Geocode API (Adres → Breedtegraad/Lengtegraad)

Gebruik Geocode om postadressen om te zetten in breedte-/lengtegraadcoördinaten. Geocodering is meestal de eerste stap vóór routeplanning of dispatch-optimalisatie wanneer u nog geen betrouwbare stopcoördinaten hebt.

TrackRoad Geocode API zet een adres om in breedte-/lengtegraadcoördinaten voor routing en dispatch.
Voorbeeld van de Geocode API: zet een adres om in breedte-/lengtegraadcoördinaten voor nauwkeurige routing en dispatch.

Best practice: valideer stops vóór route-optimalisatie

Onjuiste adressen zijn een van de meest voorkomende oorzaken van ontbrekende stops, verkeerde routes en vermijdbare optimalisatiefouten. Geocodeer eerst en roep daarna Dispatch of Route aan.

Overzicht van API-referentie Swagger UI bekijken

Inhoudsopgave

  1. Wat geocodering is en waarom het belangrijk is
  2. Wat Geocode doet
  3. MatchCode begrijpen
  4. REST-endpoint en basis-URL
  5. SOAP-endpoint
  6. Authenticatie
  7. Aanvraagschema
  8. Responseschema
  9. Voorbeelden
  10. Veelvoorkomende fouten
  11. Best practices
  12. Gerelateerde endpoints
  13. FAQ

Wat geocodering is en waarom het belangrijk is#

Geocodering zet een postadres zoals 350 5th Ave, New York, NY om in breedte-/lengtegraadcoördinaten die software kan gebruiken voor routing, ETA-berekening en afstandsmeting.

Route-optimalisatie-engines zijn afhankelijk van nauwkeurige stopcoördinaten. Wanneer adressen onvolledig, dubbelzinnig of onjuist zijn, worden routeresultaten minder betrouwbaar.

  • Onjuiste coördinaten kunnen leiden tot verkeerde routes, verkeerde afstanden en slechte ETA's.
  • Ontbrekende coördinaten kunnen leiden tot dispatchfouten, overgeslagen stops of niet-toegewezen werk.
  • Dubbelzinnige adressen kunnen resulteren in lage MatchCode-waarden en resultaten met minder vertrouwen.

Als u routes optimaliseert zonder eerst adressen te valideren, is de kans groter op ontbrekende stops, onuitvoerbare plannen of slechte routekwaliteit.

Wat Geocode doet#

Geocode accepteert een of meer Address-objecten en retourneert een of meer kandidaat-Location-resultaten voor elk adres. Elke geretourneerde Location kan LatLong-coördinaten en een MatchCode-waarde bevatten die helpt om de matchkwaliteit te beoordelen.

Transacties: elk gegeocodeerd adres telt als één transactie, zelfs wanneer meerdere adressen in hetzelfde verzoek worden verzonden.

MatchCode begrijpen#

MatchCode is een vertrouwensindicator die tijdens het geocoderen wordt geretourneerd. Het laat zien hoe nauwkeurig TrackRoad uw ingevoerde adres heeft gekoppeld aan een echte locatie.

  • Hoge MatchCode betekent meestal een nauwkeurigere match en is doorgaans veiliger voor dispatch.
  • Lage MatchCode betekent meestal dat het adres onvolledig, dubbelzinnig of minder betrouwbaar is.
  • Geen bruikbare match kan wijzen op een ongeldig adres of ontbrekende gegevens voor stad, staat, postcode of land.

Als de MatchCode laag is, corrigeer dan het adres of stuur breedte-/lengtegraad direct mee wanneer de coördinaten al bekend zijn.

REST-endpoint en basis-URL#

Item Waarde
Basis-URL https://trackservice.trackroad.com
Endpoint POST /rest/geocode
Volledige URL https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

REST-geocodeverzoeken gebruiken POST en retourneren doorgaans JSON. Afhankelijk van integratiedetails kan XML ook worden ondersteund.

SOAP-endpoint#

Item Waarde
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-verzoekenveloppen en headers voor Geocode zijn gedefinieerd in de WSDL en kunnen per SOAP-versie verschillen.

Authenticatie#

REST-authenticatie (X-API-Key)

Neem uw TrackServiceKey op in de X-API-Key-header bij elk REST-verzoek. Zie API-authenticatie .

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

Bewaar API-sleutels waar mogelijk aan de serverzijde. Vermijd het rechtstreeks insluiten van productie-API-sleutels in browser- of mobiele clientcode.

SOAP-authenticatie (SessionIDHeader)

SOAP-verzoeken gebruiken een SessionIDHeader. Voor TrackRoad SOAP-services verstuurt u uw TrackServiceKey als de waarde van SessionID bij elke call. Verouderde Login/Logout-methoden kunnen nog in oudere documentatie voorkomen, maar zijn voor modern gebruik niet vereist.

Aanbevolen: gebruik bij voorkeur REST, tenzij u moet integreren met een bestaand systeem dat alleen SOAP ondersteunt.

