API Documentation

Zip2Geo offers a simple and fast way to convert postal codes into geographic coordinates. To use the API, send a GET request to the following endpoint:

GET https://zip2geo.dev/api/lookup

Required Query Parameters

• country – The ISO 3166-1 alpha-2 country code (e.g. DE, US, FR)
• postal_code – The postal code you want to look up

Authentication

You can authenticate using one of the following methods:

• Via HTTP header: Authorization: Bearer YOUR_API_KEY
• Or as query parameter: ?key=YOUR_API_KEY

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://zip2geo.dev/api/lookup?country=DE&postal_code=10115"

Example Response

[
  {
    "postal_code": "10435",
    "country": "DE",
    "latitude": 52.5378,
    "longitude": 13.4112,
    "name": "Berlin",
    "state": "Berlin"
  }
]

Error Handling

• Invalid API Key
  Returns HTTP 401 Unauthorized:

  { "error": "Invalid API Key" }

• Host Not Allowed
  Returns HTTP 403 Forbidden:

  { "error": "Host not allowed" }

• No Results Found
  Returns HTTP 404 Not Found with an empty array:

  []

Supported Countries

Below is a list of all ISO 3166-1 alpha-2 country codes currently supported by the Zip2Geo API:

That's it. No registration hoops, no unnecessary complexity — just zip-to-geo lookup, done right.