API Geocode (Indirizzo → Latitudine/Longitudine)

Usa Geocode per convertire indirizzi postali in coordinate di latitudine/longitudine. La geocodifica è in genere il primo passaggio prima della pianificazione dei percorsi o dell'ottimizzazione del dispatch quando non disponi ancora di coordinate affidabili per le fermate.

L'API Geocode di TrackRoad converte un indirizzo in coordinate latitudine/longitudine per routing e dispatch.
Esempio di API Geocode: converti un indirizzo in coordinate latitudine/longitudine per routing e dispatch accurati.

Best practice: valida le fermate prima dell'ottimizzazione dei percorsi

Indirizzi errati sono una delle cause più comuni di fermate mancanti, percorsi sbagliati e fallimenti di ottimizzazione evitabili. Usa prima Geocode, poi chiama Dispatch o Route.

Panoramica riferimento API Apri Swagger UI

Indice dei contenuti

  1. Cos'è la geocodifica e perché è importante
  2. Cosa fa Geocode
  3. Comprendere MatchCode
  4. Endpoint REST e URL di base
  5. Endpoint SOAP
  6. Autenticazione
  7. Schema della richiesta
  8. Schema della risposta
  9. Esempi
  10. Errori comuni
  11. Best practice
  12. Endpoint correlati
  13. FAQ

Cos'è la geocodifica e perché è importante#

La geocodifica converte un indirizzo postale come 350 5th Ave, New York, NY in coordinate latitudine/longitudine che il software può usare per routing, calcolo ETA e misurazione delle distanze.

I motori di ottimizzazione dei percorsi dipendono da coordinate di fermata accurate. Quando gli indirizzi sono incompleti, ambigui o errati, i risultati dei percorsi diventano meno affidabili.

  • Coordinate errate possono produrre percorsi sbagliati, distanze errate ed ETA poco affidabili.
  • Coordinate mancanti possono causare errori di dispatch, fermate saltate o lavoro non assegnato.
  • Indirizzi ambigui possono portare a valori MatchCode bassi e risultati con minore affidabilità.

Se ottimizzi i percorsi senza validare prima gli indirizzi, è più probabile che tu veda fermate mancanti, piani non fattibili o una scarsa qualità del percorso.

Cosa fa Geocode#

Geocode accetta uno o più oggetti Address e restituisce uno o più risultati candidati di tipo Location per ciascun indirizzo. Ogni Location restituita può includere coordinate LatLong e un valore MatchCode che aiuta a valutare la qualità della corrispondenza.

Transazioni: ogni indirizzo geocodificato conta come una transazione, anche quando più indirizzi vengono inviati nella stessa richiesta.

Comprendere MatchCode#

MatchCode è un indicatore di confidenza restituito durante la geocodifica. Mostra quanto bene TrackRoad ha associato il tuo indirizzo di input a una posizione reale.

  • Un MatchCode alto di solito indica una corrispondenza più precisa ed è generalmente più sicuro per il dispatch.
  • Un MatchCode basso di solito significa che l'indirizzo è incompleto, ambiguo o meno affidabile.
  • L'assenza di una corrispondenza utile può indicare un indirizzo non valido o dati mancanti relativi a città, regione, CAP o paese.

Se il MatchCode è basso, correggi l'indirizzo o invia direttamente latitudine/longitudine quando le coordinate sono già note.

Endpoint REST e URL di base#

Elemento Valore
URL di base https://trackservice.trackroad.com
Endpoint POST /rest/geocode
URL completo https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

Le richieste REST di geocodifica usano POST e in genere restituiscono JSON. A seconda dei dettagli di integrazione, può essere supportato anche XML.

Endpoint SOAP#

Elemento Valore
URL SOAP https://trackservice.trackroad.com/TrackService.asmx
WSDL https://trackservice.trackroad.com/TrackService.asmx?wsdl
SOAPAction http://TrackService.TrackRoad.com/Geocode
Content-Type text/xml; charset=utf-8

Le buste e gli header delle richieste SOAP per Geocode sono definiti nel WSDL e possono variare in base alla versione SOAP.

Autenticazione#

Autenticazione REST (X-API-Key)

Includi il tuo TrackServiceKey nell'header X-API-Key in ogni richiesta REST. Vedi Autenticazione API .

curl -X POST "https://trackservice.trackroad.com/rest/geocode" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{ "IsNeedMatchCode": true, "Addresses": [] }'

