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

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.

Estas coordenadas servem como exemplo de busca em Bordeaux; elas não indicam uma parada garantida. Consulte o contrato OpenAPI ROOTE 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 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 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

Integrar diretamente um mapa filtrado num site

Construir um assistente em torno destas pesquisas

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.