Documentazione

1. Quick start

curl --get "https://geocoding.qubitdata.it/v1/search" \
  --data-urlencode "q=Via Romagnosi 1, Milano"

2. Forma della risposta

Envelope compatibile con Google Geocoding API: { status, results[] }. Drop-in per la maggior parte dei client già scritti contro l'API Google.

{
  "status": "OK",
  "results": [
    {
      "address_components": [
        { "long_name": "1", "short_name": "1", "types": ["street_number"] },
        { "long_name": "Via Romagnosi", "short_name": "Via Romagnosi", "types": ["route"] },
        { "long_name": "20121", "short_name": "20121", "types": ["postal_code"] },
        { "long_name": "Milano", "short_name": "Milano", "types": ["locality", "political"] },
        { "long_name": "Milano", "short_name": "MI", "types": ["administrative_area_level_2", "political"] },
        { "long_name": "Lombardia", "short_name": "Lombardia", "types": ["administrative_area_level_1", "political"] },
        { "long_name": "Italy", "short_name": "IT", "types": ["country", "political"] }
      ],
      "formatted_address": "Via Romagnosi, 1, 20121 Milano MI, Italy",
      "geometry": {
        "location": { "lat": 45.4684, "lng": 9.19054 },
        "location_type": "ROOFTOP",
        "viewport": { "northeast": {...}, "southwest": {...} }
      },
      "place_id": "qd_xxxxxxxxxxxxx",
      "types": ["street_address"]
    }
  ],
  "query": {
    "raw": "Via Romagnosi 1, Milano",
    "parsed": { "road": "via romagnosi", "number": "1", "city": "milano" }
  }
}

Codici di stato come Google: OK, ZERO_RESULTS, INVALID_REQUEST, OVER_QUERY_LIMIT, REQUEST_DENIED, UNKNOWN_ERROR.

Il campo query è una nostra estensione (Google lo omette) — utile per debug del parsing.

geometry.location_type

Campi per risultato

• place_id — ID deterministico con prefisso qd_, stabile per la tripla (strada, comune, civico). Non è un place ID di Google.
• partial_match — true quando la query è stata corretta (typo, civico mancante, ecc.).
• types — ["street_address"] quando un civico è risolto, ["route"] altrimenti.
• geometry.viewport — bounding box sintetica dimensionata sulla precisione del location_type.

Campi top-level opzionali (estensioni nostre)

• did_you_mean — strada come scritta originalmente; il risultato è per la forma corretta.
• did_you_mean_city — città come scritta originalmente; il risultato è per la forma corretta.
• alternates — candidati fuzzy ugualmente buoni (array di nomi di strada).
• postcode_override — il comune determinato dal CAP (sovrascrive la città digitata in conflitto).
• street_centroid — true quando il risultato viene dall'indice fallback solo strada.
• actual_city — su match nearby_comune, il comune reale del risultato (la città digitata è in did_you_mean_city).

3. Parser italiano

• V.le, P.zza, C.so, Lgt. espansi a Viale, Piazza, Corso, Lungotevere
• Suffissi civico preservati: 12/A, 12B, 12 bis/ter/quater, 12-14 (range → estremo inferiore), snc
• Diacritici rimossi: Via Ètna → via etna
• Numeri SS / SP restano nel nome strada (non parsati come civico): Strada Statale 16
• Inferenza città in coda: Via Roma 1 Milano risolve la città senza virgola.
• CAP disambigua: un postcode a 5 cifre sovrascrive o riempie la città.
• Scarta marker scala / sc / piano / int / interno / km e i loro valori.
• Posizioni ordinali tollerate: Vico 2° Adamo ↔ Vico Adamo 2° matchano lo stesso record.
• Iniziali nome espanse contro il dataset: Via C. Romani → Via Carolina Romani. Catene multi-iniziale supportate: Via G. B. Tiepolo.

4. Errori

5. Supporto

Domande, integrazione, condizioni enterprise: support@qubitdata.it