Conserva le chiavi API lato server quando possibile. Evita di incorporare chiavi API di produzione direttamente nel codice del browser o delle app mobili.

Autenticazione SOAP (SessionIDHeader)

Le richieste SOAP usano un SessionIDHeader. Per i servizi SOAP di TrackRoad, invia il tuo TrackServiceKey come valore di SessionID a ogni chiamata. I metodi legacy Login/Logout possono ancora apparire nella documentazione più vecchia, ma non sono necessari per l'uso moderno.

Consigliato: preferisci REST, a meno che tu non debba integrarti con un sistema esistente solo SOAP.

Schema della richiesta#

Il corpo della richiesta è un singolo oggetto GeocodeSpecification. Fornisci uno o più indirizzi da geocodificare.

GeocodeSpecification

Proprietà Tipo Obbligatorio Descrizione
IsNeedMatchCode bool No Se true, include indicatori di qualità della corrispondenza nel risultato. Consigliato per integrazioni in produzione.
Addresses Address[] Sì* Uno o più indirizzi da geocodificare. Ogni indirizzo conta come una transazione.

Address

Address è un modello condiviso tra endpoint. Lo schema completo di Address è documentato anche in Dispatch API (modelli condivisi) .

Proprietà Tipo Obbligatorio Descrizione
Street string Consigliato Riga dell'indirizzo stradale.
City string Consigliato Città o località.
State string No Stato, provincia o regione.
PostalCode string No CAP o codice postale.
Country string Consigliato Codice paese o nome del paese, ad esempio US.

Schema della risposta#

Una risposta corretta restituisce un GeocodeResult contenente uno o più oggetti GeocodeItem. Ogni elemento corrisponde a un indirizzo di input.

GeocodeResult

Proprietà Tipo Descrizione
Items GeocodeItem[] Un elemento per ciascun indirizzo di input. Ogni elemento può contenere zero, una o più posizioni candidate.
Errors Error[] Errori o avvisi restituiti dal servizio.
Status int (enum) Codice di stato come 0=None, 1=Success, 2=Failed o 3=SuccessWithErrors.

GeocodeItem

Proprietà Tipo Descrizione
Address Address L'indirizzo originale di input.
Locations Location[] Risultati candidati di geocodifica per l'indirizzo.

Location, LatLong, MatchCode

Questi modelli sono condivisi tra vari endpoint. Consulta le tabelle complete dello schema in Dispatch API (modelli condivisi) .

Error

Proprietà Tipo Descrizione
Message string Messaggio di errore o avviso leggibile da persone.

Esempi#

Usa le sezioni seguenti per esempi di richieste e risposte REST e SOAP. Il codice di esempio può rimanere neutro e non richiede localizzazione.

REST JSON request example#

Send one or more addresses in a single request.

{
  "IsNeedMatchCode": true,
  "Addresses": [
    {
      "Street": "6718 Whittier Avenue",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    },
    {
      "Street": "1450 Old Chain Bridge Road",
      "City": "McLean",
      "State": "VA",
      "PostalCode": "22101",
      "Country": "US"
    }
  ]
}

REST request examples (multiple languages)#

curl -X POST "https://trackservice.trackroad.com/rest/geocode" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -d '{
    "IsNeedMatchCode": true,
    "Addresses": [
      { "Street": "6718 Whittier Avenue", "City": "McLean", "State": "VA", "PostalCode": "22101", "Country": "US" }
    ]
  }'

REST JSON response example (shape)#

{
  "Items": [
    {
      "Address": {
        "Street": "6718 Whittier Avenue",
        "City": "McLean",
        "State": "VA",
        "PostalCode": "22101",
        "Country": "US"
      },
      "Locations": [
        {
          "MatchCode": 4,
          "LatLong": { "Latitude": 38.931594, "Longitude": -77.17602 },
          "Address": {
            "Street": "6718 Whittier Avenue",
            "City": "McLean",
            "State": "VA",
            "PostalCode": "22101",
            "Country": "US"
          }
        }
      ]
    }
  ],
  "Errors": [],
  "Status": 1
}

SOAP 1.1 request example#

SOAP Geocode uses SessionIDHeader with SessionID = TrackServiceKey and SOAPAction http://TrackService.TrackRoad.com/Geocode.

<!-- POST https://trackservice.trackroad.com/TrackService.asmx -->
<!-- Content-Type: text/xml; charset=utf-8 -->
<!-- SOAPAction: "http://TrackService.TrackRoad.com/Geocode" -->

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Header>
    <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>

  <soap:Body>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>

