# Como pesquisar as paradas de transporte próximas com uma API?

> Descubra a pesquisa de paradas próximas com a API ROOTE: coordenadas, raio, exemplo em JavaScript, leitura dos resultados e gestão de erros.

Source: https://www.roote.ai/pt/guides/como-pesquisar-paradas-de-transporte-proximas-com-uma-api/
Language: pt
Author: ROOTE

Para pesquisar paradas ao redor de um ponto, envie sua latitude, longitude e um raio para uma API de proximidade. Depois, verifique o status da resposta, as entidades retornadas e as informações de cobertura antes de mostrar a lista ou o mapa.

No contrato ROOTE roote-1.0.0, a rota GET /v1/transit/nearby descobre os locais de transporte próximos. Ela não recupera partidas nem alertas em tempo real. A busca de um local e a busca de sua próxima partida são duas operações distintas.

## Definir os parâmetros

A requisição usa lat para a latitude e lng para a longitude. O alias lon também é descrito no contrato. O parâmetro radius expressa o raio em metros; limit limita o número de resultados solicitados. O filtro modes pode especificar os modos de transporte.

| Parâmetro | Exemplo | Sentido |
| --- | --- | --- |
| lat | 44.8378 | Latitude do ponto de busca |
| lng | -0.5792 | Longitude do ponto de busca |
| radius | 600 | Raio solicitado em metros |
| limit | 10 | Limite solicitado de resultados |
| modes | bus,tram | Modos pesquisados |

Estas coordenadas servem como exemplo de busca em Bordeaux; elas não indicam uma parada garantida. Consulte o [contrato OpenAPI ROOTE](https://api.roote.ai/openapi.json) para os limites, campos e condições atuais.

## Enviar uma primeira requisição no lado servidor

Aqui está um exemplo em JavaScript para um ambiente Node.js com fetch. O token, caso seu acesso use um, permanece em uma variável de ambiente no lado do servidor. O exemplo não requer colocar um segredo no navegador.

```
async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}
```

O contrato consultado prevê acesso anônimo ou com token, conforme as políticas aplicáveis. Verifique seus direitos e os limites de acesso. Uma resposta HTTP correta não dispensa validar seu conteúdo; em produção, utilize também uma validação dos objetos contra o esquema.

## Ler as entidades e suas relações

A coleção stations contém os locais retornados. Para cada um, consulte especialmente id, name, entity_kind, location e distance_meters. As referências line_ids e operator_ids permitem associar as coleções lines e operators quando estão fornecidas.

Exiba a distância geográfica como tal. Não a transforme em tempo de caminhada sem cálculo de rota. O guia [encontrar uma parada próxima](https://www.roote.ai/pt/guides/como-encontrar-o-ponto-de-onibus-ou-tram-mais-proximo/) explica porque os acessos podem modificar o deslocamento real.

Trate também as informações desconhecidas explicitamente. No contrato, accessibility.wheelchair pode valer unknown: este valor não equivale a yes nem a no. Uma capacidade de partidas anunciada não constitui uma lista de partidas.

## Exibir uma lista ou um mapa

Use o identificador para estabilizar os elementos da interface, o nome para seu rótulo e location para sua posição. Associe as linhas através das referências, em vez de aproximar seus nomes.

Se você exibir cores de linhas ou rótulos provenientes dos dados, trate-os como entradas externas a validar. Para os nomes, use texto em vez de HTML injetado.

Mantenha as atribuições das fontes e mostre as que o contrato exige.

## Gerenciar resultado vazio, resposta parcial e erro

Um resultado empty descreve uma busca sem resultado retornado no perímetro conhecido. Não prova ausência física de transportes. Uma resposta partial pode conter locais úteis enquanto indica limites: apresente os resultados e o aviso adequado.

Leia coverage, warnings e os limites aplicados em meta. Uma lista truncada não descreve uma cobertura exaustiva. Em caso de erro de rede ou HTTP, mostre uma indisponibilidade, sem substituir o resultado por “nenhuma parada”.

Para um código 429, consulte as orientações de retomada e os eventuais cabeçalhos do serviço. Evite relançamentos em loop.

## Distinguir estações, zonas e plataformas

O campo entity_kind diferencia vários níveis de locais. Dois resultados vizinhos podem corresponder a plataformas distintas; dois nomes similares podem pertencer a fontes diferentes.

Não fusione automaticamente os locais apenas pela proximidade. Use as relações e identidades documentadas pelo serviço. Nosso guia [GTFS, GTFS-RT e GBFS](https://www.roote.ai/pt/guides/gtfs-gtfs-rt-e-gbfs-quais-diferencas/) explica o contexto dos dados.

## Preparar a integração em produção

Dispare as buscas quando a posição ou os filtros mudarem de forma útil. Agrupe chamadas idênticas, defina um tempo limite e adapte o cache ao tipo de dado e às condições do serviço.

Uma lista de locais e uma disponibilidade em tempo real não têm as mesmas exigências de frescor. Valide o percurso com respostas completas, vazias, parciais e com erro antes de apresentar a busca aos usuários.

## Expandir a pesquisa para serviços urbanos

As paragens e os serviços urbanos utilizam rotas distintas. Para pesquisar casas de banho ao redor do mesmo ponto, a rota GET /v1/services/nearby espera lat e lon, com types=toilets. Não envie modes=toilets para essa rota: este vocabulário pertence ao URL do mapa, não ao filtro de Serviços.

O exemplo JavaScript seguinte constrói um URL Serviços para um raio de 600 metros. Ele não aciona a requisição; reutilize os controlos HTTP e de contrato descritos acima. A coleção esperada torna-se services, em vez de stations. Mantenha service_type, location, distance_meters e os atributos realmente presentes.

O contrato REST documenta, entre outros, toilets, drinking_water, fountain, wifi, parking, charging, aed e locker. Os tipos expostos pelo MCP podem diferir. Para os parâmetros aceites, seus limites e as restrições do seu acesso, consulte o esquema da interface utilizada.

Os atributos de um serviço não garantem sua abertura no momento da pesquisa. Uma acessibilidade desconhecida não equivale a um serviço inacessível; uma lista vazia resultante de um erro não prova a ausência de casas de banho. Mantenha os dados próprios a cada categoria em vez de reduzi-los a um nome e um ponto.

Para um mapa combinado, associe os resultados à sua categoria e aos seus identificadores. Exiba uma mensagem de erro Serviços sem apagar as paragens retornadas pelo Transit. A pesquisa permanece centrada no mesmo ponto, mas os status e as coberturas podem ser diferentes.

```
const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());
```

[Diagnosticar uma pesquisa vazia ou com erro](https://www.roote.ai/pt/guides/sem-resultados-ou-erro-api-como-diferenciar/)

[Integrar diretamente um mapa filtrado num site](https://www.roote.ai/pt/guides/como-integrar-um-mapa-de-mobilidade-no-seu-site/)

[Construir um assistente em torno destas pesquisas](https://www.roote.ai/pt/guides/como-criar-um-assistente-que-encontre-mobilidade-ao-redor-de-um-endereco/)

## Perguntas frequentes

### Nearby fornece as próximas partidas?

Não no contrato apresentado aqui. Esta rota descobre os locais de transporte; as partidas solicitam uma capacidade distinta.

### Pode-se exibir uma lista vazia após um erro?

Apresente uma indisponibilidade. Um erro não demonstra a ausência de paradas.

### Pode-se colocar o token API no navegador?

Um segredo deve permanecer no servidor. Use o modelo de acesso previsto para sua aplicação e sua conta.