API Geocode (Adres → Szerokość/Długość geograficzna)

Użyj Geocode, aby konwertować adresy pocztowe na współrzędne szerokości i długości geograficznej. Geokodowanie jest zwykle pierwszym krokiem przed planowaniem tras lub optymalizacją dyspozycji, gdy nie masz jeszcze wiarygodnych współrzędnych punktów stop.

API Geocode TrackRoad konwertuje adres na współrzędne szerokości i długości geograficznej dla routingu i dyspozycji.
Przykład API Geocode: konwertuj adres na współrzędne szerokości i długości geograficznej dla dokładnego routingu i dyspozycji.

Najlepsza praktyka: zweryfikuj punkty stop przed optymalizacją tras

Błędne adresy są jedną z najczęstszych przyczyn brakujących punktów stop, nieprawidłowych tras i możliwych do uniknięcia błędów optymalizacji. Najpierw użyj Geocode, a potem wywołaj Dispatch lub Route.

Przegląd dokumentacji API Otwórz Swagger UI

Spis treści

  1. Czym jest geokodowanie i dlaczego jest ważne
  2. Co robi Geocode
  3. Zrozumienie MatchCode
  4. Endpoint REST i bazowy URL
  5. Endpoint SOAP
  6. Uwierzytelnianie
  7. Schemat żądania
  8. Schemat odpowiedzi
  9. Przykłady
  10. Typowe błędy
  11. Najlepsze praktyki
  12. Powiązane endpointy
  13. FAQ

Czym jest geokodowanie i dlaczego jest ważne#

Geokodowanie konwertuje adres pocztowy taki jak 350 5th Ave, New York, NY na współrzędne szerokości i długości geograficznej, których oprogramowanie może używać do routingu, obliczania ETA i pomiaru odległości.

Silniki optymalizacji tras zależą od dokładnych współrzędnych punktów stop. Gdy adresy są niepełne, niejednoznaczne lub błędne, wyniki tras stają się mniej wiarygodne.

  • Nieprawidłowe współrzędne mogą powodować błędne trasy, błędne odległości i słabe ETA.
  • Brak współrzędnych może prowadzić do błędów dyspozycji, pominiętych punktów stop lub nieprzydzielonej pracy.
  • Niejednoznaczne adresy mogą skutkować niskimi wartościami MatchCode i wynikami o mniejszej wiarygodności.

Jeśli optymalizujesz trasy bez wcześniejszej walidacji adresów, częściej zobaczysz brakujące punkty stop, niewykonalne plany lub niską jakość tras.

Co robi Geocode#

Geocode przyjmuje jeden lub więcej obiektów Address i zwraca jeden lub więcej kandydatów typu Location dla każdego adresu. Każda zwrócona Location może zawierać współrzędne LatLong oraz wartość MatchCode, która pomaga ocenić jakość dopasowania.

Transakcje: każdy geokodowany adres liczy się jako jedna transakcja, nawet gdy wiele adresów jest wysyłanych w jednym żądaniu.

Zrozumienie MatchCode#

MatchCode to wskaźnik pewności zwracany podczas geokodowania. Pokazuje, jak dobrze TrackRoad dopasował wprowadzony adres do rzeczywistej lokalizacji.

  • Wysoki MatchCode zwykle oznacza dokładniejsze dopasowanie i jest zazwyczaj bezpieczniejszy dla dyspozycji.
  • Niski MatchCode zwykle oznacza, że adres jest niepełny, niejednoznaczny lub mniej wiarygodny.
  • Brak użytecznego dopasowania może oznaczać nieprawidłowy adres lub brak danych dotyczących miasta, regionu, kodu pocztowego lub kraju.

Jeśli MatchCode jest niski, popraw adres albo wyślij bezpośrednio szerokość i długość geograficzną, gdy współrzędne są już znane.

Endpoint REST i bazowy URL#

Element Wartość
Bazowy URL https://trackservice.trackroad.com
Endpoint POST /rest/geocode
Pełny URL https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

Żądania REST geokodowania używają metody POST i zazwyczaj zwracają JSON. W zależności od szczegółów integracji może być obsługiwany także XML.

Endpoint SOAP#

Element Wartość
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

Koperty i nagłówki żądań SOAP dla Geocode są zdefiniowane w WSDL i mogą się różnić w zależności od wersji SOAP.

Uwierzytelnianie#

Uwierzytelnianie REST (X-API-Key)

Dołącz swój TrackServiceKey w nagłówku X-API-Key w każdym żądaniu REST. Zobacz Uwierzytelnianie 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": [] }'

Przechowuj klucze API po stronie serwera, jeśli to możliwe. Unikaj osadzania produkcyjnych kluczy API bezpośrednio w kodzie przeglądarki lub aplikacji mobilnej.

Uwierzytelnianie SOAP (SessionIDHeader)

Żądania SOAP używają SessionIDHeader. W usługach SOAP TrackRoad wyślij swój TrackServiceKey jako wartość SessionID przy każdym wywołaniu. Historyczne metody Login/Logout mogą nadal pojawiać się w starszej dokumentacji, ale nie są wymagane w nowoczesnym użyciu.

