API Geocode (Adresse → Latitude/Longitude)

Utilisez Geocode pour convertir des adresses postales en coordonnées latitude/longitude. Le géocodage est généralement la première étape avant la planification d’itinéraires ou l’optimisation de la répartition lorsque vous ne disposez pas encore de coordonnées d’arrêt fiables.

L’API Geocode TrackRoad convertit une adresse en coordonnées latitude/longitude pour le routage et la répartition.
Exemple d’API Geocode : convertissez une adresse en coordonnées latitude/longitude pour un routage et une répartition précis.

Bonne pratique : valider les arrêts avant l’optimisation des tournées

Les mauvaises adresses sont l’une des causes les plus fréquentes d’arrêts manquants, d’itinéraires erronés et d’échecs d’optimisation évitables. Utilisez d’abord Geocode, puis appelez Dispatch ou Route.

Vue d’ensemble de la référence API Voir Swagger UI

Table des matières

  1. Qu’est-ce que le géocodage et pourquoi c’est important
  2. Ce que fait Geocode
  3. Comprendre MatchCode
  4. Endpoint REST et URL de base
  5. Endpoint SOAP
  6. Authentification
  7. Schéma de requête
  8. Schéma de réponse
  9. Exemples
  10. Erreurs courantes
  11. Bonnes pratiques
  12. Endpoints associés
  13. FAQ

Qu’est-ce que le géocodage et pourquoi c’est important#

Le géocodage convertit une adresse postale comme 350 5th Ave, New York, NY en coordonnées latitude/longitude que le logiciel peut utiliser pour le routage, le calcul des ETA et la mesure des distances.

Les moteurs d’optimisation de tournées dépendent de coordonnées d’arrêt précises. Lorsque les adresses sont incomplètes, ambiguës ou erronées, les résultats des tournées deviennent moins fiables.

  • Des coordonnées incorrectes peuvent produire de mauvais itinéraires, de mauvaises distances et des ETA peu fiables.
  • L’absence de coordonnées peut entraîner des échecs de répartition, des arrêts ignorés ou du travail non attribué.
  • Des adresses ambiguës peuvent entraîner des valeurs de MatchCode faibles et des résultats moins fiables.

Si vous optimisez des tournées sans valider les adresses au préalable, vous risquez davantage d’obtenir des arrêts manquants, des plans irréalisables ou une mauvaise qualité de routage.

Ce que fait Geocode#

Geocode accepte un ou plusieurs objets Address et renvoie un ou plusieurs résultats candidats de type Location pour chaque adresse. Chaque Location renvoyée peut inclure des coordonnées LatLong et une valeur MatchCode qui vous aide à évaluer la qualité de la correspondance.

Transactions : chaque adresse géocodée compte comme une transaction, même lorsque plusieurs adresses sont envoyées dans la même requête.

Comprendre MatchCode#

MatchCode est un indicateur de confiance renvoyé pendant le géocodage. Il montre dans quelle mesure TrackRoad a fait correspondre votre adresse d’entrée à un emplacement réel.

  • Un MatchCode élevé signifie généralement une correspondance plus précise et est habituellement plus sûr pour la répartition.
  • Un MatchCode faible signifie généralement que l’adresse est incomplète, ambiguë ou moins fiable.
  • L’absence de correspondance utile peut indiquer une adresse invalide ou des informations manquantes sur la ville, la région, le code postal ou le pays.

Si le MatchCode est faible, corrigez l’adresse ou envoyez directement la latitude/longitude lorsque les coordonnées sont déjà connues.

Endpoint REST et URL de base#

Élément Valeur
URL de base https://trackservice.trackroad.com
Endpoint POST /rest/geocode
URL complète https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

Les requêtes REST de géocodage utilisent POST et renvoient généralement du JSON. Selon les détails d’intégration, XML peut également être pris en charge.

Endpoint SOAP#

Élément Valeur
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

Les enveloppes et en-têtes de requête SOAP pour Geocode sont définis dans le WSDL et peuvent varier selon la version de SOAP.

Authentification#

Authentification REST (X-API-Key)

Incluez votre TrackServiceKey dans l’en-tête X-API-Key sur chaque requête REST. Voir Authentification 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": [] }'

Conservez les clés API côté serveur autant que possible. Évitez d’intégrer directement des clés API de production dans du code navigateur ou mobile.

Authentification SOAP (SessionIDHeader)

Les requêtes SOAP utilisent un SessionIDHeader. Pour les services SOAP TrackRoad, envoyez votre TrackServiceKey comme valeur de SessionID à chaque appel. Les méthodes héritées Login/Logout peuvent encore apparaître dans une ancienne documentation, mais elles ne sont pas nécessaires pour un usage moderne.

