FREE ZIP Code Finder
Enter ZIP Code:

*Find Info on any U.S. ZIP Code
Find ZIP+4 of Address
Address(U.S.):
Town/City:
State:
 

*Find the ZIP Code, county, and +4 of any U.S. Address
Other FREE Lookups
Town/City:
State:
County:
Area Code:
 

*Lookup ZIP Code of any city, state, county or area code
FREE Radius Search
Find all ZIP Codes

Between
And
of ZIP Code:
 

» Download the FREE Radius Finder Application

FREE Distance Calc
Calculate the distance between two U.S. or Canadian ZIP codes.

Start ZIP:
End ZIP:
 






ZIP Code API Documentation

Questions? 1-800-425-1169
Zip Code API Instructions

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 HTTP requests using the following URL and Format:

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

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

http://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.

Example JSON Response

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




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.

Example JSON Request

http://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" }




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.

Example JSON Request

http://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" }




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.

Example JSON Request

http://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" } }




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.

Example JSON Request

http://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius?zipcode=<ZIPCODE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&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 } ] }




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.

Example JSON Request

http://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius/ByLatLon?latitude=<LATITUDE>&longitude=<LONGITUDE>&maximumradius=<MAXIMUMRADIUS>&minimumradius=<MINIMUMRADIUS>&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 } ] }




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.

Example JSON Request

http://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" } ] }




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.

Example JSON Request

http://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" } }




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.

Example JSON Request

http://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" } }




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.

Input Parameters

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

Example JSON Request

http://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" ]




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).

Example JSON Request

http://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" } } }