SOAP request examples (multiple languages)#

SOAP Geocode uses SessionIDHeader with SessionID = TrackServiceKey and SOAPAction http://TrackService.TrackRoad.com/Geocode.

curl -X POST "https://trackservice.trackroad.com/TrackService.asmx" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: "http://TrackService.TrackRoad.com/Geocode"" \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <Geocode xmlns="http://TrackService.TrackRoad.com/">
      <specification>
        <IsNeedMatchCode>true</IsNeedMatchCode>
        <Addresses>
          <Address>
            <Street>6718 Whittier Avenue</Street>
            <City>McLean</City>
            <State>VA</State>
            <PostalCode>22101</PostalCode>
            <Country>US</Country>
          </Address>
        </Addresses>
      </specification>
    </Geocode>
  </soap:Body>
</soap:Envelope>'

SOAP response example (shape)#

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>

    <GeocodeResponse xmlns="http://TrackService.TrackRoad.com/">
      <GeocodeResult>

        <Status>1</Status>
        <Errors />

        <Items>
          <GeocodeItem>

            <Address>
              <Street>6718 Whittier Avenue</Street>
              <City>McLean</City>
              <State>VA</State>
              <PostalCode>22101</PostalCode>
              <Country>US</Country>
            </Address>

            <Locations>
              <Location>
                <MatchCode>4</MatchCode>
                <LatLong>
                  <Latitude>38.931594</Latitude>
                  <Longitude>-77.17602</Longitude>
                </LatLong>
                <Address>
                  <Street>6718 Whittier Avenue</Street>
                  <City>McLean</City>
                  <State>VA</State>
                  <PostalCode>22101</PostalCode>
                  <Country>US</Country>
                </Address>
              </Location>
            </Locations>

          </GeocodeItem>
        </Items>

      </GeocodeResult>
    </GeocodeResponse>

  </soap:Body>
</soap:Envelope>

Errori comuni#

  • 401 / Unauthorized: header X-API-Key mancante o non valido nelle richieste REST.
  • 403 / Forbidden: la chiave può essere valida ma bloccata, scaduta o impossibilitata a elaborare la richiesta.
  • Indirizzo non valido o incompleto: il servizio può restituire zero candidati, corrispondenze deboli o valori MatchCode bassi.
  • Errore di autenticazione SOAP: SessionIDHeader mancante o non valido, dove SessionID deve contenere il tuo TrackServiceKey.

Best practice#

  • Memorizza nella cache i risultati di geocodifica nel tuo sistema per evitare di geocodificare ripetutamente lo stesso indirizzo, a meno che non cambi.
  • Usa input di indirizzo stabili come via, città, regione, CAP e paese per ridurre l'ambiguità.
  • Usa MatchCode per filtrare o approvare i risultati quando la qualità dei dati è importante.
  • Invia LatLong a Dispatch o Route dopo la geocodifica per migliorare le prestazioni ed evitare ricerche ripetute.
  • Se Geocode restituisce più candidati, scegli il migliore in base alla qualità della corrispondenza e all'indirizzo formattato più adatto alle tue regole di business.

FAQ#

Cosa fa l'API Geocode?
L'API Geocode converte indirizzi postali in una o più posizioni candidate con coordinate latitudine/longitudine, aiutandoti a preparare dati di fermata accurati per routing e dispatch.
Come mi autentico all'API Geocode?
Per REST, invia il tuo TrackServiceKey nell'header X-API-Key. Per SOAP, invia il tuo TrackServiceKey in SessionIDHeader come SessionID.
Perché la geocodifica può restituire più risultati?
Alcuni indirizzi sono ambigui o incompleti, quindi l'API può restituire più posizioni candidate. Usa MatchCode e i dettagli dell'indirizzo restituito per scegliere il risultato migliore.
Perché dovrei geocodificare prima dell'ottimizzazione dei percorsi?
La geocodifica prima dell'ottimizzazione dei percorsi migliora accuratezza del percorso, ETA, assegnazione delle fermate e calcoli delle distanze, garantendo che ogni fermata disponga di coordinate valide.

Passo successivo: ottimizza i percorsi con coordinate accurate

Dopo aver geocodificato gli indirizzi, usa Dispatch o Route con coordinate latitudine/longitudine per generare ETA, distanze e sequenze di percorso più accurate.

Vai a Dispatch API Apri Swagger UI