Zalecenie: preferuj REST, chyba że musisz zintegrować się z istniejącym systemem tylko SOAP.

Schemat żądania#

Treść żądania to pojedynczy obiekt GeocodeSpecification. Podaj jeden lub więcej adresów do geokodowania.

GeocodeSpecification

Właściwość Typ Wymagane Opis
IsNeedMatchCode bool Nie Jeśli true, do wyniku zostaną dołączone wskaźniki jakości dopasowania. Zalecane dla integracji produkcyjnych.
Addresses Address[] Tak* Jeden lub więcej adresów do geokodowania. Każdy adres liczy się jako jedna transakcja.

Address

Address to model współdzielony między endpointami. Pełny schemat Address jest również udokumentowany w Dispatch API (modele współdzielone) .

Właściwość Typ Wymagane Opis
Street string Zalecane Linia adresu ulicy.
City string Zalecane Miasto lub miejscowość.
State string Nie Stan, województwo lub region.
PostalCode string Nie Kod ZIP lub kod pocztowy.
Country string Zalecane Kod kraju lub nazwa kraju, na przykład US.

Schemat odpowiedzi#

Poprawna odpowiedź zwraca GeocodeResult zawierający jeden lub więcej obiektów GeocodeItem. Każdy element odpowiada jednemu adresowi wejściowemu.

GeocodeResult

Właściwość Typ Opis
Items GeocodeItem[] Jeden element dla każdego adresu wejściowego. Każdy element może zawierać zero, jedną lub wiele kandydackich lokalizacji.
Errors Error[] Błędy lub ostrzeżenia zwrócone przez usługę.
Status int (enum) Kod statusu, taki jak 0=None, 1=Success, 2=Failed lub 3=SuccessWithErrors.

GeocodeItem

Właściwość Typ Opis
Address Address Oryginalny adres wejściowy.
Locations Location[] Kandydackie wyniki geokodowania dla adresu.

Location, LatLong, MatchCode

Te modele są współdzielone między różnymi endpointami. Zobacz pełne tabele schematów w Dispatch API (modele współdzielone) .

Error

Właściwość Typ Opis
Message string Czytelny dla człowieka komunikat błędu lub ostrzeżenia.

Przykłady#

Użyj poniższych sekcji dla przykładowych żądań i odpowiedzi REST oraz SOAP. Kod przykładów może pozostać neutralny językowo i nie wymaga lokalizacji.

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>

Typowe błędy#

  • 401 / Unauthorized: brak nagłówka X-API-Key lub jest on nieprawidłowy w żądaniach REST.
  • 403 / Forbidden: klucz może być poprawny, ale zablokowany, wygasły lub niezdolny do przetworzenia żądania.
  • Nieprawidłowy lub niepełny adres: usługa może zwrócić zero kandydatów, słabe dopasowania lub niskie wartości MatchCode.
  • Błąd uwierzytelniania SOAP: brak lub nieprawidłowy SessionIDHeader, gdzie SessionID musi zawierać Twój TrackServiceKey.

Najlepsze praktyki#

  • Buforuj wyniki geokodowania w swoim systemie, aby nie geokodować wielokrotnie tego samego adresu, chyba że uległ zmianie.
  • Używaj stabilnych danych adresowych, takich jak ulica, miasto, region, kod pocztowy i kraj, aby zmniejszyć niejednoznaczność.
  • Używaj MatchCode do filtrowania lub zatwierdzania wyników, gdy jakość danych ma znaczenie.
  • Przekazuj LatLong do Dispatch lub Route po geokodowaniu, aby poprawić wydajność i uniknąć powtarzanych wyszukiwań.
  • Jeśli Geocode zwraca wielu kandydatów, wybierz najlepszego na podstawie jakości dopasowania i sformatowanego adresu najlepiej pasującego do Twoich reguł biznesowych.

FAQ#

Co robi API Geocode?
API Geocode konwertuje adresy pocztowe na jedną lub więcej kandydackich lokalizacji ze współrzędnymi szerokości i długości geograficznej, pomagając przygotować dokładne dane punktów stop dla routingu i dyspozycji.
Jak uwierzytelnić się w API Geocode?
Dla REST wyślij swój TrackServiceKey w nagłówku X-API-Key. Dla SOAP wyślij swój TrackServiceKey w SessionIDHeader jako SessionID.
Dlaczego geokodowanie może zwracać wiele wyników?
Niektóre adresy są niejednoznaczne lub niepełne, dlatego API może zwracać wiele kandydackich lokalizacji. Użyj MatchCode oraz zwróconych szczegółów adresu, aby wybrać najlepszy wynik.
Dlaczego warto geokodować przed optymalizacją tras?
Geokodowanie przed optymalizacją tras poprawia dokładność trasy, ETA, przypisanie punktów stop i obliczanie odległości, ponieważ zapewnia, że każdy punkt stop ma prawidłowe współrzędne.

Następny krok: optymalizuj trasy z dokładnymi współrzędnymi

Po geokodowaniu adresów użyj Dispatch lub Route ze współrzędnymi szerokości i długości geograficznej, aby uzyskać dokładniejsze ETA, odległości i sekwencje tras.

Przejdź do Dispatch API Otwórz Swagger UI