Postcode API
Search Postcal codes by Text, Location and Geometry
The Postcode API allows you to search for postcodes using text input, precise coordinates, or defined geometries such as a radius or bounding box.
Need postcodes for a specific area or query by address text? Our API provides accurate results and can return original geometry polygons when available, enabling detailed analysis and visualization of postcode boundaries.
Whether you're building mapping tools, logistics systems, or geospatial applications, the API simplifies retrieving and analyzing postal code data based on your specific needs.
Use Cases
The Postcode API offers flexible tools to address a wide range of real-world scenarios, from logistics optimization to location-based analytics. Below are some of the key use cases where the API can add significant value:
Features and Capabilities
Features and Capabilities
The Postal Code API offers two powerful endpoints for retrieving and querying postcodes:
Retrieve a single postcode by text input (postcode value) or geographic coordinates (latitude and longitude). Here are URL examples:
Search for a postcode by text:
https://api.geoapify.com/v1/postcode/search?postcode=82140&countrycode=de&apiKey=YOUR_API_KEYSearch for a postcode by location:
https://api.geoapify.com/v1/postcode/search?lat=48.2095&lon=11.3448&apiKey=YOUR_API_KEYQuery a list of postcodes using flexible filters, such as:
-
Text to match postcodes by prefix ("startsWith" option):
https://api.geoapify.com/v1/postcode/list?text=82&countrycode=de&limit=10&apiKey=YOUR_API_KEY -
Geometry-based queries including radius, bounding box (rect), or administrative areas like cities and suburbs.
-
Search within a radius:
https://api.geoapify.com/v1/postcode/list?filter=circle:11.3448,48.2095,10000&apiKey=YOUR_API_KEY -
Search within a bounding box:
https://api.geoapify.com/v1/postcode/list?filter=rect:11.2832,48.1792,11.4048,48.2371&apiKey=YOUR_API_KEY -
Search by city or suburb:
https://api.geoapify.com/v1/postcode/list?filter=place:5194a2957b81c9024059ece5d2533f6d4840f00101f9016517010000000000c00208&countrycode=de&apiKey=YOUR_API_KEY
-
The API provides additional capabilities to enhance location-based applications:
- Original Geometry Polygons: When available, the API returns the original geometry of postcodes, enabling precise visualization and analysis.
- Structured Address Data: Results include detailed address components such as postcode, city, suburb, state, and country.
- Timezone Information: Each result includes timezone details with standard and daylight saving offsets.
- Plus Codes: Postcodes are accompanied by Plus Codes, providing an alternative for identifying locations.
- Open Data Sources: The API integrates reliable open data sources, such as OpenStreetMap, GeoNames, and official country datasets where available. These sources are carefully curated to ensure accuracy, consistency, and global coverage. You can learn more about our data sources and download postal code datasets here.
These features make the Postcode API a comprehensive solution for postcode lookups, geospatial queries, and detailed location analysis.
For further details, explore the API in our Playground or check the Postcode API Documentation.
Getting started
You can query postcodes using our Postcode API. Find tutorials here to help you get started.
Below are simple steps to retrieve postcodes:
Step 1. Register and get an API Key
You will require an API Key to use the API:
- Register on the MyProject Geoapify page.
- Create a new project.
- Go to the "API keys" section and get your API key.
Visit the Getting Started with Maps API page for detailed information on how to create a project, generate an API key, and start working with Geoapify APIs.
Step 2. Generate and call HTTP GET API request
The Postcode API responds to HTTP GET requests. The typical request URLs for the Search Endpoint and List Endpoint are as follows:
Search Endpoint - Query postcode by text or location:
https://api.geoapify.com/v1/postcode/search?postcode=82140&countrycode=de&apiKey=YOUR_API_KEYList Endpoint - Retrieve postcodes within a bounding box:
https://api.geoapify.com/v1/postcode/list?filter=rect:11.2832,48.1792,11.4048,48.2371&apiKey=YOUR_API_KEYNote: Use encodeURIComponent() or a similar method to ensure parameters like text and postcode are URL-encoded correctly.
Visit our documentation page for more details about API parameters, or explore the Postcode API Playground to generate sample queries.
Step 3. Get the API result object
The API returns results in the requested format (GeoJSON, JSON, XML) format. Below is an example of a List Endpoint response in the JSON format:
- [] 2 items▶
- {} 16 keys▶
- "AB10"
- -2.0981
- 57.1437
- {} 4 keys▶
- "United Kingdom"
- "gb"
- "Scotland"
- "Aberdeen City"
- "City Centre"
- "SCT"
- "Aberdeen City, AB10, United Kingdom"
- "Aberdeen City"
- "AB10, United Kingdom"
- {} 7 keys▶
- "9C9V4WV2+FQ"
- "519be61da7e8c800c059b537f8c264924c40c00207920310414231302b67622b696d706f72746564"
- {} 16 keys▶
Examples
Below are examples of using the Postcode API for different scenarios with comments about locations:
Searching a postal code in the US
Retrieve details for a specific postal code in the United States.
https://api.geoapify.com/v1/postcode/search?postcode=90210&countrycode=us&apiKey=YOUR_API_KEYLocation: Beverly Hills, California, USA.
Search postcode by latitude and longitude in Norway
Find the nearest postcode to a specific geographic location in Norway.
https://api.geoapify.com/v1/postcode/search?lat=59.9139&lon=10.7522&apiKey=YOUR_API_KEYLocation: Oslo, Norway.
List postcodes starting with "AB" in Great Britain
Retrieve postcodes in Great Britain that start with the prefix "AB".
https://api.geoapify.com/v1/postcode/list?text=AB&countrycode=gb&limit=10&apiKey=YOUR_API_KEYLocation: Aberdeen and surrounding areas, Scotland, GB.
List postcodes within a bounding box in France
Retrieve postcodes within a defined rectangular area in France.
https://api.geoapify.com/v1/postcode/list?filter=rect:2.2522,48.8156,2.4222,48.9022&apiKey=YOUR_API_KEYLocation: Covers northern Paris, France.
Get postcodes within a radius in Italy
Find all postcodes within a 5 km radius of a specific location in Italy.
https://api.geoapify.com/v1/postcode/list?filter=circle:12.4964,41.9028,5000&apiKey=YOUR_API_KEYLocation: Centered around Rome, Italy.
Get all postcodes in Munich, Germany
Retrieve all postcodes within the city of Munich using a filter=place:place_id search. The place_id can be obtained from the Geocoding API or Autocomplete API.
https://api.geoapify.com/v1/postcode/list?&filter=place:51ac66e77e9826274059f9426dc08c114840f00101f901dcf3000000000000c00208&limit=20&geometry=original&apiKey=YOUR_API_KEYLocation: Munich, Bavaria, Germany.
Note: The place_id used in the filter is returned as part of the response from Geocoding or Autocomplete API when querying the desired location.
Retrieve 100 postcodes within a radius
Fetch up to 100 postcodes around a specified point with the limit parameter.
https://api.geoapify.com/v1/postcode/list?filter=circle:11.2845,48.2735,10000&limit=100&apiKey=YOUR_API_KEYLocation: 10 km radius around Bergkirchen, Bavaria, Germany.
Pricing
Geoapify Postcode API offers flexible pricing based on usage to accommodate various business needs. The API uses a credit-based system to calculate request costs.
For each request made to the Postcode API, you will be charged 1 credit. Additionally, for every additional set of 20 postcodes included in the response, 1 extra credit will be deducted.
- Example 1: You request a list of postcodes within a bounding box with
limit=50. The API responds with 50 postcodes.
- Cost: 1 credit for the initial request + 2 credits for the additional 30 postcodes (1 credit per 20 postcodes).
- Total: 3 credits (1 + 1 * 2 = 3).
- Example 2: You retrieve postcodes using a radius filter with
limit=100. The API returns 100 postcodes.
- Cost: 1 credit for the initial request + 4 credits for the additional 80 postcodes.
- Total: 5 credits (1 + 1 * 4 = 5).
- Example 3: You query postcodes by text with
limit=500, and the API responds with 240 postcodes.
- Cost: 1 credit for the initial request + 11 credits for the additional 220 postcodes.
- Total: 12 credits (1 + 1 * 11 = 12).
The Free plan includes 3000 credits per day, allowing you to explore and evaluate the API without any cost. If you exceed this quota, you can upgrade to a paid plan that fits your usage needs.
For detailed information on pricing tiers, additional features, and credit packages, please visit our Pricing page. It provides a comprehensive overview of the available options to help you choose the most suitable plan for your business requirements.
FAQ
How is the Postcode API different from the Geocoding API with type=postcode?
The Postcode API is specifically designed for querying postcodes and retrieving larger datasets. While the Geocoding API with type=postcode focuses on matching addresses that include postcodes, the Postcode API uses multiple country-specific databases, returns original postcode geometry when available, and supports efficient data retrieval with pagination (limit and offset).
Can the Postcode List endpoint be used as an Autocomplete service?
Yes, the Postcode List endpoint can be used for Autocomplete functionality. You can utilize the Geoapify Geocoder Autocomplete library and set the `setSendGeocoderRequestFunc` parameter to call the Postcode API, enabling seamless postcode suggestions.
What data sources does the Postcode API use?
The Postcode API integrates multiple open data sources that are specific to each country, ensuring accurate and up-to-date postcode information. For more details on the data sources used, visit our Postal Code Data Sources page.
What geometry can the Postcode API return?
The Postcode API can return original geometry polygons of postcodes when available. These geometries are valuable for precise visualization, mapping, and geospatial analysis.
How can I retrieve a list of postal codes using the API?
You can retrieve a list of postcodes using the Postcode List endpoint. Flexible filters are supported, including prefix-based searches (startsWith), geometry-based queries (radius, bounding box), and administrative boundaries like cities and suburbs. The API also supports pagination with the "limit" and "offset" parameters for efficient data handling.
Can I search for postcodes by text and location?
Yes, the Postal Code API allows searching postcodes by text input (e.g., matching by prefix) and by geographic coordinates (latitude and longitude). This flexibility ensures accurate results for various use cases.
Is pagination supported for large datasets?
Yes, the Postcode List endpoint supports pagination. You can use the "limit" parameter to define the number of postcodes returned per request (maximum 500) and the "offset" parameter to fetch subsequent pages of results efficiently.
Can the Postcode API return additional location details?
Yes, in addition to postcodes, the API provides structured address data, including components like city, state, and country. Results also include timezone details, Plus Codes, and original geometry when available.
What are the primary use cases of the Postal Code API?
The Postcode API is ideal for applications involving address validation, postal code searches, geospatial mapping, and large-scale data analysis. It is also suitable for location-based services, autocomplete solutions, and visualizing postcode boundaries.
How can I get started with the Postcode API?
To get started, register on the Geoapify MyProject page, create a project, and obtain your API key. Use the key to make requests to the Postcode API. Refer to our Postcode API Documentation for examples and detailed parameter information.
