Skip to main content

Geocoding Addresses

The geocodeAddress query converts a text address into map coordinates along with complete address components. This is useful when you want to create orders or addresses via the API but need to obtain geocodes or other location details.

GraphQL query documentation

Use Cases​

  • Creating orders or addresses programmatically: If you have addresses but lack precise geocodes or complete address components (city, postal code, country), use geocoding to enrich your data before creating orders or addresses via the API.
  • Address validation: Verify that an address is valid and exists in the geocoding provider's database.
  • Standardizing address format: Get the standardized address components for an address string.

Basic Example​

Geocode a simple address string:


const fetch = require("node-fetch")

fetch("https://backend.impargo.eu/", {
  headers: {
    "authorization": token,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "operationName": "GeocodeAddress",
    "variables": {
      "query": "Alexanderplatz 1, 10178 Berlin, Germany"
    },
    "query": `
      query GeocodeAddress($query: String!) {
        geocodeAddress(query: $query) {
          label
          coordinates {
            lat
            lon
          }
          components {
            street
            houseNumber
            postalCode
            city
            district
            state
            country
          }
        }
      }
    `
  }),
  method: "POST"
});

{
  "data": {
    "geocodeAddress": {
      "label": "10178 Berlin, Alexanderplatz 1, Mitte, Germany",
      "coordinates": {
        "lat": 52.52128,
        "lon": 13.4127
      },
      "components": {
        "street": "Alexanderplatz",
        "houseNumber": "1",
        "postalCode": "10178",
        "city": "Berlin",
        "district": "Mitte",
        "state": "Berlin",
        "country": "de"
      }
    }
  }
}

Example with Country Filter​

If you want to limit the search to a specific country:


const fetch = require("node-fetch")

fetch("https://backend.impargo.eu/", {
  headers: {
    "authorization": token,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "operationName": "GeocodeAddressInCountry",
    "variables": {
      "query": "Marienplatz 1, 80331 Munich",
      "country": "de"
    },
    "query": `
      query GeocodeAddressInCountry($query: String!, $country: AddressCountry) {
        geocodeAddress(query: $query, country: $country) {
          label
          coordinates {
            lat
            lon
          }
          components {
            street
            houseNumber
            postalCode
            city
            country
          }
        }
      }
    `
  }),
  method: "POST"
});

{
  "data": {
    "geocodeAddress": {
      "label": "80331 Munich, Marienplatz 1, Altstadt, Germany",
      "coordinates": {
        "lat": 48.13744,
        "lon": 11.57472
      },
      "components": {
        "street": "Marienplatz",
        "houseNumber": "1",
        "postalCode": "80331",
        "city": "Munich",
        "country": "de"
      }
    }
  }
}

Workflow Example: Creating an Address After Geocoding​

Here's a typical workflow where you geocode an address first, then use the geocoded data to create an address in the system:

  1. Step 1: Geocode the address to get precise coordinates and validated components
  2. Step 2: Use the geocoded results to create an address with validated data

This ensures your addresses are accurate and properly located on the map before they're used in orders or routes.

Error Handling​

The geocodeAddress query throws an error if:

  • Invalid query: The address string is empty or too long (max 256 characters)
  • Address not found: No matching address could be found for the provided query
  • Not in the allowed geocoding countries: The specified country is not in the allowed countries for your company's geocoding settings. By default, all EU countries are allowed, but if your company has configured custom geocoding settings (e.g., only DE and FR), you can only geocode addresses in those countries.
  • Geocoding unavailable: The geocoding service is temporarily unavailable (this error is retryable)

Rate Limiting​

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