You have items in your cart. Checkout Now.
Our Products Find ZIP+4 of Address FREE ZIP Code Finder Other FREE Lookups FREE Radius Search FREE Distance Calc |
ZIP Code API DocumentationQuestions? 1-800-425-1169Zip Code API Instructions
Making API RequestsZIP-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>
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 InformationThe API has several errors that mean different things. Below are errors you should know. Invalid API KeyThe API Key that was provided is invalid and reports that Access is denied. Example JSON Response{
"Error": "Access is denied."
}
Common Error Messages
Endpoint: Get Credit InfoThis 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
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
|
The ZIP Details API endpoint provides all information about a ZIP Code.
Parameter | Required | Definition |
---|---|---|
ZIPCODE | Y | The 5 digit U.S. ZIP Code or the 6 character Canadian Postal Code. |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetZipCodeDetails/00603?key=<YOURAPIKEY>
{
"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"
}
}
The ZIP Code Radius Finder allows you to find all the ZIP Codes that fall within a given radius of a centerpoint ZIP Code.
Parameter | Required | Definition |
---|---|---|
CODE | 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). |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius?zipcode=<ZIPCODE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&country=<COUNTRY>&key=<YOURAPIKEY>
{
"DataList": [
{
"City": "AGUADILLA",
"State": "PR",
"Latitude": 18.488773,
"Longitude": -67.147741,
"Code": "00604",
"County": "AGUADILLA",
"Distance": 2.37
},
{
"City": "AGUADILLA",
"State": "PR",
"Latitude": 18.4289,
"Longitude": -67.1538,
"Code": "00605",
"County": "AGUADILLA",
"Distance": 2.73
},
{
"City": "SAN ANTONIO",
"State": "PR",
"Latitude": 18.50189,
"Longitude": -67.097099,
"Code": "00690",
"County": "AGUADILLA",
"Distance": 3.62
}
]
}
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.
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). |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius/ByLatLon?latitude=<LATITUDE>&longitude=<LONGITUDE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&country=<COUNTRY>&key=<YOURAPIKEY>
{
"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
}
]
}
The Distance Calculator allows you to find the distance between two Latitude/Longitude Coordinates.
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. |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance?fromlatitude=<FROMLATITUDE>&fromlongitude=<FROMLONGITUDE>&tolatitude=<TOLATITUDE>&tolongitude=<TOLONGITUDE>&key=<YOURAPIKEY>
{
"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"
}
]
}
The Distance Calculator allows you to find the distance between two ZIP Codes.
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. |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance/ByZip?fromzipcode=<FROMZIPCODE>&tozipcode=<TOZIPCODE>&key=<YOURAPIKEY>
{
"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"
}
}
The Distance Calculator allows you to find the distance between a given ZIP Code and any latitude/longitude value.
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. |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance/ZipToLatLon??fromzipcode=<FROMZIPCODE>&tolatitude=<TOLATITUDE>&tolongitude=<TOLONGITUDE>&key=<YOURAPIKEY>
{
"DistanceInMiles": 1824.4926248205049,
"DistanceInKm": 2936.2418926251748,
"FromPointDetails": {
"FromLatitude": 30.480652000000,
"FromLongitude": -87.194144000000,
"FromZipCode": "32504",
"FromCity": "PENSACOLA",
"FromState": "FL",
"FromCounty": "ESCAMBIA"
}
}
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.
Parameter | Required | Definition |
---|---|---|
COUNTRY | Y | The 2 character country code (US or CA). |
STATE | N | The two character State or Province Code. |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetAllZipCodes?country=<COUNTRY>&state=<STATE>&key=<YOURAPIKEY>
[
"00501",
"00544",
"06390",
"10001",
"10002",
"10003",
"10004",
"10005",
"10006",
"10007",
"10008",
"10009",
"10010",
"10011",
"14903",
"14904",
"14905"
]
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.
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). |
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/ZipCodeOfAddress?address=<ADDRESS>&address1=<ADDRESS1>&city=<CITY>&state=<STATE>&zipcode=<ZIPCODE>&key=<YOURAPIKEY>
{
"Result": {
"Address": {
"Address2": "6406 IVY LN",
"City": "GREENBELT",
"State": "MD",
"Zip5": "20770",
"Zip4": "1441"
}
}
}