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

map-marker-alt

Busca por Geolocalização

Sugestões baseadas na proximidade do usuário

check-circle

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

`GET /v4/places/by-location`

Busca lugares baseada em coordenadas geográficas ou informações de localização.

Parâmetros:

latitude / longitude - Coordenadas para busca por proximidade
radius - Raio de busca em quilômetros
cityName / state - Busca direta por cidade e estado

Exemplo:

GET /v4/places/by-location?latitude=-22.898&longitude=-43.209&radius=50

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"`

codeExemplo 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

tachometer-altPerformance Otimizada

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

userExperiência do Usuário

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

plugIntegração Simplificada

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

cogsFuncionalidades 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.

Lugares

Serviço de Lugares

Principais Recursos

Endpoints Disponíveis

`GET /v4/places`

`GET /v4/places/by-location`

Estrutura da Resposta

Fluxo de Implementação

1. Captura de Input

2. Busca de Sugestões

3. Seleção do Usuário

4. Armazenamento do Slug

5. Repetição para Destino

6. Integração Final

Vantagens da Implementação

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.

What’s Next

What’s Next

Serviço de Lugares

Principais Recursos

Endpoints Disponíveis

GET /v4/places

GET /v4/places/by-location

Estrutura da Resposta

Fluxo de Implementação

1. Captura de Input

2. Busca de Sugestões

3. Seleção do Usuário

4. Armazenamento do Slug

5. Repetição para Destino

6. Integração Final

Vantagens da Implementação

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.

What’s Next

What’s Next

`GET /v4/places`

`GET /v4/places/by-location`

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.