Serviço de Lugares

O serviço de Lugares oferece funcionalidades completas para busca, autocomplete e validação de localidades, facilitando a implementação de campos de origem e destino em aplicações de busca de viagens.

Principais Recursos

Autocomplete Inteligente

Busca rápida e contextual por nome de cidade ou terminal

Busca por Geolocalização

Sugestões baseadas na proximidade do usuário

Validação de Localidades

IDs canônicos para integração segura com outros serviços

Endpoints Disponíveis

`GET /v4/places`

Busca lugares através de termos de pesquisa como nome de cidade ou terminal.

Parâmetros:

name - Termo de pesquisa (obrigatório)
limit - Máximo de resultados retornados (padrão: 20)
fields - Campos específicos na resposta (opcional)

Exemplo:

GET /v4/places?name=rio&limit=10

Estrutura da Resposta

Os dados retornados incluem os seguintes campos essenciais:

Campo	Tipo	Descrição	Exemplo
`name`	string	Nome formatado para exibição ao usuário	`"Rio de Janeiro, RJ - Rodov. do Rio"`
`slug`	string	Identificador único para uso em `/v5/trips`	`"rio-de-janeiro-rj-novo-rio"`
`useGroupByCity`	boolean	Indica se há múltiplos terminais na cidade	`true`
`terminal.name`	string	Nome específico do terminal	`"Rodoviaria do Rio"`
`latlon`	string	Coordenadas no formato lat,lon	`"-22.89803,-43.209162"`

Exemplo de Resposta Completa

{
  "data": [
    {
      "id": 123,
      "name": "Rio de Janeiro, RJ - Rodov. do Rio",
      "slug": "rio-de-janeiro-rj-novo-rio",
      "useGroupByCity": true,
      "terminal": {
        "name": "Rodoviaria do Rio",
        "id": 456
      },
      "latlon": "-22.89803,-43.209162",
      "city": "Rio de Janeiro",
      "state": "RJ"
    }
  ]
}

Fluxo de Implementação

1. Captura de Input

Cliente digita o nome da cidade de origem

2. Busca de Sugestões

Aplicação chama /v4/places?name=sao

3. Seleção do Usuário

Cliente escolhe uma opção da lista retornada

4. Armazenamento do Slug

Aplicação salva o campo slug do resultado

5. Repetição para Destino

Mesmo processo para cidade de destino

6. Integração Final

Usa os slugs em /v5/trips nos parâmetros from e to

Vantagens da Implementação

Performance Otimizada

Sistema de filtros e indexação otimizados para respostas rápidas, mesmo com grandes volumes de dados.

Experiência do Usuário

Interface de autocomplete intuitiva que facilita a seleção de localidades, reduzindo erros de digitação.

Integração Simplificada

Uso de slugs canônicos garante consistência na integração com outros serviços da API.

Funcionalidades Avançadas

Suporte a geolocalização, agrupamento por cidade e múltiplos terminais para máxima flexibilidade.

💡
Dica: Sempre utilize o campo slug retornado pela API de Lugares como identificador nas chamadas para /v5/trips. Isso garante a consistência dos dados e evita problemas de integração.