API de Geocodificação (Endereço → Latitude/Longitude)

Use o Geocode para converter endereços postais em coordenadas de latitude/longitude. A geocodificação é normalmente o primeiro passo antes do planeamento de rotas ou da otimização de dispatch quando ainda não dispõe de coordenadas fiáveis para as paragens.

API de Geocodificação TrackRoad a converter um endereço em coordenadas de latitude/longitude para routing e dispatch.
Exemplo da API de Geocodificação: converter um endereço em coordenadas de latitude/longitude para routing e dispatch precisos.

Boa prática: valide as paragens antes da otimização de rotas

Endereços incorretos são uma das causas mais comuns de paragens em falta, rotas incorretas e falhas de otimização evitáveis. Faça primeiro a geocodificação e só depois chame Dispatch ou Route.

Visão geral da Referência da API Ver Swagger UI

Índice

  1. O que é a geocodificação e porque é importante
  2. O que o Geocode faz
  3. Compreender o MatchCode
  4. Endpoint REST e URL base
  5. Endpoint SOAP
  6. Autenticação
  7. Esquema do pedido
  8. Esquema da resposta
  9. Exemplos
  10. Erros comuns
  11. Boas práticas
  12. Endpoints relacionados
  13. Perguntas frequentes

O que é a geocodificação e porque é importante#

A geocodificação converte um endereço postal como 350 5th Ave, New York, NY em coordenadas de latitude/longitude que o software pode utilizar para routing, cálculo de ETA e medição de distâncias.

Os motores de otimização de rotas dependem de coordenadas de paragem precisas. Quando os endereços estão incompletos, ambíguos ou incorretos, os resultados das rotas tornam-se menos fiáveis.

  • Coordenadas incorretas podem originar rotas erradas, distâncias erradas e ETAs fracos.
  • A ausência de coordenadas pode conduzir a falhas de dispatch, paragens ignoradas ou trabalho não atribuído.
  • Endereços ambíguos podem resultar em valores de MatchCode baixos e resultados com menor confiança.

Se otimizar rotas sem validar primeiro os endereços, é mais provável que surjam paragens em falta, planos inviáveis ou baixa qualidade de rota.

O que o Geocode faz#

O Geocode aceita um ou mais objetos Address e devolve um ou mais resultados candidatos Location para cada endereço. Cada Location devolvida pode incluir coordenadas LatLong e um valor de MatchCode que ajuda a avaliar a qualidade da correspondência.

Transações: cada endereço geocodificado conta como uma transação, mesmo quando vários endereços são enviados no mesmo pedido.

Compreender o MatchCode#

O MatchCode é um indicador de confiança devolvido durante a geocodificação. Mostra quão de perto a TrackRoad fez corresponder o seu endereço de entrada a uma localização real.

  • MatchCode elevado normalmente significa uma correspondência mais precisa e é, regra geral, mais seguro para dispatch.
  • MatchCode baixo normalmente significa que o endereço está incompleto, é ambíguo ou é menos fiável.
  • Sem correspondência útil pode indicar um endereço inválido ou dados em falta de cidade, estado, código postal ou país.

Se o MatchCode for baixo, corrija o endereço ou envie latitude/longitude diretamente quando as coordenadas já forem conhecidas.

Endpoint REST e URL base#

Item Valor
URL base https://trackservice.trackroad.com
Endpoint POST /rest/geocode
URL completa https://trackservice.trackroad.com/rest/geocode
Content-Type application/json

Os pedidos REST de geocodificação usam POST e normalmente devolvem JSON. Dependendo dos detalhes da integração, o XML também pode ser suportado.

Endpoint SOAP#

Item Valor
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

Os envelopes e cabeçalhos dos pedidos SOAP para Geocode são definidos no WSDL e podem variar consoante a versão SOAP.

Autenticação#

Autenticação REST (X-API-Key)

Inclua a sua TrackServiceKey no cabeçalho X-API-Key em todos os pedidos REST. Consulte Autenticação da 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": [] }'

Mantenha as chaves da API no lado do servidor sempre que possível. Evite incorporar chaves de produção diretamente no código do browser ou da aplicação móvel.

Autenticação SOAP (SessionIDHeader)

Os pedidos SOAP usam um SessionIDHeader. Nos serviços SOAP da TrackRoad, envie a sua TrackServiceKey como valor de SessionID em cada chamada. Os métodos Login/Logout legados ainda podem aparecer em documentação antiga, mas não são necessários na utilização moderna.

Recomendado: prefira REST, a menos que tenha de integrar com um sistema existente apenas com SOAP.

