Skip to main content

Geocoding Workflow

This use case demonstrates a typical geocoding workflow: accept user input, find suggestions, geocode an address, and reverse geocode for verification.

Using Python?

The Python SDK wraps all these endpoints in a typed client — client.location.geocode(q="..."), client.location.autocomplete(q="..."), etc.

Scenario​

Your application allows users to input addresses. You need to:

  1. Provide autocomplete suggestions as they type
  2. Geocode the selected address to coordinates
  3. Verify the result by reverse geocoding back to an address

Step 1: Address Autocomplete​

As the user types, request suggestions:

# User typed "new y"
curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/autocomplete?q=new%20y" \
  -H "Authorization: YOUR_API_KEY"

Response:

{
  "results": [
    {
      "label": "New York, New York",
      "lat": 40.7128,
      "lon": -74.0060,
      "placeId": "abc123",
      "geocodingQuality": "city",
      "geocodingRequired": false,
      "highlights": ["New York"]
    },
    {
      "label": "New Haven, Connecticut",
      "lat": 41.3083,
      "lon": -72.9279,
      "placeId": "def456",
      "geocodingQuality": "city",
      "geocodingRequired": false,
      "highlights": ["New Haven"]
    }
  ]
}

Step 2: Geocode Selected Address​

User selects an address (or provides a full address). Convert it to coordinates:

curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode?q=1600%20Pennsylvania%20Avenue%20Washington%20DC" \
  -H "Authorization: YOUR_API_KEY"

Response:

{
  "result": {
    "lat": 38.8951,
    "lon": -77.0369,
    "label": "1600 Pennsylvania Avenue, Washington, DC 20500",
    "placeId": "xyz789",
    "geocodingQuality": "rooftop"
  }
}

Step 3: Reverse Geocode for Verification​

Verify the geocoded coordinates by converting them back to an address:

# Use coordinates from previous response
curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse?lat=38.8951&lon=-77.0369" \
  -H "Authorization: YOUR_API_KEY"

Response:

{
  "result": {
    "label": "1600 Pennsylvania Avenue, Washington, DC 20500",
    "placeId": "xyz789",
    "geocodingQuality": "rooftop",
    "type": "address"
  }
}

Complete Workflow Example​

async function completeGeocodeWorkflow(userInput) {
  const apiKey = process.env.QARTA_API_KEY;

  try {
    // Step 1: Get suggestions
    console.log('Getting suggestions...');
    const { results: suggestions } = await fetch(
      `https://graph.quarticle.ro/graph/api/v1/places/autocomplete?q=${encodeURIComponent(userInput)}`,
      { headers: { 'Authorization': `${apiKey}` } }
    ).then(r => r.json());

    if (suggestions.length === 0) {
      console.log('No suggestions found');
      return null;
    }

    // Use first suggestion (or let user select)
    const selectedLabel = suggestions[0].label;
    console.log(`Selected: ${selectedLabel}`);

    // Step 2: Geocode the address
    console.log('Geocoding address...');
    const { result: location } = await fetch(
      `https://graph.quarticle.ro/graph/api/v1/places/geocode?q=${encodeURIComponent(selectedLabel)}`,
      { headers: { 'Authorization': `${apiKey}` } }
    ).then(r => r.json());

    console.log(`Coordinates: [${location.lon}, ${location.lat}]`);
    console.log(`Quality: ${location.geocodingQuality}`);

    // Step 3: Verify with reverse geocoding
    console.log('Verifying location...');
    const { result: verified } = await fetch(
      `https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse?lat=${location.lat}&lon=${location.lon}`,
      { headers: { 'Authorization': `${apiKey}` } }
    ).then(r => r.json());

    console.log(`Verified: ${verified.label}`);

    return {
      original: userInput,
      selected: selectedLabel,
      coordinates: { lat: location.lat, lon: location.lon },
      verified: verified.label,
      quality: location.geocodingQuality
    };

  } catch (error) {
    console.error('Geocoding error:', error);
    return null;
  }
}

// Usage
const result = await completeGeocodeWorkflow('new y');
console.log(JSON.stringify(result, null, 2));

Use Cases​

This workflow is useful for:

  • Address input forms - Guide users with suggestions
  • Mapping applications - Convert addresses to map coordinates
  • Location validation - Verify user input is a real address
  • Multi-step flows - Combine with portfolio analysis using the coordinates
  • Quality assurance - Check geocoding quality before storing

Error Handling​

async function geocodeWithErrorHandling(address) {
  const response = await fetch(
    `https://graph.quarticle.ro/graph/api/v1/places/geocode?q=${encodeURIComponent(address)}`,
    { headers: { 'Authorization': `${apiKey}` } }
  );

  if (response.status === 400) {
    console.error('Invalid address format');
    return null;
  }

  if (response.status === 401) {
    console.error('Invalid API key');
    return null;
  }

  const { result } = await response.json();

  // Check geocoding quality
  if (result.geocodingQuality === 'address' || result.geocodingQuality === 'rooftop') {
    console.log('High quality match');
    return result;
  } else {
    console.warn(`Low quality match (${result.geocodingQuality})`);
    return result;
  }
}

Next Steps​