Geocode API (Adresse → Breitengrad/Längengrad)

Verwenden Sie Geocode, um Postadressen in Breiten-/Längengrad-Koordinaten umzuwandeln. Geocoding ist in der Regel der erste Schritt vor Routenplanung oder Dispositionsoptimierung, wenn noch keine zuverlässigen Stop-Koordinaten vorhanden sind.

TrackRoad Geocode API wandelt eine Adresse für Routing und Disposition in Breiten-/Längengrad-Koordinaten um.
Beispiel der Geocode API: Wandeln Sie eine Adresse für präzises Routing und Disposition in Breiten-/Längengrad-Koordinaten um.

Best Practice: Stopps vor der Routenoptimierung validieren

Fehlerhafte Adressen gehören zu den häufigsten Ursachen für fehlende Stopps, falsche Routen und vermeidbare Optimierungsfehler. Erst Geocode, dann Dispatch oder Route verwenden.

API-Referenzübersicht Swagger UI öffnen

Inhaltsverzeichnis

  1. Was Geocoding ist und warum es wichtig ist
  2. Was Geocode macht
  3. MatchCode verstehen
  4. REST-Endpunkt und Basis-URL
  5. SOAP-Endpunkt
  6. Authentifizierung
  7. Request-Schema
  8. Response-Schema
  9. Beispiele
  10. Häufige Fehler
  11. Best Practices
  12. Verwandte Endpunkte
  13. FAQ

Was Geocoding ist und warum es wichtig ist#

Geocoding wandelt eine Postadresse wie 350 5th Ave, New York, NY in Breiten-/Längengrad-Koordinaten um, die Software für Routing, ETA-Berechnung und Distanzmessung verwenden kann.

Routenoptimierungssysteme sind auf präzise Stop-Koordinaten angewiesen. Wenn Adressen unvollständig, mehrdeutig oder falsch sind, werden Routenergebnisse unzuverlässiger.

  • Falsche Koordinaten können zu falschen Routen, falschen Entfernungen und ungenauen ETAs führen.
  • Fehlende Koordinaten können zu Dispositionsfehlern, übersprungenen Stopps oder nicht zugewiesener Arbeit führen.
  • Mehrdeutige Adressen können zu niedrigen MatchCode-Werten und Ergebnissen mit geringerer Sicherheit führen.

Wenn Sie Routen optimieren, ohne Adressen vorher zu validieren, treten häufiger fehlende Stopps, unlösbare Pläne oder schlechte Routenergebnisse auf.

Was Geocode macht#

Geocode akzeptiert ein oder mehrere Address-Objekte und liefert für jede Adresse ein oder mehrere mögliche Location-Ergebnisse zurück. Jede zurückgegebene Location kann LatLong-Koordinaten und einen MatchCode enthalten, mit dem sich die Trefferqualität bewerten lässt.

Transaktionen: jede geocodierte Adresse zählt als eine Transaktion, auch wenn mehrere Adressen in derselben Anfrage gesendet werden.

MatchCode verstehen#

MatchCode ist ein Vertrauensindikator, der beim Geocoding zurückgegeben wird. Er zeigt, wie gut TrackRoad Ihre Eingabeadresse einer realen Position zuordnen konnte.

  • Hoher MatchCode bedeutet in der Regel einen präziseren Treffer und ist normalerweise sicherer für die Disposition.
  • Niedriger MatchCode bedeutet meist, dass die Adresse unvollständig, mehrdeutig oder weniger zuverlässig ist.
  • Kein brauchbarer Treffer kann auf eine ungültige Adresse oder fehlende Angaben zu Stadt, Region, Postleitzahl oder Land hinweisen.

Wenn der MatchCode niedrig ist, korrigieren Sie die Adresse oder senden Sie direkt Breiten-/Längengrade, wenn die Koordinaten bereits bekannt sind.

REST-Endpunkt und Basis-URL#

Element Wert
Basis-URL https://trackservice.trackroad.com
Endpunkt POST /rest/geocode
Vollständige URL https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

REST-Geocode-Anfragen verwenden POST und liefern typischerweise JSON zurück. Abhängig von den Integrationsdetails kann auch XML unterstützt werden.

SOAP-Endpunkt#

Element Wert
SOAP-URL 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

SOAP-Request-Envelopes und Header für Geocode sind im WSDL definiert und können je nach SOAP-Version variieren.

Authentifizierung#

REST-Authentifizierung (X-API-Key)

Übermitteln Sie Ihren TrackServiceKey in jedem REST-Request im Header X-API-Key. Siehe API-Authentifizierung .

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

Bewahren Sie API-Schlüssel nach Möglichkeit serverseitig auf. Produktive API-Schlüssel sollten nicht direkt in Browser- oder Mobile-Client-Code eingebettet werden.

SOAP-Authentifizierung (SessionIDHeader)

SOAP-Anfragen verwenden einen SessionIDHeader. Bei TrackRoad SOAP-Services senden Sie Ihren TrackServiceKey als Wert von SessionID bei jedem Aufruf. Veraltete Login/Logout-Methoden können in älterer Dokumentation noch erscheinen, sind für moderne Nutzung jedoch nicht erforderlich.

Empfehlung: REST bevorzugen, außer Sie müssen in ein bestehendes reines SOAP-System integrieren.

Request-Schema#

