ZIP Code API Sample Code

Making API Requests

ZIP-Codes.com provides United States ZIP Code and Canadian Postal Code data over a RESTful JSON and XML based API. Registration to obtain an API Key is required.

The ZIP Codes API is configured to receive HTTPS requests using the following URL and Format:

https://api.zip-codes.com/ZipCodesAPI.svc/1.0/<endpoint>?key=<APIKEY>

For XML response data, simply append the URL with XML like this:

https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/<endpoint>?key=<YOURAPIKEY>

You must pass along your API Key for every request.
Use GET or POST verbs.
All query string parameters must be properly URL-encoded.
Use the domain name, not the IP Address as the IP address can shift.
Spaces in a query string parameters may be encoded as + for readability.

This documentation assumes that you have some experience with web requests, specifically RESTful services. It's not only important to know how to make a request, but how to handle the response data that is returned.

Error Information

The API has several errors that mean different things. Below are errors you should know.

Invalid API Key

The API Key that was provided is invalid and reports that Access is denied.

JSON XML

Example JSON Response

{
	"Error": "Access is denied."
}

Example XML Response

<Error xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<Error>Access is denied</Error>
</Error>

Common Error Messages

Error Message
Access is denied.
Credit limit has been reached.
Invalid ZIP Code.
Invalid ZIP Code or Postal Code.
Invalid Minimum Radius.
Invalid Maximum Radius.
Maximum radius must be greater than the Minimum Radius.
Invalid user data.
Invalid Latitude/Longitude.
Invalid Latitude.
Invalid Longitude.
Invalid From/To Latitude/Longitude.
Invalid From Latitude.
Invalid From Longitude.
Invalid To Latitude.
Invalid To Longitude.
Country is required.
Invalid State/Province.
User Key is required.
Address Not Found.
Invalid City.
Invalid State.
Address, City, and State are required.
Server error.
Server error: <Message>
Error Connecting to USPS Server.

Endpoint: Get Credit Info

This endpoint will show you how many API requests you have used today, how many API requests used this billing period, how many API requests remain, and when your next billing date is. The API Service has different levels with a maximum number of calls in a given month depending on your service level. This endpoint allows you to accurately gauge how many calls you have been making. Calls to this endpoint do not count against your monthly limit and may be called at any time.

Input Parameters

Parameter	Required	Definition
API KEY	Y	Your private API Key.

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetCreditInfo?key=<YOURAPIKEY>

Example JSON Response