Aanvraagschema#

De request body is één GeocodeSpecification-object. Geef een of meer adressen op die u wilt geocoderen.

GeocodeSpecification

Eigenschap Type Verplicht Beschrijving
IsNeedMatchCode bool Nee Indien true, worden indicatoren voor matchkwaliteit in het resultaat opgenomen. Aanbevolen voor productie-integraties.
Addresses Address[] Ja* Eén of meer adressen om te geocoderen. Elk adres telt als één transactie.

Address

Address is een gedeeld model over meerdere endpoints heen. Het volledige Address-schema is ook gedocumenteerd op Dispatch API (gedeelde modellen) .

Eigenschap Type Verplicht Beschrijving
Street string Aanbevolen Straatadresregel.
City string Aanbevolen Stad of plaats.
State string Nee Staat, provincie of regio.
PostalCode string Nee ZIP-code of postcode.
Country string Aanbevolen Landcode of landnaam, bijvoorbeeld US.

Responseschema#

Een succesvol antwoord retourneert een GeocodeResult met een of meer GeocodeItem-objecten. Elk item komt overeen met één ingevoerd adres.

GeocodeResult

Eigenschap Type Beschrijving
Items GeocodeItem[] Eén item per ingevoerd adres. Elk item kan nul, één of meerdere kandidaatlocaties bevatten.
Errors Error[] Fouten of waarschuwingen die door de service worden geretourneerd.
Status int (enum) Statuscode zoals 0=None, 1=Success, 2=Failed of 3=SuccessWithErrors.

GeocodeItem

Eigenschap Type Beschrijving
Address Address Het oorspronkelijke ingevoerde adres.
Locations Location[] Kandidaatresultaten van de geocodering voor het adres.

Location, LatLong, MatchCode

Deze modellen worden gedeeld tussen endpoints. Zie de volledige schematabellen op Dispatch API (gedeelde modellen) .

Error

Eigenschap Type Beschrijving
Message string Voor mensen leesbare fout- of waarschuwingsmelding.

Voorbeelden#

Gebruik de volgende secties voor REST- en SOAP-voorbeeldverzoeken en -antwoorden. Voorbeeldcode kan taaloneutraal blijven en hoeft niet gelokaliseerd te worden.

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>

Veelvoorkomende fouten#

  • 401 / Unauthorized: ontbrekende of ongeldige X-API-Key bij REST-verzoeken.
  • 403 / Forbidden: de sleutel kan geldig zijn, maar geblokkeerd, verlopen of niet in staat om het verzoek te verwerken.
  • Ongeldig of onvolledig adres: de service kan nul kandidaten, zwakke matches of lage MatchCode-waarden retourneren.
  • SOAP-authenticatiefout: ontbrekende of ongeldige SessionIDHeader, waarbij SessionID uw TrackServiceKey moet bevatten.

Best practices#

  • Cache geocoderesultaten in uw systeem zodat u niet steeds hetzelfde adres opnieuw geocodeert, tenzij het wijzigt.
  • Gebruik stabiele adresinvoer zoals straat, stad, staat, postcode en land om dubbelzinnigheid te verminderen.
  • Gebruik MatchCode om resultaten te filteren of goed te keuren wanneer gegevenskwaliteit belangrijk is.
  • Stuur LatLong naar Dispatch of Route na het geocoderen om prestaties te verbeteren en herhaalde opzoekingen te vermijden.
  • Als Geocode meerdere kandidaten retourneert, kies dan de beste op basis van matchkwaliteit en het opgemaakte adres dat het beste aansluit op uw bedrijfsregels.

FAQ#

Wat doet de Geocode API?
De Geocode API zet postadressen om in een of meer kandidaatlocaties met breedte-/lengtegraadcoördinaten, zodat u nauwkeurige stopgegevens kunt voorbereiden voor routing en dispatch.
Hoe authenticeer ik bij de Geocode API?
Voor REST stuurt u uw TrackServiceKey mee in de X-API-Key-header. Voor SOAP stuurt u uw TrackServiceKey mee in SessionIDHeader als SessionID.
Waarom kan geocodering meerdere resultaten teruggeven?
Sommige adressen zijn dubbelzinnig of onvolledig, waardoor de API meerdere kandidaatlocaties kan retourneren. Gebruik MatchCode en de geretourneerde adresgegevens om het beste resultaat te kiezen.
Waarom moet ik geocoderen vóór route-optimalisatie?
Geocoderen vóór route-optimalisatie verbetert de nauwkeurigheid van routes, ETA's, stoptoewijzing en afstandsberekeningen doordat elke stop geldige coördinaten heeft.

Próximo passo: otimize rotas com coordenadas precisas

Gebruik na het geocoderen van adressen Dispatch of Route met breedte-/lengtegraadcoördinaten om nauwkeurigere ETA's, afstanden en routesequenties te genereren.

Ga naar Dispatch API Swagger UI bekijken