Postcode API

The Postcode API provides a convenient way to query and retrieve information about postcodes and their associated locations. It offers two main endpoints: search and list. The API is designed to handle flexible use cases, such as searching postcodes by geographic coordinates or retrieving a list of postcodes within specified filters.

This API is particularly useful for applications involving geospatial data, address validation, and localized search.

Features:

• Postcode Search: Look up postcodes using coordinates, a specific postcode, or a combination of both.
• Postcode List: Retrieve a list of postcodes filtered by geographic bounds, text search, or additional parameters.
• Customizable Output: Choose between various formats, including geojson, json, and xml, and specify the type of geometry returned (e.g., point or original).
• Global Coverage: Supports multiple countries with customizable filters for localization.

Explore the API:

Try out the functionality of our Postcode API using our interactive API Playground:

Endpoints:

1. Search Endpoint
   Use the search endpoint to find postcodes based on geographic coordinates or specific postcode values.

   Example Request:

   GET https://api.geoapify.com/v1/postcode/search?lat=51.02951939019121&lon=10.240940845638988&geometry=original&apiKey=YOUR_API_KEY
   

   Copy

2. List Endpoint
   Use the list endpoint to retrieve a collection of postcodes filtered by various criteria.

   Example Request:

   GET https://api.geoapify.com/v1/postcode/list?&countrycode=de&limit=20&geometry=original&filter=rect:8.303646633584322,49.56318958410171,11.11799160014175,50.83655794972171&apiKey=YOUR_API_KEY
   

   Copy

Documentation Links:

• Authentication and API Key
• Postcode Search API
• Postcode List API
• Pricing

Authentication and API key

To start using the Postcode API, you will need to obtain an API key. Fortunately, you can easily register for a free Geoapify API Key without needing a credit card.

Our free plan allows you to start immediately without any cost concerns. When your project scales, you can seamlessly upgrade to a paid plan for higher usage limits and additional features. For more information on pricing options, visit the Pricing page.

Steps to Get a Geoapify API Key:

1. Register for an Account
   Visit the Geoapify MyProjects page and create a new account if you don’t already have one.

2. Create a New Project
   Once logged in, create a new project. Navigate to the API Keys section where an API key will be automatically generated for your project. You can also generate multiple keys for the same project if needed.

3. Protect Your API Key
   For added security, configure restrictions for your API key by specifying allowed IP addresses, HTTP referrers, origins, and CORS.

4. Use Your API Key
   Select the Postcode API from the available APIs, and copy your API key to integrate it into your requests.

5. Test Your API Key
   Use the provided API key to make a test request. You can try it out directly via the API Playground to see how the API works and view a sample of the result object.

By following these steps, you’ll be ready to utilize the Postcode API in your projects efficiently and securely.

API Reference: Postcode Search API

The Postcode Search API allows users to search for postcodes based on geographic coordinates, a specific postcode, or both. It provides results in various formats, including JSON, GeoJSON, and XML, and supports customizable output for diverse use cases.

Request URL

https://api.geoapify.com/v1/postcode/search?REQUEST_PARAMS

Examples

Here are Postcode Search API URL examples (click on a URL to test the API):

• Search by geographic coordinates:
  https://api.geoapify.com/v1/postcode/search?lat=51.02951939019121&lon=10.240940845638988&geometry=original&apiKey=YOUR_API_KEY

• Search by postcode and country code:
  https://api.geoapify.com/v1/postcode/search?postcode=68100&countrycode=fr&geometry=original&apiKey=YOUR_API_KEY

Request Parameters

Usage Notes:

• Either postcode or a combination of lat and lon must be provided.
• Results are localized based on the countrycode parameter when specified.

Response Object

Depending on the format parameter, the API returns results in GeoJSON.FeatureCollection, JSON, or XML format. Each result contains information about the postcode and its associated location.

Key Response Fields

Example JSON Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "postcode": "68100",
        "lon": 7.341772669,
        "lat": 47.743740419,
        "datasource": {
          "sourcename": "geoclip",
          "attribution": "Géoclip (Ciril GROUP)",
          "license": "ODbL License",
          "url": "https://www.geoclip.fr/"
        },
        "country": "France",
        "country_code": "fr",
        "state": "Grand Est",
        "county": "Haut-Rhin",
        "municipality": "Mulhouse",
        "city": "Mulhouse",
        "state_code": "GES",
        "state_COG": "44",
        "formatted": "68100 Mulhouse, France",
        "address_line1": "68100 Mulhouse",
        "address_line2": "France",
        "timezone": {
          "name": "Europe/Paris",
          "offset_STD": "+01:00",
          "offset_STD_seconds": 3600,
          "offset_DST": "+02:00",
          "offset_DST_seconds": 7200,
          "abbreviation_STD": "CET",
          "abbreviation_DST": "CEST"
        },
        "plus_code": "8FV9P8VR+FP",
        "plus_code_short": "VR+FP Mulhouse, Haut-Rhin, France",
        "place_id": "51271690a7f95d1d4059bf28d4e232df4740c0020792031136383130302b66722b696d706f72746564"
      },
      "geometry": {
        "type": "Feature",
        "properties": {},
        "geometry": {
          "type": "Point",
          "coordinates": [
            7.341772669,
            47.743740419
          ]
        }
      },
      "bbox": [
        7.323173647,
        47.721942339,
        7.368265299,
        47.765209795
      ]
    }
  ]
}