{
	"CreditsUsedToday": 13,
	"CreditsUsedThisBillingCycle": 80,
	"RemainingCredits": 3920,
	"NextBillingDate": "2014-05-30T14:00:00"
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetCreditInfo?key=<YOURAPIKEY>

Example XML Response

<CreditInfo xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<CreditsUsedThisBillingCycle>80</CreditsUsedThisBillingCycle>
	<CreditsUsedToday>13</CreditsUsedToday>
	<NextBillingDate>2014-05-30T14:00:00</NextBillingDate>
	<RemainingCredits>3920</RemainingCredits>
</CreditInfo>

Endpoint: Quick ZIP Code Details

The quick ZIP Details API endpoint provides brief information about the ZIP Code. It is designed to be super fast and provide only the required information for most form autofills. It accepts a single ZIP Code and returns that ZIP Codes city, state, county, and latitude/longitude.

Input Parameters

Parameter	Required	Definition
ZIPCODE	Y	The 5 digit U.S. ZIP Code or the 6 character Canadian Postal Code.

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/QuickGetZipCodeDetails/00603?key=<YOURAPIKEY>

Example JSON Response

{
	"City": "AGUADILLA",
	"State": "PR",
	"Latitude": 18.458585,
	"Longitude": -67.129867,
	"ZipCode": "00603",
	"County": "AGUADILLA"
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/QuickGetZipCodeDetails/00603?key=<YOURAPIKEY>

Example XML Response

<CodeDetails xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<City>AGUADILLA</City>
	<County>AGUADILLA</County>
	<Latitude>18.458585</Latitude>
	<Longitude>-67.129867</Longitude>
	<State>PR</State>
	<ZipCode>00603</ZipCode>
</CodeDetails>

Endpoint: ZIP Code Details

The ZIP Details API endpoint provides all information about a ZIP Code.

Input Parameters

Parameter	Required	Definition
ZIPCODE	Y	The 5 digit U.S. ZIP Code or the 6 character Canadian Postal Code.

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetZipCodeDetails/00603?key=<YOURAPIKEY>

Example JSON Response

{
    "item": {
        "ID": "73096",
        "CountiesArea": "4060",
        "ZipCodePopulation": "21741",
        "HouseholdsPerZipcode": "8669.0000",
        "WhitePop": "19761",
        "BlackPop": "471",
        "HispanicPop": "1092",
        "AsianPop": "1966",
        "IndianPop": "80",
        "HawaiianPop": "55",
        "OtherPop": "387",
        "MalePop": "10292",
        "FemalePop": "11449",
        "PersonsPerHousehold": "2.49",
        "AverageHouseValue": "1000000.00",
        "IncomePerHousehold": "130071.00",
        "MedianAge": "47.50",
        "MedianAgeMale": "47.90",
        "MedianAgeFemale": "47.10",
        "AverageFamilySize": "3.06",
        "Bus03Establishments": "2304",
        "Bus03Employment": "30355",
        "Bus03PayrollQuarter1": "358631",
        "Bus03PayrollAnnual": "1683558",
        "Bus03EmploymentFlag": " ",
        "CBSAPop2003": null,
        "CBSADivPop2003": "9818605",
        "DeliveryActive": "10881",
        "DeliveryBusiness": "1473",
        "DeliveryResidential": "9501",
        "DeliverySpecial": "9501",
        "DeliveryBox": "0",
        "DeliverySFDU": "6938",
        "DeliveryMFDU": "2543",
        "PopulationEstimate": "23657",
        "_109thDistrict": "0",
        "_109thArea": "0",
        "_110thDistrict": "01|28|30|33",
        "_110thArea": "28089.47|218.45|135.94|288.58",
        "GrowthRank": "0",
        "GrowthHousingUnits2003": "0",
        "GrowthHousingUnits2004": "0",
        "GrowthIncreaseNumber": "0",
        "GrowthIncreasePercentage": "0.00",
        "Latitude": "34.103131",
        "Longitude": "-118.416253",
        "Elevation": "267.00",
        "AreaLand": "10.126000",
        "AreaWater": "0.061000",
        "Primary": "P",
        "State": "CA",
        "CityType": "P",
        "CityAliasType": null,
        "Classification": " ",
        "ZipCode": "90210",
        "CityAliasAbbr": null,
        "AreaCode": "310/424",
        "AreaCodeTemp": "310/424",
        "AreaCodeTest": null,
        "City": "BEVERLY HILLS",
        "CityAliasName": "BEVERLY HILLS",
        "CountyName": "LOS ANGELES",
        "CountyFIPS": "037",
        "StateFIPS": "06",
        "CountyANSI": "037",
        "StateANSI": "06",
        "TimeZone": "8",
        "DayLightSaving": "Y",
        "MSA": "4472",
        "PMSA": "4480",
        "PMSAName": "Los Angeles-Long Beach, CA PMSA",
        "CSA": "348",
        "CSAName": "Los Angeles-Long Beach, CA",
        "CBSA": "31080",
        "CBSA_DIV": "31084",
        "CBSA_DIV_Name": "Los Angeles-Long Beach-Glendale, CA",
        "CBSA_Type": "Metro",
        "CBSA_Name": "Los Angeles-Long Beach-Anaheim, CA",
        "MSAName": "Los Angeles-Riverside-Orange County, CA",
        "Region": "West",
        "Division": "Pacific",
        "MailingName": "Y",
        "MultiCounty": " ",
        "Prev": "90209",
        "Next": "90211",
        "CityStateKey": "Z20259",
        "PreferredLastLineKey": "Z20259",
        "PreferredLastLineName": "BEVERLY HILLS",
        "IntroDateZIP": "<2004-10",
        "IntroDateAlias": "<2004-10",
        "FacilityCode": "P",
        "CityDeliveryIndicator": "Y",
        "CarrierRouteRateSortation": "B",
        "FinanceNumber": "050666",
        "UniqueZIPName": null,
        "MixedCaseCity": "Beverly Hills",
        "MixedCaseAlias": "Beverly Hills"
    }
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetZipCodeDetails/00603?key=<YOURAPIKEY>

Example XML Response

<item>
  <ID>73096</ID>
  <CountiesArea>4060</CountiesArea>
  <ZipCodePopulation>21741</ZipCodePopulation>
  <HouseholdsPerZipcode>8669.0000</HouseholdsPerZipcode>
  <WhitePop>19761</WhitePop>
  <BlackPop>471</BlackPop>
  <HispanicPop>1092</HispanicPop>
  <AsianPop>1966</AsianPop>
  <IndianPop>80</IndianPop>
  <HawaiianPop>55</HawaiianPop>
  <OtherPop>387</OtherPop>
  <MalePop>10292</MalePop>
  <FemalePop>11449</FemalePop>
  <PersonsPerHousehold>2.49</PersonsPerHousehold>
  <AverageHouseValue>1000000.00</AverageHouseValue>
  <IncomePerHousehold>130071.00</IncomePerHousehold>
  <MedianAge>47.50</MedianAge>
  <MedianAgeMale>47.90</MedianAgeMale>
  <MedianAgeFemale>47.10</MedianAgeFemale>
  <AverageFamilySize>3.06</AverageFamilySize>
  <Bus03Establishments>2304</Bus03Establishments>
  <Bus03Employment>30355</Bus03Employment>
  <Bus03PayrollQuarter1>358631</Bus03PayrollQuarter1>
  <Bus03PayrollAnnual>1683558</Bus03PayrollAnnual>
  <Bus03EmploymentFlag></Bus03EmploymentFlag>
  <CBSAPop2003></CBSAPop2003>
  <CBSADivPop2003>9818605</CBSADivPop2003>
  <DeliveryActive>10881</DeliveryActive>
  <DeliveryBusiness>1473</DeliveryBusiness>
  <DeliveryResidential>9501</DeliveryResidential>
  <DeliverySpecial>9501</DeliverySpecial>
  <DeliveryBox>0</DeliveryBox>
  <DeliverySFDU>6938</DeliverySFDU>
  <DeliveryMFDU>2543</DeliveryMFDU>
  <PopulationEstimate>23657</PopulationEstimate>
  <_109thDistrict>0</_109thDistrict>
  <_109thArea>0</_109thArea>
  <_110thDistrict>01|28|30|33</_110thDistrict>
  <_110thArea>28089.47|218.45|135.94|288.58</_110thArea>
  <GrowthRank>0</GrowthRank>
  <GrowthHousingUnits2003>0</GrowthHousingUnits2003>
  <GrowthHousingUnits2004>0</GrowthHousingUnits2004>
  <GrowthIncreaseNumber>0</GrowthIncreaseNumber>
  <GrowthIncreasePercentage>0.00</GrowthIncreasePercentage>
  <Latitude>34.103131</Latitude>
  <Longitude>-118.416253</Longitude>
  <Elevation>267.00</Elevation>
  <AreaLand>10.126000</AreaLand>
  <AreaWater>0.061000</AreaWater>
  <Primary>P</Primary>
  <State>CA</State>
  <CityType>P</CityType>
  <CityAliasType></CityAliasType>
  <Classification></Classification>
  <ZipCode>90210</ZipCode>
  <CityAliasAbbr></CityAliasAbbr>
  <AreaCode>310/424</AreaCode>
  <AreaCodeTemp>310/424</AreaCodeTemp>
  <AreaCodeTest></AreaCodeTest>
  <City>BEVERLY HILLS</City>
  <CityAliasName>BEVERLY HILLS</CityAliasName>
  <CountyName>LOS ANGELES</CountyName>
  <CountyFIPS>037</CountyFIPS>
  <StateFIPS>06</StateFIPS>
  <CountyANSI>037</CountyANSI>
  <StateANSI>06</StateANSI>
  <TimeZone>8</TimeZone>
  <DayLightSaving>Y</DayLightSaving>
  <MSA>4472</MSA>
  <PMSA>4480</PMSA>
  <PMSAName>Los Angeles-Long Beach, CA PMSA</PMSAName>
  <CSA>348</CSA>
  <CSAName>Los Angeles-Long Beach, CA</CSAName>
  <CBSA>31080</CBSA>
  <CBSA_DIV>31084</CBSA_DIV>
  <CBSA_DIV_Name>Los Angeles-Long Beach-Glendale, CA</CBSA_DIV_Name>
  <CBSA_Type>Metro</CBSA_Type>
  <CBSA_Name>Los Angeles-Long Beach-Anaheim, CA</CBSA_Name>
  <MSAName>Los Angeles-Riverside-Orange County, CA</MSAName>
  <Region>West</Region>
  <Division>Pacific</Division>
  <MailingName>Y</MailingName>
  <MultiCounty></MultiCounty>
  <Prev>90209</Prev>
  <Next>90211</Next>
  <CityStateKey>Z20259</CityStateKey>
  <PreferredLastLineKey>Z20259</PreferredLastLineKey>
  <PreferredLastLineName>BEVERLY HILLS</PreferredLastLineName>
  <IntroDateZIP><2004-10</IntroDateZIP>
  <IntroDateAlias><2004-10</IntroDateAlias>
  <FacilityCode>P</FacilityCode>
  <CityDeliveryIndicator>Y</CityDeliveryIndicator>
  <CarrierRouteRateSortation>B</CarrierRouteRateSortation>
  <FinanceNumber>050666</FinanceNumber>
  <UniqueZIPName></UniqueZIPName>
  <MixedCaseCity>Beverly Hills</MixedCaseCity>
  <MixedCaseAlias>Beverly Hills</MixedCaseAlias>
</item>

Endpoint: ZIP Code Radius Finder

The ZIP Code Radius Finder allows you to find all the ZIP Codes that fall within a given radius of a centerpoint ZIP Code.

Input Parameters

Parameter	Required	Definition
ZIPCODE	Y	The 5 digit U.S. ZIP Code or the 6 character Canadian Postal Code.
MAXIMUMRADIUS	N	The maximum number of miles to look for in the radius. Default is 50.
MINIMUMRADIUS	N	The minimum number of miles to look for in the radius. Default is 0.
COUNTRY	N	The country to limit results to. Values: US (United States), CA (Canada), or ALL (default).

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius?zipcode=<ZIPCODE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&country=<COUNTRY>&key=<YOURAPIKEY>

Example JSON Response

{
    "DataList": [
        {
            "City": "AGUADILLA",
            "State": "PR",
            "Latitude": 18.488773,
            "Longitude": -67.147741,
            "ZipCode": "00604",
            "County": "AGUADILLA",
            "Distance": 2.37
        },
        {
            "City": "AGUADILLA",
            "State": "PR",
            "Latitude": 18.4289,
            "Longitude": -67.1538,
            "ZipCode": "00605",
            "County": "AGUADILLA",
            "Distance": 2.73
        },
        {
            "City": "SAN ANTONIO",
            "State": "PR",
            "Latitude": 18.50189,
            "Longitude": -67.097099,
            "ZipCode": "00690",
            "County": "AGUADILLA",
            "Distance": 3.62
        }
    ]
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/FindZipCodesInRadius/?zipcode=<ZIPCODE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&country=<COUNTRY>&key=<YOURAPIKEY>

Example XML Response

<Result xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<DataList>
		<CodeDetails>
			<City>AGUADILLA</City>
			<County>AGUADILLA</County>
			<Distance>2.37</Distance>
			<Latitude>18.488773000000</Latitude>
			<Longitude>-67.147741000000</Longitude>
			<State>PR</State>
			<ZipCode>00604</ZipCode>
		</CodeDetails>
		<CodeDetails>
			<City>AGUADILLA</City>
			<County>AGUADILLA</County>
			<Distance>2.73</Distance>
			<Latitude>18.428900000000</Latitude>
			<Longitude>-67.153800000000</Longitude>
			<State>PR</State>
			<ZipCode>00605</ZipCode>
		</CodeDetails>
		<CodeDetails>
			<City>SAN ANTONIO</City>
			<County>AGUADILLA</County>
			<Distance>3.62</Distance>
			<Latitude>18.501890000000</Latitude>
			<Longitude>-67.097099000000</Longitude>
			<State>PR</State>
			<ZipCode>00690</ZipCode>
		</CodeDetails>
	</DataList>
</Result>

Endpoint: ZIP Code Radius Finder By Lat/Lon

The ZIP Code Radius Finder allows you to find all the ZIP Codes that fall within a given radius of a Latitude/Longitude centerpoint that you specify.

Input Parameters

Parameter	Required	Definition
LATITUDE	Y	The Latitude to use as the centerpoint for the radius search.
LONGITUDE	Y	The Longitude to use as the centerpoint for the radius search.
MAXIMUMRADIUS	N	The maximum number of miles to look for in the radius. Default is 50.
MINIMUMRADIUS	N	The minimum number of miles to look for in the radius. Default is 0.
COUNTRY	N	The country to limit results to. Values: US (United States), CA (Canada), or ALL (default).

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius/ByLatLon?latitude=<LATITUDE>&longitude=<LONGITUDE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&country=<COUNTRY>&key=<YOURAPIKEY>

Example JSON Response

{
    "DataList": [
        {
            "City": "AGUADILLA",
            "State": "PR",
            "Latitude": 18.488773,
            "Longitude": -67.147741,
            "ZipCode": "00604",
            "County": "AGUADILLA",
            "Distance": 2.37
        },
        {
            "City": "AGUADILLA",
            "State": "PR",
            "Latitude": 18.4289,
            "Longitude": -67.1538,
            "ZipCode": "00605",
            "County": "AGUADILLA",
            "Distance": 2.73
        },
        {
            "City": "SAN ANTONIO",
            "State": "PR",
            "Latitude": 18.50189,
            "Longitude": -67.097099,
            "ZipCode": "00690",
            "County": "AGUADILLA",
            "Distance": 3.62
        }
    ]
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/FindZipCodesInRadius/ByLatLon?latitude=<LATITUDE>&longitude=<LONGITUDE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&country=<COUNTRY>&key=<YOURAPIKEY>

Example XML Response

<Result xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<DataList>
		<CodeDetails>
			<City>AGUADILLA</City>
			<County>AGUADILLA</County>
			<Distance>2.37</Distance>
			<Latitude>18.488773000000</Latitude>
			<Longitude>-67.147741000000</Longitude>
			<State>PR</State>
			<ZipCode>00604</ZipCode>
		</CodeDetails>
		<CodeDetails>
			<City>AGUADILLA</City>
			<County>AGUADILLA</County>
			<Distance>2.73</Distance>
			<Latitude>18.428900000000</Latitude>
			<Longitude>-67.153800000000</Longitude>
			<State>PR</State>
			<ZipCode>00605</ZipCode>
		</CodeDetails>
		<CodeDetails>
			<City>SAN ANTONIO</City>
			<County>AGUADILLA</County>
			<Distance>3.62</Distance>
			<Latitude>18.501890000000</Latitude>
			<Longitude>-67.097099000000</Longitude>
			<State>PR</State>
			<ZipCode>00690</ZipCode>
		</CodeDetails>
	</DataList>
</Result>

Endpoint: Calculate Distance By Lat/Lon

The Distance Calculator allows you to find the distance between two Latitude/Longitude Coordinates.

Input Parameters

Parameter	Required	Definition
FROMLATITUDE	Y	The Latitude to use as the From point in the distance calculation.
FROMLONGITUDE	Y	The Longitude to use as the From point in the distance calculation.
TOLATITUDE	Y	The Latitude to use as the To point in the distance calculation.
TOLONGITUDE	Y	The Longitude to use as the To point in the distance calculation.

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance?fromlatitude=<FROMLATITUDE>&fromlongitude=<FROMLONGITUDE>&tolatitude=<TOLATITUDE>&tolongitude=<TOLONGITUDE>&key=<YOURAPIKEY>

Example JSON Response

{
	"DistanceInMiles": 16.635073383968564,
	"DistanceInKm": 26.77160690726711,
	"FromPointDetails": {
		"FromLatitude": 13.263500000000,
		"FromLongitude": 144.669700000000,
		"FromZipCode": "96916",
		"FromCity": "MERIZO",
		"FromState": "GU",
		"FromCounty": "GUAM"
	},
	"ToPointDetailsList": [
		{
			"ToLatitude": 13.468600000000,
			"ToLongitude": 144.798900000000,
			"ToZipCode": "96913",
			"ToCity": "BARRIGADA",
			"ToState": "GU",
			"ToCounty": "GUAM"
		},
		{
			"ToLatitude": 13.468600000000,
			"ToLongitude": 144.798900000000,
			"ToZipCode": "96921",
			"ToCity": "BARRIGADA",
			"ToState": "GU",
			"ToCounty": "GUAM"
		}
	]
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/CalculateDistance?fromlatitude=<FROMLATITUDE>&fromlongitude=<FROMLONGITUDE>&tolatitude=<TOLATITUDE>&tolongitude=<TOLONGITUDE>&key=<YOURAPIKEY>

Example XML Response

<DistanceDetails xmlns="https://schemas.datacontract.org/2004/07/ZipCodesAPI.Core.DataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<DistanceInKm>26.77160690726711</DistanceInKm>
	<DistanceInMiles>16.635073383968564</DistanceInMiles>
	<FromPointDetails>
		<FromCity>MERIZO</FromCity>
		<FromCounty>GUAM</FromCounty>
		<FromLatitude>13.263500000000</FromLatitude>
		<FromLongitude>144.669700000000</FromLongitude>
		<FromState>GU</FromState>
		<FromZipCode>96916</FromZipCode>
	</FromPointDetails>
	<ToPointDetailsList>
		<ToPointDetails>
			<ToCity>BARRIGADA</ToCity>
			<ToCounty>GUAM</ToCounty>
			<ToLatitude>13.468600000000</ToLatitude>
			<ToLongitude>144.798900000000</ToLongitude>
			<ToState>GU</ToState>
			<ToZipCode>96913</ToZipCode>
		</ToPointDetails>
		<ToPointDetails>
			<ToCity>BARRIGADA</ToCity>
			<ToCounty>GUAM</ToCounty>
			<ToLatitude>13.468600000000</ToLatitude>
			<ToLongitude>144.798900000000</ToLongitude>
			<ToState>GU</ToState>
			<ToZipCode>96921</ToZipCode>
		</ToPointDetails>
	</ToPointDetailsList>
</DistanceDetails>

Endpoint: Calculate Distance By ZIP Code

The Distance Calculator allows you to find the distance between two ZIP Codes.

Input Parameters

Parameter	Required	Definition
FROMZIPCODE	Y	The ZIP Code to use as the From point in the distance calculation.
TOZIPCODE	Y	The ZIP Code to use as the To point in the distance calculation.

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance/ByZip?fromzipcode=<FROMZIPCODE>&tozipcode=<TOZIPCODE>&key=<YOURAPIKEY>

Example JSON Response

{
  "DistanceInMiles": 1835.096876886239,
  "DistanceInKm": 2953.3078148063778,
  "FromPointDetails": {
    "FromLatitude": 30.480652000000,
    "FromLongitude": -87.194144000000,
    "FromZipCode": "32504",
    "FromCity": "PENSACOLA",
    "FromState": "FL",
    "FromCounty": "ESCAMBIA"
  },
  "ToPointDetails": {
    "ToLatitude": 34.103131000000,
    "ToLongitude": -118.416253000000,
    "ToZipCode": "90210",
    "ToCity": "BEVERLY HILLS",
    "ToState": "CA",
    "ToCounty": "LOS ANGELES"
  }
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/CalculateDistance/ByZip?fromzipcode=<FROMZIPCODE>&tozipcode=<TOZIPCODE>&key=<YOURAPIKEY>

Example XML Response

<DistanceDetails xmlns="https://schemas.datacontract.org/2004/07/ZipCodesAPI.Core.DataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<DistanceInKm>2953.3078148063778</DistanceInKm>
	<DistanceInMiles>1835.096876886239</DistanceInMiles&rt;
	<FromPointDetails>
		<FromCity>PENSACOLA</FromCity>
		<FromCounty>ESCAMBIA</FromCounty>
		<FromLatitude>30.480652000000</FromLatitude>
		<FromLongitude>-87.194144000000</FromLongitude>
		<FromState>FL</FromState>
		<FromZipCode>32504</FromZipCode>
	</FromPointDetails>
	<ToPointDetails>
		<ToCity>BEVERLY HILLS</ToCity>
		<ToCounty>LOS ANGELES</ToCounty>
		<ToLatitude>34.103131000000</ToLatitude>
		<ToLongitude>-118.416253000000</ToLongitude>
		<ToState>CA</ToState>
		<ToZipCode>90210</ToZipCode>
	</ToPointDetails>
</DistanceDetails>

Endpoint: Calculate Distance by ZIP Code to Lat/Lon

The Distance Calculator allows you to find the distance between a given ZIP Code and any latitude/longitude value.

Input Parameters

Parameter	Required	Definition
FROMZIPCODE	Y	The ZIP COde to use as the From point in the distance calculation.
TOLATITUDE	Y	The Latitude to use as the To point in the distance calculation.
TOLONGITUDE	Y	The Longtude to use as the To point in the distance calculation.

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance/ZipToLatLon??fromzipcode=<FROMZIPCODE>&tolatitude=<TOLATITUDE>&tolongitude=<TOLONGITUDE>&key=<YOURAPIKEY>

Example JSON Response

{
  "DistanceInMiles": 1824.4926248205049,
  "DistanceInKm": 2936.2418926251748,
  "FromPointDetails": {
    "FromLatitude": 30.480652000000,
    "FromLongitude": -87.194144000000,
    "FromZipCode": "32504",
    "FromCity": "PENSACOLA",
    "FromState": "FL",
    "FromCounty": "ESCAMBIA"
  }
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/CalculateDistance/ZipToLatLon??fromzipcode=<FROMZIPCODE>&tolatitude=<TOLATITUDE>&tolongitude=<TOLONGITUDE>&key=<YOURAPIKEY>

Example XML Response

<DistanceDetails xmlns="https://schemas.datacontract.org/2004/07/ZipCodesAPI.Core.DataContracts" xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<DistanceInKm>2936.2418926251748</DistanceInKm>
	<DistanceInMiles>1824.4926248205049</DistanceInMiles>
	<FromPointDetails>
		<FromCity>PENSACOLA</FromCity>
		<FromCounty>ESCAMBIA</FromCounty>
		<FromLatitude>30.480652000000</FromLatitude>
		<FromLongitude>-87.194144000000</FromLongitude>
		<FromState>FL</FromState>
		<FromZipCode>32504</FromZipCode>
	</FromPointDetails>
</DistanceDetails>

Endpoint: Get All ZIP Codes

The Get All ZIP Codes endpoint allows you to retrieve a simple list of all ZIP Codes within the given Country and State selected. NOTE: Canadian Provinces will return only the 3 character FSAs which are valid not a full list of 6 character Postal Codes.

Input Parameters

Parameter	Required	Definition
COUNTRY	Y	The 2 character country code (US or CA).
STATE	N	The two character State or Province Code.

JSON XML CA JSON CA XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetAllZipCodes?country=<COUNTRY>&state=<STATE>&key=<YOURAPIKEY>

Example JSON Response

[
	"00501",
	"00544",
	"06390",
	"10001",
	"10002",
	"10003",
	"10004",
	"10005",
	"10006",
	"10007",
	"10008",
	"10009",
	"10010",
	"10011",
	"14903",
	"14904",
	"14905"
]

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetAllZipCodes?country=<COUNTRY>&state=<STATE>&key=<YOURAPIKEY>

Example XML Response

<ZipCodesList xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<ZipCode>00501</ZipCode>
	<ZipCode>00544</ZipCode>
	<ZipCode>06390</ZipCode>
	<ZipCode>10001</ZipCode>
	<ZipCode>10002</ZipCode>
	<ZipCode>10003</ZipCode>
	<ZipCode>10004</ZipCode>
	<ZipCode>10005</ZipCode>
	<ZipCode>10006</ZipCode>
	<ZipCode>10007</ZipCode>
	<ZipCode>10008</ZipCode>
	<ZipCode>10009</ZipCode>
	<ZipCode>10010</ZipCode>
	<ZipCode>10011</ZipCode>
	<ZipCode>14904</ZipCode>
	<ZipCode>14905</ZipCode>
</ZipCodesList>

Example Canadian JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetAllZipCodes?country=CA&state=<STATE>&key=<YOURAPIKEY>

Example Canadian JSON Response

[
  "B0C",
  "B0E",
  "B0H",
  "B0J",
  "B0K",
  "B0L",
  "B0M",
  "B0N",
  "B0P",
  "B0R",
  "B0S",
  "B0T",
  "B0V",
  "B0W",
  "B1A",
  "B1B",
  "B1C",
  "B1E",
  "B1G",
  "B1H",
  "B1J",
  "B1K",
  "B1L",
  "B1M",
  "B1N",
  "B1P",
  "B1R",
  "B1S",
  "B1T",
  "B1V",
  "B1W",
  "B1X",
  "B1Y",
  "B2A",
  "B2C",
  "B2E",
  "B2G",
  "B2H",
  "B2J"
]

Example Canadian XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetAllZipCodes?country=CA&state=<STATE>&key=<YOURAPIKEY>

Example Canadian XML Response

<ZipCodesList xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
	<ZipCode>B0C</ZipCode>
	<ZipCode>B0E</ZipCode>
	<ZipCode>B0H</ZipCode>
	<ZipCode>B0J</ZipCode>
	<ZipCode>B0K</ZipCode>
	<ZipCode>B0L</ZipCode>
	<ZipCode>B0M</ZipCode>
	<ZipCode>B0N</ZipCode>
	<ZipCode>B0P</ZipCode>
	<ZipCode>B0R</ZipCode>
	<ZipCode>B0S</ZipCode>
	<ZipCode>B0T</ZipCode>
	<ZipCode>B0V</ZipCode>
	<ZipCode>B0W</ZipCode>
	<ZipCode>B1A</ZipCode>
	<ZipCode>B1B</ZipCode>
	<ZipCode>B1C</ZipCode>
	<ZipCode>B1E</ZipCode>
	<ZipCode>B1G</ZipCode>
	<ZipCode>B1H</ZipCode>
	<ZipCode>B1J</ZipCode>
	<ZipCode>B1K</ZipCode>
	<ZipCode>B1L</ZipCode>
	<ZipCode>B1M</ZipCode>
	<ZipCode>B1N</ZipCode>
	<ZipCode>B1P</ZipCode>
	<ZipCode>B1R</ZipCode>
	<ZipCode>B1S</ZipCode>
	<ZipCode>B1T</ZipCode>
	<ZipCode>B1V</ZipCode>
	<ZipCode>B1W</ZipCode>
	<ZipCode>B1X</ZipCode>
	<ZipCode>B1Y</ZipCode>
	<ZipCode>B2A</ZipCode>
	<ZipCode>B2C</ZipCode>
	<ZipCode>B2E</ZipCode>
	<ZipCode>B2G</ZipCode>
	<ZipCode>B2H</ZipCode>
	<ZipCode>B2J</ZipCode>
</ZipCodesList>

Endpoint: Get ZIP Code of Address

The ZIP Code of Address endpoint allows you to provide a street address, city, and state and returns the ZIP+4 that this address falls in. This feature is limited to U.S. Addresses only.

Input Parameters

Parameter	Required	Definition
ADDRESS	Y	The Street Number and Street Name of the address. Ex: 121 Main St.
ADDRESS1	N	Used to provide Apartment or Suite Number (if available).
CITY	Y	The city for which this address is in.
STATE	Y	The two character State Code.
ZIPCODE	N	The ZIP Code of the address (if known).

JSON XML

Example JSON Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/ZipCodeOfAddress?address=<ADDRESS>&address1=<ADDRESS1>&city=<CITY>&state=<STATE>&zipcode=<ZIPCODE>&key=<YOURAPIKEY>

Example JSON Response

{
    "Result": {
        "Address": {
            "Address2": "6406 IVY LN",
            "City": "GREENBELT",
            "State": "MD",
            "Zip5": "20770",
            "Zip4": "1441"
        }
    }
}

Example XML Request


				https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/ZipCodeOfAddress?address=<ADDRESS>&address1=<ADDRESS1>&city=<CITY>&state=<STATE>&zipcode=<ZIPCODE>&key=<YOURAPIKEY>

Example XML Response

<Result>
	<Address>
		Address2>6406 IVY LN</Address2>
		<City>GREENBELT</City>
		<State>MD</State>
		<Zip5>20770</Zip5>
		<Zip4>1441</Zip4>
	</Address>
</Result>