Geocoding Workflow Examples

This guide shows practical workflows that combine geocoding with address and order creation, helping you integrate geocoding into your business processes.

Workflow 1: Geocode and Create an Address

This workflow demonstrates how to geocode an address and then create it in the system with accurate coordinates and components.

Flow:

1. Geocode an address string to get precise coordinates and validated components
2. Create an address using the geocoded data

NodeJS

const fetch = require("node-fetch")

async function geocodeAndCreateAddress(addressString, token) {
  // Step 1: Geocode the address
  const geocodeResponse = await fetch("https://backend.impargo.eu/", {
    headers: {
      "authorization": token,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      "operationName": "GeocodeAddress",
      "variables": { "query": addressString },
      "query": `
        query GeocodeAddress($query: String!) {
          geocodeAddress(query: $query) {
            coordinates {
              lat
              lon
            }
            components {
              street
              houseNumber
              postalCode
              city
              country
              countryCode
            }
            label
          }
        }
      `
    }),
    method: "POST"
  });

  const geocodeResult = await geocodeResponse.json();
  const geocodedData = geocodeResult[0].data.geocodeAddress;

  // Step 2: Create the address with geocoded data
  const createAddressResponse = await fetch("https://backend.impargo.eu/", {
    headers: {
      "authorization": token,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      "operationName": "CreateAddress",
      "variables": {
        "data": {
          "label": geocodedData.label,
          "street": geocodedData.components.street,
          "houseNumber": geocodedData.components.houseNumber,
          "zipcode": geocodedData.components.postalCode,
          "city": geocodedData.components.city,
          "country": geocodedData.components.country,
          "coordinates": {
            "lat": geocodedData.coordinates.lat,
            "lon": geocodedData.coordinates.lon
          }
        }
      },
      "query": `
        mutation CreateAddress($data: AddressCreateInput!) {
          createAddress(data: $data) {
            _id
            label
            coordinates {
              lat
              lon
            }
            city
            street
            zipcode
            country
          }
        }
      `
    }),
    method: "POST"
  });

  const addressResult = await createAddressResponse.json();
  return addressResult[0].data.createAddress;
}

// Example usage
geocodeAndCreateAddress("Hauptstraße 123, 10115 Berlin", token)
  .then(address => console.log("Address created:", address))
  .catch(error => console.error("Error:", error));

Workflow 2: Reverse Geocode Delivery Coordinates

This workflow converts GPS coordinates from tracking into human-readable addresses for order stops.

Flow:

1. Receive GPS coordinates from vehicle tracking
2. Reverse geocode to get address information
3. Use address for display or validation

NodeJS

const fetch = require("node-fetch")

async function reverseGeocodeDeliveryLocation(lat, lon, token) {
  const response = await fetch("https://backend.impargo.eu/", {
    headers: {
      "authorization": token,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      "operationName": "ReverseGeocodeLocation",
      "variables": { "lat": lat, "lon": lon },
      "query": `
        query ReverseGeocodeLocation($lat: Float!, $lon: Float!) {
          reverseGeocode(lat: $lat, lon: $lon) {
            label
            coordinates {
              lat
              lon
            }
            components {
              street
              houseNumber
              postalCode
              city
              country
              countryName
            }
            timezone
          }
        }
      `
    }),
    method: "POST"
  });

  const result = await response.json();
  return result[0].data.reverseGeocode;
}

// Example: Process multiple delivery coordinates
async function processDeliveryLocations(deliveries, token) {
  const addressedDeliveries = await Promise.all(
    deliveries.map(async (delivery) => {
      const address = await reverseGeocodeDeliveryLocation(
        delivery.lat,
        delivery.lon,
        token
      );
      return {
        ...delivery,
        address: address.label,
        city: address.components.city,
        country: address.components.country
      };
    })
  );
  return addressedDeliveries;
}

Workflow 3: Create Order with Geocoded Pickup and Delivery Addresses

This workflow shows how to create an order using geocoded addresses for both pickup and delivery locations.

Flow:

1. Geocode the pickup address
2. Geocode the delivery address
3. Create an order with both geocoded locations

NodeJS

