Sări la conținutul principal

Flux de lucru geocodificare

Acest caz de utilizare demonstrează un flux de lucru tipic de geocodificare: acceptă intrare utilizator, găsește sugestii, geocodifică o adresă și geocodifică invers pentru verificare.

Folosești Python?

SDK-ul Python avvolează toate aceste puncte finale într-un client tipizat — client.location.geocode(q="..."), client.location.autocomplete(q="..."), etc.

Scenariu​

Aplicația ta permite utilizatorilor să introducă adrese. Trebuie să:

  1. Furnizezi sugestii completare automată pe măsură ce tastează
  2. Geocodifică adresa selectată la coordonate
  3. Verifică rezultatul prin geocodificare inversă

Pasul 1: Completare automată adresă​

Pe măsură ce utilizatorul tastează, cere sugestii:

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

Răspuns:

{
  "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"]
    }
  ]
}

Pasul 2: Geocodifică adresa selectată​

Utilizatorul selectează o adresă (sau furnizează o adresă completă). Convertește-o în coordonate:

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

Răspuns:

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

Pasul 3: Geocodificare inversă pentru verificare​

Verifică coordonatele geocodificate prin convertirea lor înapoi la o adresă:

# Utilizează coordonatele din răspunsul anterior
curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse?lat=38.8951&lon=-77.0369" \
  -H "Authorization: YOUR_API_KEY"

Răspuns:

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

Fluxul complet - Exemplu​

def complete_geocode_workflow(user_input):
    try:
        # Pasul 1: Obține sugestii
        print('Getting suggestions...')
        data = requests.get(
            'https://graph.quarticle.ro/graph/api/v1/places/autocomplete',
            params={'q': user_input},
            headers=headers
        ).json()
        suggestions = data['results']

        if not suggestions:
            print('No suggestions found')
            return None

        selected = suggestions[0]['label']
        print(f'Selected: {selected}')

        # Pasul 2: Geocodifică adresa
        print('Geocoding address...')
        location = requests.get(
            'https://graph.quarticle.ro/graph/api/v1/places/geocode',
            params={'q': selected},
            headers=headers
        ).json()['result']

        print(f"Coordinates: [{location['lon']}, {location['lat']}]")
        print(f"Quality: {location['geocodingQuality']}")

        # Pasul 3: Verifică cu geocodificare inversă
        print('Verifying location...')
        verified = requests.get(
            'https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse',
            params={'lat': location['lat'], 'lon': location['lon']},
            headers=headers
        ).json()['result']

        print(f"Verified: {verified['label']}")

        return {
            'original': user_input,
            'selected': selected,
            'coordinates': {'lat': location['lat'], 'lon': location['lon']},
            'verified': verified['label'],
            'quality': location['geocodingQuality']
        }

    except Exception as e:
        print(f'Error: {e}')
        return None

# Utilizare
result = complete_geocode_workflow('new y')
print(json.dumps(result, indent=2))

Cazuri de utilizare​

Acest flux este util pentru:

  • Forme intrare adresă - Ghidează utilizatorii cu sugestii
  • Aplicații de mapare - Convertește adrese la coordonate hartă
  • Validare locație - Verifică că intrarea utilizatorului este o adresă reală
  • Fluxuri multi-pas - Combină cu analiză portofoliu utilizând coordonatele
  • Asigurare calitate - Verifică calitatea geocodificării înainte de stocare

Gestionare erori​

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();

  // Verifică calitatea geocodificării
  if (result.geocodingQuality === 'address' || result.geocodingQuality === 'rooftop') {
    console.log('High quality match');
    return result;
  } else {
    console.warn(`Low quality match (${result.geocodingQuality})`);
    return result;
  }
}

Pași următori​