Der Request-Body ist ein einzelnes GeocodeSpecification-Objekt. Geben Sie eine oder mehrere Adressen an, die geocodiert werden sollen.

GeocodeSpecification

Eigenschaft Typ Erforderlich Beschreibung
IsNeedMatchCode bool Nein Wenn true, werden Match-Qualitätsindikatoren im Ergebnis zurückgegeben. Für produktive Integrationen empfohlen.
Addresses Address[] Ja* Eine oder mehrere zu geocodierende Adressen. Jede Adresse zählt als Transaktion.

Address

Address ist ein gemeinsames Modell, das in mehreren Endpunkten verwendet wird. Das vollständige Address-Schema ist auch dokumentiert unter Dispatch API (gemeinsame Modelle) .

Eigenschaft Typ Erforderlich Beschreibung
Street string Empfohlen Straßenadresszeile.
City string Empfohlen Stadt oder Ort.
State string Nein Bundesland, Provinz oder Region.
PostalCode string Nein Postleitzahl.
Country string Empfohlen Ländercode oder Ländername, zum Beispiel US.

Response-Schema#

Eine erfolgreiche Antwort liefert ein GeocodeResult mit einem oder mehreren GeocodeItem-Objekten. Jedes Element entspricht einer Eingabeadresse.

GeocodeResult

Eigenschaft Typ Beschreibung
Items GeocodeItem[] Ein Element pro Eingabeadresse. Jedes Element kann null, einen oder mehrere Kandidatenstandorte enthalten.
Errors Error[] Vom Service zurückgegebene Fehler oder Warnungen.
Status int (enum) Statuscode wie 0=None, 1=Success, 2=Failed oder 3=SuccessWithErrors.

GeocodeItem

Eigenschaft Typ Beschreibung
Address Address Die ursprüngliche Eingabeadresse.
Locations Location[] Mögliche Geocoding-Ergebnisse für die Adresse.

Location, LatLong, MatchCode

Diese Modelle werden von mehreren Endpunkten gemeinsam verwendet. Die vollständigen Schematabellen finden Sie in der Dispatch API (gemeinsame Modelle) .

Error

Eigenschaft Typ Beschreibung
Message string Für Menschen lesbare Fehler- oder Warnmeldung.

Beispiele#

Verwenden Sie die folgenden Bereiche für REST- und SOAP-Beispielanfragen sowie -antworten. Beispielcode kann sprachneutral bleiben und muss nicht lokalisiert werden.

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>

Häufige Fehler#

  • 401 / Unauthorized: fehlender oder ungültiger X-API-Key bei REST-Anfragen.
  • 403 / Forbidden: der Schlüssel ist möglicherweise gültig, aber blockiert, abgelaufen oder kann die Anfrage nicht verarbeiten.
  • Ungültige oder unvollständige Adresse: der Service kann null Kandidaten, schwache Treffer oder niedrige MatchCode-Werte zurückgeben.
  • SOAP-Authentifizierungsfehler: fehlender oder ungültiger SessionIDHeader, wobei SessionID Ihren TrackServiceKey enthalten muss.

Best Practices#

  • Geocoding-Ergebnisse cachen Sie in Ihrem System, damit dieselbe Adresse nicht wiederholt geocodiert werden muss, solange sie sich nicht ändert.
  • Stabile Adresseingaben verwenden wie Straße, Stadt, Region, Postleitzahl und Land, um Mehrdeutigkeiten zu reduzieren.
  • MatchCode verwenden, um Ergebnisse zu filtern oder freizugeben, wenn Datenqualität wichtig ist.
  • LatLong an Dispatch oder Route übergeben, nachdem geocodiert wurde, um die Performance zu verbessern und wiederholte Lookups zu vermeiden.
  • Wenn Geocode mehrere Kandidaten zurückgibt, wählen Sie den besten anhand der Trefferqualität und der formatierten Adresse, die am besten zu Ihren Geschäftsregeln passt.

FAQ#

Was macht die Geocode API?
Die Geocode API wandelt Postadressen in einen oder mehrere mögliche Standorte mit Breiten-/Längengrad-Koordinaten um und hilft Ihnen dabei, präzise Stop-Daten für Routing und Disposition vorzubereiten.
Wie authentifiziere ich mich bei der Geocode API?
Für REST senden Sie Ihren TrackServiceKey im Header X-API-Key. Für SOAP senden Sie Ihren TrackServiceKey im SessionIDHeader als SessionID.
Warum kann Geocoding mehrere Ergebnisse zurückgeben?
Einige Adressen sind mehrdeutig oder unvollständig. Deshalb kann die API mehrere mögliche Standorte zurückgeben. Verwenden Sie MatchCode und die zurückgegebenen Adressdetails, um das beste Ergebnis auszuwählen.
Warum sollte ich vor der Routenoptimierung geocodieren?
Geocoding vor der Routenoptimierung verbessert Routenpräzision, ETAs, Stop-Zuweisung und Distanzberechnungen, da sichergestellt wird, dass jeder Stopp gültige Koordinaten besitzt.

Nächster Schritt: Routen mit präzisen Koordinaten optimieren

Nach dem Geocoding von Adressen verwenden Sie Dispatch oder Route mit Breiten-/Längengrad-Koordinaten, um präzisere ETAs, Entfernungen und Routensequenzen zu erzeugen.

Zur Dispatch API Swagger UI öffnen