Geocoding Postal Codes

The geocodePostalCode query finds the coordinates for a postal code in a specific country. This is useful when you have a postal code but need precise coordinates for mapping, routing, or address validation.

GraphQL query documentation

Use Cases

• Quick coordinate lookup: Get coordinates from just a postal code and country without a full address.
• Delivery area mapping: Map service areas or delivery zones by postal code.
• Address prefix completion: Use postal code coordinates as a starting point for more detailed geocoding.
• Regional logistics: Group orders by postal code regions for dispatch planning.

Basic Example

Find coordinates for a postal code in a specific country:

NodeJS

const fetch = require("node-fetch")

fetch("https://backend.impargo.eu/", {
  headers: {
    "authorization": token,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "operationName": "GeocodePostalCode",
    "variables": {
      "postalCode": "10115",
      "country": "de"
    },
    "query": `
      query GeocodePostalCode($postalCode: String!, $country: AddressCountry!) {
        geocodePostalCode(postalCode: $postalCode, country: $country) {
          lat
          lon
          __typename
        }
      }
    `
  }),
  method: "POST"
});

Response

{
  "data": {
    "geocodePostalCode": {
      "lat": 52.53194,
      "lon": 13.38455,
      "__typename": "Coordinates"
    }
  }
}

Example: Multiple Postal Code Lookups

Geocode multiple postal codes at once to map delivery regions:

NodeJS

const fetch = require("node-fetch")

// Array of postal codes to geocode
const postalCodes = [
  { postalCode: "10115", country: "de" },  // Berlin
  { postalCode: "80331", country: "de" },  // Munich
  { postalCode: "75001", country: "fr" }   // Paris
];

// Create queries for each postal code
const queries = postalCodes.map((pc, index) => ({
  operationName: `GeocodePostalCode${index + 1}`,
  variables: { postalCode: pc.postalCode, country: pc.country },
  query: `
    query GeocodePostalCode${index + 1}($postalCode: String!, $country: AddressCountry!) {
      geocodePostalCode(postalCode: $postalCode, country: $country) {
        lat
        lon
      }
    }
  `
}));

fetch("https://backend.impargo.eu/", {
  headers: {
    "authorization": token,
    "content-type": "application/json",
  },
  body: JSON.stringify(queries),
  method: "POST"
});

Response

[
  {
    "data": {
      "geocodePostalCode": {
        "lat": 52.52374,
        "lon": 13.41053
      }
    }
  },
  {
    "data": {
      "geocodePostalCode": {
        "lat": 48.13704,
        "lon": 11.57549
      }
    }
  },
  {
    "data": {
      "geocodePostalCode": {
        "lat": 48.85661,
        "lon": 2.35222
      }
    }
  }
]

Differences from Full Address Geocoding

Feature	geocodePostalCode	geocodeAddress
Input	Postal code + country	Address string + optional country
Output	Coordinates only	Full address + coordinates
Speed	Faster (exact match)	Slower (fuzzy matching)
Use case	Area/region mapping	Precise address matching
Validation	Validates postal code exists	Validates full address exists

Workflow: Map Delivery Regions by Postal Code

Use postal code geocoding to create service area maps:

1. Get postal code coordinates using geocodePostalCode
2. Plot on map or create geographical clusters
3. Assign delivery zones based on postal code regions
4. Route orders within zone coverage areas

Result Handling

The geocodePostalCode field returns coordinates when the geocoding provider finds an exact match for the requested postal code and country. It returns null without an error when no exact match is found.

• Empty postal code: An empty or whitespace-only postalCode throws an invalid-query error.
• Not in the allowed geocoding countries: A country outside your company's allowed geocoding countries throws an invalid-country error.
• Provider or rate-limit failure: These throw a geocoding-unavailable error with retry information when available.

Supported Countries

By default, geocoding is available for all EU countries. However, if your company has configured custom geocoding settings, the country parameter must be one of your allowed countries. For example, if your settings restrict geocoding to only Germany (DE) and France (FR), postal code geocoding will only work for those two countries.

Rate Limiting

The postal code geocoding API has a rate limit of 240 requests per 60 seconds per company. If you exceed this limit, the request will be rejected.