Recommandation : privilégiez REST sauf si vous devez vous intégrer à un système existant uniquement SOAP.

Schéma de requête#

Le corps de la requête est un objet GeocodeSpecification unique. Fournissez une ou plusieurs adresses à géocoder.

GeocodeSpecification

Propriété Type Obligatoire Description
IsNeedMatchCode bool Non Si true, inclut des indicateurs de qualité de correspondance dans le résultat. Recommandé pour les intégrations de production.
Addresses Address[] Oui* Une ou plusieurs adresses à géocoder. Chaque adresse compte comme une transaction.

Address

Address est un modèle partagé entre plusieurs endpoints. Le schéma complet de Address est également documenté dans Dispatch API (modèles partagés) .

Propriété Type Obligatoire Description
Street string Recommandé Ligne d’adresse.
City string Recommandé Ville ou localité.
State string Non État, province ou région.
PostalCode string Non Code postal.
Country string Recommandé Code pays ou nom du pays, par exemple US.

Schéma de réponse#

Une réponse réussie renvoie un GeocodeResult contenant un ou plusieurs objets GeocodeItem. Chaque élément correspond à une adresse d’entrée.

GeocodeResult

Propriété Type Description
Items GeocodeItem[] Un élément par adresse d’entrée. Chaque élément peut contenir zéro, un ou plusieurs emplacements candidats.
Errors Error[] Erreurs ou avertissements renvoyés par le service.
Status int (enum) Code d’état tel que 0=None, 1=Success, 2=Failed ou 3=SuccessWithErrors.

GeocodeItem

Propriété Type Description
Address Address L’adresse d’entrée d’origine.
Locations Location[] Résultats candidats de géocodage pour l’adresse.

Location, LatLong, MatchCode

Ces modèles sont partagés entre plusieurs endpoints. Consultez les tableaux de schéma complets dans Dispatch API (modèles partagés) .

Error

Propriété Type Description
Message string Message d’erreur ou d’avertissement lisible par un humain.

Exemples#

Utilisez les sections suivantes pour les exemples de requêtes et réponses REST et SOAP. Le code d’exemple peut rester neutre et n’a pas besoin d’être localisé.

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>

Erreurs courantes#

  • 401 / Unauthorized : en-tête X-API-Key manquant ou invalide sur les requêtes REST.
  • 403 / Forbidden : la clé peut être valide mais bloquée, expirée ou incapable de traiter la requête.
  • Adresse invalide ou incomplète : le service peut renvoyer zéro candidat, des correspondances faibles ou de faibles valeurs de MatchCode.
  • Échec d’authentification SOAP : SessionIDHeader manquant ou invalide, où SessionID doit contenir votre TrackServiceKey.

Bonnes pratiques#

  • Mettez en cache les résultats de géocodage dans votre système afin de ne pas géocoder la même adresse à répétition sauf si elle change.
  • Utilisez des entrées d’adresse stables comme la rue, la ville, la région, le code postal et le pays pour réduire l’ambiguïté.
  • Utilisez MatchCode pour filtrer ou valider les résultats lorsque la qualité des données est importante.
  • Envoyez LatLong à Dispatch ou Route après le géocodage afin d’améliorer les performances et d’éviter des recherches répétées.
  • Si Geocode renvoie plusieurs candidats, choisissez le meilleur en fonction de la qualité de correspondance et de l’adresse formatée la plus adaptée à vos règles métier.

FAQ#

Que fait l’API Geocode ?
L’API Geocode convertit des adresses postales en un ou plusieurs emplacements candidats avec des coordonnées latitude/longitude, ce qui vous aide à préparer des données d’arrêt précises pour le routage et la répartition.
Comment m’authentifier auprès de l’API Geocode ?
Pour REST, envoyez votre TrackServiceKey dans l’en-tête X-API-Key. Pour SOAP, envoyez votre TrackServiceKey dans SessionIDHeader comme SessionID.
Pourquoi le géocodage peut-il renvoyer plusieurs résultats ?
Certaines adresses sont ambiguës ou incomplètes, l’API peut donc renvoyer plusieurs emplacements candidats. Utilisez MatchCode et les détails d’adresse renvoyés pour choisir le meilleur résultat.
Pourquoi devrais-je géocoder avant l’optimisation de tournées ?
Le géocodage avant l’optimisation de tournées améliore la précision des itinéraires, les ETA, l’affectation des arrêts et les calculs de distance en garantissant que chaque arrêt possède des coordonnées valides.

Étape suivante : optimisez les tournées avec des coordonnées précises

Après avoir géocodé les adresses, utilisez Dispatch ou Route avec des coordonnées latitude/longitude afin de générer des ETA, des distances et des séquences de tournée plus précises.

Aller à Dispatch API Voir Swagger UI