ZIP Code API Reference Documentation

ZIP Code API Reference

Complete technical documentation for all endpoints, parameters, responses, and error codes.

Complete Field Dictionary
8 Documented Endpoints
Detailed Error Codes
View Quick Start Guide | Get Your API Key |
8
REST Endpoints
40+
Response Fields
2
Output Formats
7
Time Zone Codes

Making API Requests

Getting Started: 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.

Base URL Format

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

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

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>

Important Requirements

  • 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 (IP can change)
  • Spaces in query string parameters may be encoded as + for readability
Note: This documentation assumes you have some experience with web requests, specifically RESTful services. It's important to know not only how to make a request, but how to handle the response data that is returned.

Error Information

The API returns structured error messages to help you troubleshoot issues. Below are the errors you should know.

Error Response Format

{
    "Error": "Access is denied."
}
<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.

Get Credit Info GET

Monitor your API usage and remaining credits for the current billing period.

Important: Calls to this endpoint do not count against your monthly limit and may be called at any time.

Input Parameters

Parameter Required Definition
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetCreditInfo?key=<YOURAPIKEY>
Response
{
    "CreditsUsedToday": 13,
    "CreditsUsedThisBillingCycle": 80,
    "RemainingCredits": 3920,
    "NextBillingDate": "2014-05-30T14:00:00"
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetCreditInfo?key=<YOURAPIKEY>
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>

Quick ZIP Code Details GET

Get essential ZIP Code information fast - perfect for form autofills and quick lookups.

Performance: This endpoint is optimized for speed, returning only city, state, county, and coordinates.

Input Parameters

Parameter Required Definition
zipcode Required 5-digit U.S. ZIP Code or 6-character Canadian Postal Code
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/QuickGetZipCodeDetails/00603?key=<YOURAPIKEY>
Response
{
    "City": "AGUADILLA",
    "State": "PR",
    "Latitude": 18.458585,
    "Longitude": -67.129867,
    "ZipCode": "00603",
    "County": "AGUADILLA"
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/QuickGetZipCodeDetails/00603?key=<YOURAPIKEY>
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>

ZIP Code Details GET

Retrieve comprehensive demographic, geographic, and statistical data for any ZIP Code.

Input Parameters

Parameter Required Definition
zipcode Required 5-digit U.S. ZIP Code or 6-character Canadian Postal Code
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetZipCodeDetails/90210?key=<YOURAPIKEY>
Response (Truncated for Display)
{
    "item": {
        "ZipCode": "90210",
        "City": "BEVERLY HILLS",
        "State": "CA",
        "County": "LOS ANGELES",
        "Latitude": "34.103131",
        "Longitude": "-118.416253",
        "ZipCodePopulation": "21741",
        "HouseholdsPerZipcode": "8669.0000",
        "MedianAge": "47.50",
        "AverageHouseValue": "1000000.00",
        "IncomePerHousehold": "130071.00",
        "TimeZone": "8",
        "AreaCode": "310/424"
        // ... 70+ additional fields
    }
}
Note: This endpoint returns 80+ data fields including demographics, business statistics, and geographic information. The response has been truncated for display purposes.
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetZipCodeDetails/90210?key=<YOURAPIKEY>
Response (Truncated for Display)
<item>
    <ZipCode>90210</ZipCode>
    <City>BEVERLY HILLS</City>
    <State>CA</State>
    <County>LOS ANGELES</County>
    <Latitude>34.103131</Latitude>
    <Longitude>-118.416253</Longitude>
    <!-- 70+ additional fields -->
</item>

ZIP Code Radius Finder GET

Find all ZIP Codes within a specified radius of a center ZIP Code.

Input Parameters

Parameter Required Definition
zipcode Required Center point ZIP Code or Postal Code
maximumradius Optional Maximum radius in miles (default: 50)
minimumradius Optional Minimum radius in miles (default: 0)
country Optional US, CA, or ALL (default: ALL)
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius?zipcode=00603&maximumradius=5&key=<YOURAPIKEY>
Response
{
    "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
        }
    ]
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/FindZipCodesInRadius?zipcode=00603&maximumradius=5&key=<YOURAPIKEY>
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.488773</Latitude>
            <Longitude>-67.147741</Longitude>
            <State>PR</State>
            <Code>00604</Code>
        </CodeDetails>
    </DataList>
</Result>

ZIP Code Radius Finder By Lat/Lon GET

Find all ZIP Codes within a radius of any latitude/longitude coordinate.

Input Parameters

Parameter Required Definition
latitude Required Center point latitude coordinate
longitude Required Center point longitude coordinate
maximumradius Optional Maximum radius in miles (default: 50)
minimumradius Optional Minimum radius in miles (default: 0)
country Optional US, CA, or ALL (default: ALL)
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/FindZipCodesInRadius/ByLatLon?latitude=18.458585&longitude=-67.129867&maximumradius=5&key=<YOURAPIKEY>
Response
{
    "DataList": [
        {
            "City": "AGUADILLA",
            "State": "PR",
            "Latitude": 18.488773,
            "Longitude": -67.147741,
            "ZipCode": "00604",
            "County": "AGUADILLA",
            "Distance": 2.37
        }
    ]
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/FindZipCodesInRadius/ByLatLon?latitude=18.458585&longitude=-67.129867&maximumradius=5&key=<YOURAPIKEY>
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.488773</Latitude>
            <Longitude>-67.147741</Longitude>
            <State>PR</State>
            <ZipCode>00604</ZipCode>
        </CodeDetails>
    </DataList>
</Result>

Calculate Distance By Lat/Lon GET

Calculate the distance between two latitude/longitude coordinate pairs.

Input Parameters

Parameter Required Definition
fromlatitude Required Starting point latitude
fromlongitude Required Starting point longitude
tolatitude Required Destination point latitude
tolongitude Required Destination point longitude
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance?fromlatitude=13.2635&fromlongitude=144.6697&tolatitude=13.4686&tolongitude=144.7989&key=<YOURAPIKEY>
Response
{
    "DistanceInMiles": 16.635073,
    "DistanceInKm": 26.771607,
    "FromPointDetails": {
        "FromLatitude": 13.2635,
        "FromLongitude": 144.6697,
        "FromZipCode": "96916",
        "FromCity": "MERIZO",
        "FromState": "GU",
        "FromCounty": "GUAM"
    },
    "ToPointDetailsList": [{
        "ToLatitude": 13.4686,
        "ToLongitude": 144.7989,
        "ToZipCode": "96913",
        "ToCity": "BARRIGADA",
        "ToState": "GU",
        "ToCounty": "GUAM"
    }]
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/CalculateDistance?fromlatitude=13.2635&fromlongitude=144.6697&tolatitude=13.4686&tolongitude=144.7989&key=<YOURAPIKEY>
Response
<DistanceDetails xmlns="https://schemas.datacontract.org/2004/07/ZipCodesAPI.Core.DataContracts">
    <DistanceInKm>26.771607</DistanceInKm>
    <DistanceInMiles>16.635073</DistanceInMiles>
    <FromPointDetails>
        <FromCity>MERIZO</FromCity>
        <FromCounty>GUAM</FromCounty>
        <FromLatitude>13.2635</FromLatitude>
        <FromLongitude>144.6697</FromLongitude>
        <FromState>GU</FromState>
        <FromZipCode>96916</FromZipCode>
    </FromPointDetails>
</DistanceDetails>

Calculate Distance By ZIP Code GET

Calculate the distance between two ZIP Codes.

Input Parameters

Parameter Required Definition
fromzipcode Required Starting ZIP Code
tozipcode Required Destination ZIP Code
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance/ByZip?fromzipcode=32504&tozipcode=90210&key=<YOURAPIKEY>
Response
{
    "DistanceInMiles": 1835.096877,
    "DistanceInKm": 2953.307815,
    "FromPointDetails": {
        "FromLatitude": 30.480652,
        "FromLongitude": -87.194144,
        "FromZipCode": "32504",
        "FromCity": "PENSACOLA",
        "FromState": "FL",
        "FromCounty": "ESCAMBIA"
    },
    "ToPointDetails": {
        "ToLatitude": 34.103131,
        "ToLongitude": -118.416253,
        "ToZipCode": "90210",
        "ToCity": "BEVERLY HILLS",
        "ToState": "CA",
        "ToCounty": "LOS ANGELES"
    }
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/CalculateDistance/ByZip?fromzipcode=32504&tozipcode=90210&key=<YOURAPIKEY>
Response
<DistanceDetails xmlns="https://schemas.datacontract.org/2004/07/ZipCodesAPI.Core.DataContracts">
    <DistanceInKm>2953.307815</DistanceInKm>
    <DistanceInMiles>1835.096877</DistanceInMiles>
    <FromPointDetails>
        <FromCity>PENSACOLA</FromCity>
        <FromCounty>ESCAMBIA</FromCounty>
        <FromState>FL</FromState>
        <FromZipCode>32504</FromZipCode>
    </FromPointDetails>
    <ToPointDetails>
        <ToCity>BEVERLY HILLS</ToCity>
        <ToCounty>LOS ANGELES</ToCounty>
        <ToState>CA</ToState>
        <ToZipCode>90210</ToZipCode>
    </ToPointDetails>
</DistanceDetails>

Calculate Distance ZIP to Lat/Lon GET

Calculate the distance from a ZIP Code to any latitude/longitude coordinate.

Input Parameters

Parameter Required Definition
fromzipcode Required Starting ZIP Code
tolatitude Required Destination latitude
tolongitude Required Destination longitude
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/CalculateDistance/ZipToLatLon?fromzipcode=32504&tolatitude=34.103131&tolongitude=-118.416253&key=<YOURAPIKEY>
Response
{
    "DistanceInMiles": 1824.492625,
    "DistanceInKm": 2936.241893,
    "FromPointDetails": {
        "FromLatitude": 30.480652,
        "FromLongitude": -87.194144,
        "FromZipCode": "32504",
        "FromCity": "PENSACOLA",
        "FromState": "FL",
        "FromCounty": "ESCAMBIA"
    }
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/CalculateDistance/ZipToLatLon?fromzipcode=32504&tolatitude=34.103131&tolongitude=-118.416253&key=<YOURAPIKEY>
Response
<DistanceDetails xmlns="https://schemas.datacontract.org/2004/07/ZipCodesAPI.Core.DataContracts">
    <DistanceInKm>2936.241893</DistanceInKm>
    <DistanceInMiles>1824.492625</DistanceInMiles>
    <FromPointDetails>
        <FromCity>PENSACOLA</FromCity>
        <FromCounty>ESCAMBIA</FromCounty>
        <FromState>FL</FromState>
        <FromZipCode>32504</FromZipCode>
    </FromPointDetails>
</DistanceDetails>

Get All ZIP Codes GET

Retrieve a complete list of ZIP Codes for a specific country and/or state.

Note: Canadian provinces return only the 3-character FSAs (Forward Sortation Areas), not full 6-character Postal Codes.

Input Parameters

Parameter Required Definition
country Required 2-character country code (US or CA)
state Optional 2-character state or province code
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetAllZipCodes?country=US&state=NY&key=<YOURAPIKEY>
Response (Truncated)
["00501", "00544", "06390", "10001", "10002", "10003", "14903", "14904", "14905"]
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/GetAllZipCodes?country=US&state=NY&key=<YOURAPIKEY>
Response (Truncated)
<ZipCodesList xmlns:i="https://www.w3.org/2001/XMLSchema-instance">
    <ZipCode>00501</ZipCode>
    <ZipCode>10001</ZipCode>
    <ZipCode>14905</ZipCode>
</ZipCodesList>
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/GetAllZipCodes?country=CA&state=NS&key=<YOURAPIKEY>
Response (Truncated)
["B0C", "B0E", "B0H", "B1A", "B2A"]

Get ZIP Code of Address GET

Deprecation Notice: This endpoint will be shut off on January 1, 2026. Please migrate away from this endpoint.

Validate a U.S. address and retrieve its ZIP+4 code.

U.S. Only: This feature is limited to United States addresses only.

Input Parameters

Parameter Required Definition
address Required Street number and name (e.g., "121 Main St")
address1 Optional Apartment or suite number
city Required City name
state Required 2-character state code
zipcode Optional ZIP Code (if known)
key Required Your private API Key

Example Request & Response

Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/ZipCodeOfAddress?address=6406+IVY+LN&city=GREENBELT&state=MD&key=<YOURAPIKEY>
Response
{
    "Result": {
        "Address": {
            "Address2": "6406 IVY LN",
            "City": "GREENBELT",
            "State": "MD",
            "Zip5": "20770",
            "Zip4": "1441"
        }
    }
}
Request
https://api.zip-codes.com/ZipCodesAPI.svc/1.0/xml/ZipCodeOfAddress?address=6406+IVY+LN&city=GREENBELT&state=MD&key=<YOURAPIKEY>
Response
<Result>
    <Address>
        <Address2>6406 IVY LN</Address2>
        <City>GREENBELT</City>
        <State>MD</State>
        <Zip5>20770</Zip5>
        <Zip4>1441</Zip4>
    </Address>
</Result>
Documentation
API Overview
API Endpoints