const fetch = require("node-fetch")

async function createOrderWithGeocodedAddresses(pickupAddress, deliveryAddress, token) {
  // Step 1: Geocode both addresses in parallel
  const geocodeQuery = async (query) => {
    const response = await fetch("https://backend.impargo.eu/", {
      headers: {
        "authorization": token,
        "content-type": "application/json",
      },
      body: JSON.stringify({
        "operationName": "GeocodeAddress",
        "variables": { "query": query },
        "query": `
          query GeocodeAddress($query: String!) {
            geocodeAddress(query: $query) {
              coordinates {
                lat
                lon
              }
              components {
                city
                postalCode
                street
                country
              }
              label
            }
          }
        `
      }),
      method: "POST"
    });
    const result = await response.json();
    return result[0].data.geocodeAddress;
  };

  const [pickup, delivery] = await Promise.all([
    geocodeQuery(pickupAddress),
    geocodeQuery(deliveryAddress)
  ]);

  // Step 2: Create order with geocoded addresses
  const createOrderResponse = await fetch("https://backend.impargo.eu/", {
    headers: {
      "authorization": token,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      "operationName": "ImportOrder",
      "variables": {
        "data": {
          "label": "Sample Order",
          "pickupStop": {
            "address": {
              "street": pickup.components.street,
              "city": pickup.components.city,
              "zipcode": pickup.components.postalCode,
              "country": pickup.components.country,
              "coordinates": pickup.coordinates
            }
          },
          "deliveryStops": [
            {
              "address": {
                "street": delivery.components.street,
                "city": delivery.components.city,
                "zipcode": delivery.components.postalCode,
                "country": delivery.components.country,
                "coordinates": delivery.coordinates
              }
            }
          ]
        }
      },
      "query": `
        mutation ImportOrder($data: OrderImportInput!) {
          importOrder(data: $data) {
            _id
            label
            pickupStop {
              address {
                label
                city
                street
                zipcode
              }
              coordinates {
                lat
                lon
              }
            }
            deliveryStops {
              address {
                label
                city
                street
                zipcode
              }
              coordinates {
                lat
                lon
              }
            }
          }
        }
      `
    }),
    method: "POST"
  });

  const orderResult = await createOrderResponse.json();
  return orderResult[0].data.importOrder;
}

// Example usage
createOrderWithGeocodedAddresses(
  "Hauptstraße 123, 10115 Berlin",
  "Marienplatz 1, 80331 Munich",
  token
)
  .then(order => console.log("Order created:", order))
  .catch(error => console.error("Error:", error));

Best Practices

1. Error Handling

Always handle geocoding errors gracefully:

• Address not found: Provide user feedback to review and correct the address
• Invalid coordinates: Validate input before sending to reverse geocoding
• Rate limit exceeded: Implement exponential backoff for retries

2. Performance Optimization

• Batch operations: When possible, chain queries to reduce round trips
• Cache results: Store geocoding results to avoid repeated lookups for same addresses
• Parallel requests: Use Promise.all() to geocode multiple addresses concurrently

3. Data Validation

• Verify components: Check that required address components (city, postal code, country) are present
• Validate coordinates: Ensure latitude (-90 to 90) and longitude (-180 to 180) are in valid ranges
• Country consistency: Verify that the geocoded country matches expected region

4. User Experience

• Provide feedback: Show users the geocoded address for confirmation before creating orders
• Handle edge cases: Some addresses may have multiple matches or no results
• Graceful degradation: Have fallback options if geocoding fails

Common Scenarios

Scenario: Address Standardization

Some addresses may have variations (e.g., "St." vs "Street"). Geocoding automatically standardizes these:

Input: "St. Main St, 10115 Berlin"
Geocoded Label: "Main Street 1, 10115 Berlin, Germany"

Scenario: Partial Addresses

You can geocode partial addresses and the system will try to find the best match:

Input: "Berlin, 10115"
Result: Coordinates for central Berlin postal code 10115

Scenario: Ambiguous Addresses

If multiple matches exist, geocoding returns the most likely result. Use the country parameter to disambiguate:

Without country filter: May return results from multiple countries
With country=de: Returns only German results