Skip to main content

Reverse Geocoding

The reverseGeocode query finds the address and location details for a given set of map coordinates (latitude and longitude). This is useful when you have GPS coordinates but need the corresponding address information.

GraphQL query documentation

Use Cases​

  • Displaying addresses from GPS coordinates: When you receive GPS coordinates from a driver or vehicle tracking system, use reverse geocoding to show a human-readable address.
  • Address lookup from map clicks: Convert user-selected map coordinates into full address details.
  • Validating delivery locations: Verify that GPS coordinates correspond to valid addresses before creating orders.
  • Address enrichment from third-party data: When integrating with external systems that provide coordinates, enrich that data with complete address components.

Basic Example​

Find the address for a specific coordinate:


const fetch = require("node-fetch")

fetch("https://backend.impargo.eu/", {
  headers: {
    "authorization": token,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "operationName": "ReverseGeocodeLocation",
    "variables": {
      "lat": 52.52374,
      "lon": 13.41053
    },
    "query": `
      query ReverseGeocodeLocation($lat: Float!, $lon: Float!) {
        reverseGeocode(lat: $lat, lon: $lon) {
          label
          coordinates {
            lat
            lon
          }
          components {
            street
            houseNumber
            postalCode
            city
            district
            state
            country
          }
        }
      }
    `
  }),
  method: "POST"
});

{
  "data": {
    "reverseGeocode": {
      "label": "10178 Berlin, Memhardstraße 1, Mitte, Germany",
      "coordinates": {
        "lat": 52.52374,
        "lon": 13.41053
      },
      "components": {
        "street": "Memhardstraße",
        "houseNumber": "1",
        "postalCode": "10178",
        "city": "Berlin",
        "district": "Mitte",
        "state": "Berlin",
        "country": "de"
      }
    }
  }
}

Example: Multiple Coordinate Lookups​

Reverse geocode multiple delivery stops at once by making sequential queries:


const fetch = require("node-fetch")

// Array of delivery coordinates
const deliveryStops = [
  { lat: 52.52374, lon: 13.41053 },   // Berlin
  { lat: 48.13704, lon: 11.57549 }    // Munich
];

// Create queries for each coordinate
const queries = deliveryStops.map((stop, index) => ({
  operationName: `ReverseGeocodeStop${index + 1}`,
  variables: { lat: stop.lat, lon: stop.lon },
  query: `
    query ReverseGeocodeStop${index + 1}($lat: Float!, $lon: Float!) {
      reverseGeocode(lat: $lat, lon: $lon) {
        label
        coordinates {
          lat
          lon
        }
        components {
          city
          postalCode
          street
          country
        }
      }
    }
  `
}));

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

[
  {
    "data": {
      "reverseGeocode": {
        "label": "Hauptstraße 123, 10115 Berlin, Germany",
        "coordinates": {
          "lat": 52.52374,
          "lon": 13.41053
        },
        "components": {
          "city": "Berlin",
          "postalCode": "10115",
          "street": "Hauptstraße",
          "country": "de"
          }
      }
    }
  },
  {
    "data": {
      "reverseGeocode": {
        "label": "Marienplatz 1, 80331 Munich, Germany",
        "coordinates": {
          "lat": 48.13704,
          "lon": 11.57549
        },
        "components": {
          "city": "Munich",
          "postalCode": "80331",
          "street": "Marienplatz",
          "country": "de"
          }
      }
    }
  }
]

Workflow Example: Creating an Address from GPS Coordinates​

Here's a typical workflow where you reverse geocode coordinates to get address details:

  1. Step 1: Reverse geocode the coordinates to get the full address
  2. Step 2: Review the address components (street, city, postal code, country)
  3. Step 3: Use the address data to create an address in the system

This ensures accurate address information even when you only have GPS coordinates.

Coordinate Validation​

The reverseGeocode query validates input coordinates:

  • Latitude must be between -90 and 90
  • Longitude must be between -180 and 180

Invalid coordinates will result in an error.

Error Handling​

The reverseGeocode query throws an error if:

  • Invalid coordinates: The latitude or longitude values are outside valid ranges
  • Address not found: No matching address could be found for the provided coordinates
  • Geocoding unavailable: The geocoding service is temporarily unavailable (this error is retryable)

Note on Coordinate Precision​

In some cases, the geocoding provider may return slightly different coordinates than the ones you requested. The reverseGeocode query normalizes this by returning the exact coordinates you provided, while using the provider's address result. This ensures consistency between the coordinates you query and the coordinates returned.

Rate Limiting​

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