This response shows the postcode 68100 in Mulhouse, France, along with its geographical coordinates and associated metadata.

API Reference: Postcode List API

The Postcode List API allows users to retrieve a list of postcodes based on specified filters, geographic bounds, and optional search criteria. This endpoint is ideal for obtaining postcode data for regions or refining results with customizable filters.

Request URL

https://api.geoapify.com/v1/postcode/list?REQUEST_PARAMS

Examples

Here are Postcode List API URL examples (click on a URL to test the API):

• List postcodes within a bounding rectangle:
  https://api.geoapify.com/v1/postcode/list?&countrycode=de&limit=20&geometry=original&filter=rect:8.303646633584322,49.56318958410171,11.11799160014175,50.83655794972171&apiKey=YOUR_API_KEY

• List postcodes within a circular area or radius: https://api.geoapify.com/v1/postcode/list?&limit=100&filter=circle:11.284522198253057,48.273546146646254,10000&apiKey=YOUR_API_KEY

Request Parameters

Usage Notes:

• Use the filter parameter to narrow down postcodes within specific regions or boundaries.
• Combine limit and offset for paginated results.

Geolocation Filters

You can use the following geolocation filters to refine results:

Note: Combine multiple filters with the | (pipe) character to apply AND logic.

Response Object

The API returns results in GeoJSON.FeatureCollection, JSON, or XML format, depending on the format parameter. Each returned postcode includes the following fields:

Example JSON Response

{
  "results": [
    {
      "datasource": {
        "sourcename": "openstreetmap",
        "attribution": "© OpenStreetMap contributors",
        "license": "Open Database License",
        "url": "https://www.openstreetmap.org/copyright"
      },
      "postcode": "82140",
      "ref": "82140",
      "other_names": {
        "ref": "82140"
      },
      "country": "Germany",
      "country_code": "de",
      "state": "Bavaria",
      "county": "Landkreis Fürstenfeldbruck",
      "city": "Olching",
      "suburb": "Olching",
      "lon": 11.344881403517578,
      "lat": 48.2094622192212,
      "state_code": "BY",
      "formatted": "82140 Olching, Germany",
      "address_line1": "82140 Olching",
      "address_line2": "Germany",
      "timezone": {
        "name": "Europe/Berlin",
        "offset_STD": "+01:00",
        "offset_STD_seconds": 3600,
        "offset_DST": "+02:00",
        "offset_DST_seconds": 7200,
        "abbreviation_STD": "CET",
        "abbreviation_DST": "CEST"
      },
      "plus_code": "8FWH685V+QX",
      "plus_code_short": "5V+QX Olching, Landkreis Fürstenfeldbruck, Germany",
      "place_id": "5191369a4b94b0264059bda672a8cf1a4840c0020792030838323134302b6465",
      "bbox": {
        "lon1": 11.2831904,
        "lat1": 48.1792862,
        "lon2": 11.40485,
        "lat2": 48.2371537
      }
    },
    {
      "datasource": {
        "sourcename": "openstreetmap",
        "attribution": "© OpenStreetMap contributors",
        "license": "Open Database License",
        "url": "https://www.openstreetmap.org/copyright"
      },
      "postcode": "82194",
      "ref": "82194",
      "other_names": {
        "ref": "82194"
      },
      "country": "Germany",
      "country_code": "de",
      "state": "Bavaria",
      "county": "Landkreis Fürstenfeldbruck",
      "city": "Gröbenzell",
      "lon": 11.375150197890301,
      "lat": 48.19290864472579,
      "state_code": "BY",
      "formatted": "82194 Gröbenzell, Germany",
      "address_line1": "82194 Gröbenzell",
      "address_line2": "Germany",
      "timezone": {
        "name": "Europe/Berlin",
        "offset_STD": "+01:00",
        "offset_STD_seconds": 3600,
        "offset_DST": "+02:00",
        "offset_DST_seconds": 7200,
        "abbreviation_STD": "CET",
        "abbreviation_DST": "CEST"
      },
      "plus_code": "8FWH59VG+53",
      "plus_code_short": "VG+53 Gröbenzell, Landkreis Fürstenfeldbruck, Germany",
      "place_id": "51b50dceaf13c0264059421b003bb1184840c0020792030838323139342b6465",
      "bbox": {
        "lon1": 11.3537558,
        "lat1": 48.177571,
        "lon2": 11.3935928,
        "lat2": 48.2068346
      }
    },
    ...
  ]
}

This JSON response lists postcodes located within a 10,000-meter radius from Bergkirchen, Bavaria, Germany. Each object in the results array includes detailed location data such as postcode, country, state, city, and formatted address. Geographic coordinates (lat, lon) and a bounding box (bbox) define the area for each postcode. The timezone field provides time zone details, and plus_code offers an alternate geocoding reference. All data is sourced from OpenStreetMap, ensuring accurate and open-licensed geographic information.

Pricing

Geoapify's Postcodes API uses a credit-based pricing model, making it simple to understand and predict costs based on your usage.

We offer a variety of Pricing Plans tailored to different usage levels. You can start with our FREE plan, which provides 3,000 credits per day, and easily upgrade as your needs grow.

The cost of a Postcodes API call depends on the number of results retrieved, with every 20 postcodes costing 1 credit. You can manage the number of results using the limit parameter to control your costs effectively.

For example, retrieving 100 postcodes would cost 5 credits.