Geocodifica

Panoramica

L’API di geocodifica ti permette di cercare località in tutto il mondo e recuperarne i dettagli. Supporta la corrispondenza approssimativa, i risultati localizzati e le ricerche dirette per ID.

Ricerca

Cerca località per nome con corrispondenza approssimativa opzionale.

GET /geocoding/lookup?q={query}

Parametri

Parametro	Obbligatorio	Predefinito	Descrizione
q	Sì	—	Query di ricerca (minimo 2 caratteri)
language	No	en	Codice lingua per risultati localizzati (es. de, it, fr)
field	No	name	Ambito di ricerca. name cerca solo nei nomi delle località. all cerca nel nome, nella regione amministrativa e nel paese.
country	No	—	Codice paese ISO 3166-1 alpha-2 per filtrare i risultati (es. AT, CH, US)
limit	No	10	Numero massimo di risultati (max 50)

Richiesta di esempio

GET /geocoding/lookup?q=Zurich&language=en&limit=5

Risposta di esempio

{
  "results": [
    {
      "id": "3704415940",
      "name": "Zürich",
      "lat": 47.36667,
      "lon": 8.55,
      "country_code": "CH",
      "country_name": "Switzerland",
      "admin1_name": "Kanton Zürich",
      "timezone": "Europe/Zurich",
      "population": 341730,
      "feature_code": "PPLA"
    }
  ],
  "count": 1
}

Ricerca per ID

Recupera una località specifica tramite il suo ID univoco.

GET /geocoding/lookup?id={location_id}

Parametri

Parametro	Obbligatorio	Descrizione
id	Sì	L’ID pubblico univoco della località

Richiesta di esempio

GET /geocoding/lookup?id=3704415940

Risposta di esempio

{
  "id": "3704415940",
  "name": "Zürich",
  "lat": 47.36667,
  "lon": 8.55,
  "country_code": "CH",
  "country_name": "Switzerland",
  "admin1_name": "Kanton Zürich",
  "admin2_name": "Bezirk Zürich",
  "timezone": "Europe/Zurich",
  "population": 341730,
  "elevation": null,
  "feature_code": "PPLA"
}

Campi della risposta

Campo	Tipo	Descrizione
id	string	Identificatore univoco della località
name	string	Nome della località (localizzato quando il parametro language è impostato)
lat	float	Latitudine
lon	float	Longitudine
country_code	string	Codice paese ISO 3166-1 alpha-2
country_name	string	Nome del paese
admin1_name	string	Divisione amministrativa di primo livello (es. stato, cantone)
admin2_name	string	Divisione amministrativa di secondo livello (es. distretto, contea)
timezone	string	Identificatore fuso orario IANA
population	integer	Popolazione (può essere null)
elevation	integer	Altitudine in metri (può essere null)
feature_code	string	Codice che indica il tipo di località (es. PPL per città, PPLA per capitale, AIRP per aeroporto)

Errori

Status	Descrizione
400	Parametro obbligatorio mancante (id o q)
404	Località non trovata (solo ricerca per ID)
503	Dati di geocodifica non ancora caricati