Esquema do pedido#

O corpo do pedido é um único objeto GeocodeSpecification. Forneça um ou mais endereços que pretende geocodificar.

GeocodeSpecification

Propriedade Tipo Obrigatório Descrição
IsNeedMatchCode bool Não Se verdadeiro, inclui indicadores de qualidade da correspondência no resultado. Recomendado para integrações de produção.
Addresses Address[] Sim* Um ou mais endereços a geocodificar. Cada endereço conta como uma transação.

Address

Address é um modelo partilhado entre endpoints. O esquema completo de Address também está documentado em API Dispatch (modelos partilhados) .

Propriedade Tipo Obrigatório Descrição
Street string Recomendado Linha de endereço.
City string Recomendado Cidade ou localidade.
State string Não Estado, província ou região.
PostalCode string Não Código ZIP ou código postal.
Country string Recomendado Código do país ou nome do país, por exemplo US.

Esquema da resposta#

Uma resposta bem-sucedida devolve um GeocodeResult que contém um ou mais objetos GeocodeItem. Cada item corresponde a um endereço de entrada.

GeocodeResult

Propriedade Tipo Descrição
Items GeocodeItem[] Um item por endereço de entrada. Cada item pode conter zero, uma ou várias localizações candidatas.
Errors Error[] Erros ou avisos devolvidos pelo serviço.
Status int (enum) Código de estado como 0=None, 1=Success, 2=Failed ou 3=SuccessWithErrors.

GeocodeItem

Propriedade Tipo Descrição
Address Address O endereço original de entrada.
Locations Location[] Resultados candidatos de geocodificação para o endereço.

Location, LatLong, MatchCode

Estes modelos são partilhados entre endpoints. Consulte as tabelas completas do esquema em API Dispatch (modelos partilhados) .

Error

Propriedade Tipo Descrição
Message string Mensagem de erro ou aviso legível por humanos.

Exemplos#

Use as secções seguintes para pedidos e respostas de exemplo em REST e SOAP. O código de exemplo pode permanecer neutro em relação ao idioma e não precisa de localização.

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>

Erros comuns#

  • 401 / Não autorizado: X-API-Key em falta ou inválido nos pedidos REST.
  • 403 / Proibido: a chave pode ser válida, mas estar bloqueada, expirada ou incapaz de processar o pedido.
  • Endereço inválido ou incompleto: o serviço pode devolver zero candidatos, correspondências fracas ou valores de MatchCode baixos.
  • Falha de autenticação SOAP: SessionIDHeader em falta ou inválido, em que SessionID deve conter a sua TrackServiceKey.

Boas práticas#

  • Coloque os resultados de geocodificação em cache no seu sistema para não geocodificar repetidamente o mesmo endereço, a menos que ele mude.
  • Utilize dados de endereço estáveis como rua, cidade, estado, código postal e país para reduzir a ambiguidade.
  • Use o MatchCode para filtrar ou aprovar resultados quando a qualidade dos dados for importante.
  • Envie LatLong para Dispatch ou Route após a geocodificação para melhorar o desempenho e evitar pesquisas repetidas.
  • Se o Geocode devolver múltiplos candidatos, escolha o melhor usando a qualidade da correspondência e o endereço formatado que melhor se adapte às suas regras de negócio.

Perguntas frequentes#

O que faz a API de Geocodificação?
A API de Geocodificação converte endereços postais em uma ou mais localizações candidatas com coordenadas de latitude/longitude, ajudando a preparar dados de paragens precisos para routing e dispatch.
Como faço a autenticação na API de Geocodificação?
Para REST, envie a sua TrackServiceKey no cabeçalho X-API-Key. Para SOAP, envie a sua TrackServiceKey em SessionIDHeader como SessionID.
Porque pode a geocodificação devolver vários resultados?
Alguns endereços são ambíguos ou incompletos, por isso a API pode devolver várias localizações candidatas. Use o MatchCode e os detalhes do endereço devolvido para escolher o melhor resultado.
Porque devo fazer geocodificação antes da otimização de rotas?
Fazer geocodificação antes da otimização de rotas melhora a precisão das rotas, os ETAs, a atribuição de paragens e os cálculos de distância, garantindo que cada paragem tem coordenadas válidas.

Próximo passo: optimize rotas com coordenadas precisas

Depois de geocodificar os endereços, use Dispatch ou Route com coordenadas de latitude/longitude para gerar ETAs, distâncias e sequências de rotas mais precisos.

Ir para a API Dispatch Ver Swagger UI