DEV Community

Cover image for How to Get Postcode Data from Text Using an API
Alfiya Tarasenko
Alfiya Tarasenko

Posted on

How to Get Postcode Data from Text Using an API

#api #dev #programming #javascript

Someone types 10115 into your postcode field. How do you make sense of it?

You could validate it, sure — but what if you also want to know where it is?
Is it Berlin? What are its coordinates? Which region does it belong to?

That’s where Geoapify’s Postcode API comes in.

With just one request, you can turn a simple string like 10115 into rich geographic data — coordinates, boundaries, and more — in milliseconds. Perfect for powering location-aware features like shipping calculators, coverage checkers, or personalized search.

Make a call to the Postcode Search API

Geoapify’s /postcode/search endpoint transforms raw text (like 10115) into structured location information, including:

  • City or town
  • Bounding box (perfect for map zoom)
  • Associated administrative regions
  • Polygon geometry (if available)

In short: everything your app needs to understand where a postcode is — and how big that area really is.

Here’s an example request using curl:

curl "https://api.geoapify.com/v1/postcode/search?postcode=10115&countrycode=de&geometry=original&apiKey=YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode
  • postcode=10115 — the postcode you’re searching for
  • countrycode=de — restricts results to Germany (use ISO 3166-1 alpha-2 codes)
  • geometry=original — returns the full boundary polygon (if available) instead of just a point
  • apiKey=YOUR_API_KEY — your personal API key from Geoapify Get Started (free tier available)

Example response (truncated for clarity):

{
  "type": "FeatureCollection",
  "features": [
    {
      "properties": {
        "postcode": "10115",
        "country": "Germany",
        "country_code": "de",
        "city": "Berlin",
        "district": "Mitte",
        "lat": 52.5296001,
        "lon": 13.3909760,
        "formatted": "10115 Berlin, Germany"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [...]
      },
      "bbox": [13.3652242, 52.5237433, 13.4012965, 52.5401484]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The response from the Postcode Search API gives you everything you need — from city and district names to full boundary polygons. Perfect for building location-aware apps, validating addresses, or visualizing coverage.

Example of postcode 10115 (Berlin) with boundary polygon and location details returned by the Geoapify Postcode Search API.

Step 2: Use the data in your app

The Postcode Search API response gives you more than just coordinates — it provides administrative regions, formatted addresses, and even boundary polygons.

You can use this data to:

  • Validate postcode entries
  • Display the area on a map
  • Zoom to the postcode’s bounding box

Example using JavaScript fetch:

const apiKey = "YOUR_API_KEY";
const url = "https://api.geoapify.com/v1/postcode/search?postcode=10115&countrycode=de&geometry=original&apiKey=" + apiKey;

fetch(url)
  .then(response => response.json())
  .then(data => {
    const postcodeFeature = data.features[0];
    console.log("Postcode:", postcodeFeature.properties.postcode);
    console.log("City:", postcodeFeature.properties.city);
    console.log("Coordinates:", postcodeFeature.properties.lat, postcodeFeature.properties.lon);
    console.log("Bounding Box:", postcodeFeature.bbox);
  })
  .catch(error => console.error(error));
Enter fullscreen mode Exit fullscreen mode

Wrapping up

With the Geoapify Postcode Search API, you can:

  • Turn raw postcode text into full geographic context
  • Access city, district, and region data in milliseconds
  • Retrieve bounding boxes and polygons for maps and coverage analysis

Try it now:

Because a good app knows the difference between 10115 and 90210.

Top comments (0)