APIs de mapas, pesquisa e Studio

Desenvolva com mapas e dados geográficos

Autenticação e erros

Envie a chave em Authorization: Bearer. Coordenadas: [longitude, latitude]. Defina OSRMROUTE_API_KEY localmente; DATASET_ID é o UUID de um conjunto próprio. Nunca publique uma chave Studio no navegador.

401: chave inválida · 403: sem permissão · 402: créditos insuficientes · 429: limite de pedidos · 502/503: fonte indisponível. Verifique o estado HTTP; operações pagas falhadas libertam os créditos reservados.

409: conflito de revisão. Leia o recurso atual e concilie as alterações antes de tentar novamente.

Pesquisa em linguagem natural

Encontre locais com consultas curtas em inglês.

Créditos por pedido: 2
Permissões necessárias: geocode + places

Categoria em inglês + near/in + local; raio de 100–5000 m. Seis categorias, até dez candidatos. Sem avaliações, preços ou disponibilidade em tempo real. Dois créditos mesmo para resultados vazios bem-sucedidos.

POST /api/v1/search/natural

Corpo do pedido — Os campos * são obrigatórios.
`q *`	`string`	`maxLength: 1000`
`ai`	`boolean`	`default: false`
`center`	`array`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/natural" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"cafes near Berlin within 2 km"}'

Resposta

intent
places[].distance_meters
places[].details
interpretation: constrained_english_grammar
exhaustive: false

Explorar a API Referência API

Detalhes dos locais

Consulte atributos fornecidos pela fonte.

Créditos por pedido: 1
Permissões necessárias: places

Um crédito com permissão places. Objeto OpenStreetMap pelo ID da pesquisa; cache de uma hora. Contactos, horários e acessibilidade ausentes ficam null. A data fonte é a edição do objeto, não verificação comercial. Sem estado de abertura em tempo real. 20 chamadas/min/chave; 30 leituras fonte/min globais fora do cache.

POST /api/v1/places/details

Corpo do pedido — Os campos * são obrigatórios.
`id *`	`string`	`maxLength: 24`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/places/details" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"osm:N:123"}'

Resposta

place.details.phone
place.details.website
place.details.opening_hours
place.details.wheelchair
place.details.observed_at
place.details.source_updated_at
place.details.open_now: null

Explorar a API Referência API

Prévia de estilo por texto

Descreva cores e camadas e reveja o mapa.

Créditos por pedido: 0
Permissões necessárias: studio

Comandos em inglês separados por ponto e vírgula: tema, cor hex e visibilidade. A prévia não guarda. Aplicar altera o rascunho e pode guardá-lo automaticamente.

POST /api/v1/studio/preview

Corpo do pedido — Os campos * são obrigatórios.
`prompt *`	`string`	`maxLength: 1000`
`ai`	`boolean`	`default: false`
`design`	`object`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/studio/preview" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"dark; water #123456; hide buildings"}'

Resposta

design
changes[]
saved: false
method: explicit_style_commands

Explorar a API Referência API

Static Maps API

Exporte mapas estilizados em PNG para relatórios e aplicações.

Créditos por pedido: 4
Permissões necessárias: maps

Quatro paletas: light, dark, navigation, minimal. 128–512 px, zoom 1–14. Renderização simplificada com atribuição; sem camadas ou efeitos personalizados do Studio.

POST /api/v1/maps/static

Corpo do pedido — Os campos * são obrigatórios.
`center *`	`array`
`zoom`	`integer`	`min: 1 · max: 14 · default: 12`
`width`	`integer`	`min: 128 · max: 512 · default: 512`
`height`	`integer`	`min: 128 · max: 512 · default: 512`
`style`	`string`	`light \| dark \| navigation \| minimal`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/maps/static" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"center":[13.405,52.52],"zoom":12,"width":512,"height":512,"style":"light"}' \
  --output map.png

Resposta

Content-Type: image/png

Explorar a API Referência API

Dataset Query API

Encontre elementos próximos nos seus próprios dados geográficos.

Créditos por pedido: 1
Permissões necessárias: maps

Apenas dados do proprietário da chave. Raio 0–50.000 m, limite 1–50. Pontos próximos e distâncias locais estimadas, não distâncias rodoviárias nem geometrias completas. Resultados vazios bem-sucedidos também custam 1 crédito.

POST /api/v1/maps/datasets/{id}/query

Corpo do pedido — Os campos * são obrigatórios.
`point *`	`array`
`radius`	`number`	`min: 0 · max: 50000 · default: 0`
`limit`	`integer`	`min: 1 · max: 50 · default: 10`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/maps/datasets/$DATASET_ID/query" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"point":[2.3522,48.8566],"radius":1000,"limit":10}'

Resposta

type: FeatureCollection
features[].geometry.type: Point
features[].properties
returned

Explorar a API Referência API

Search Along Route API

Compare paragens e tempo adicional de condução ao longo da rota.

Créditos por pedido: 14
Permissões necessárias: places + route

Rotas de condução até 200 km. Cinco posições amostradas e até oito desvios; pesquisa não exaustiva. fuel, charging_station, restaurant, cafe, parking, pharmacy. Sem trânsito em direto nem disponibilidade de carregadores.

POST /api/v1/places/along-route

Corpo do pedido — Os campos * são obrigatórios.
`start *`	`array`
`end *`	`array`
`category *`	`string`	`fuel \| charging_station \| restaurant \| cafe \| parking \| pharmacy`
`max_detour_seconds`	`number`	`min: 0 · max: 1800 · default: 600`
`limit`	`integer`	`min: 1 · max: 8 · default: 5`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/places/along-route" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":[13.405,52.52],"end":[13.3777,52.5163],"category":"cafe","max_detour_seconds":600,"limit":5}'

Resposta

places[]
baseline.duration_seconds
baseline.distance_meters
discovery
duration_model

Explorar a API Referência API

Structured Geocoding API

Pesquise endereços por rua, cidade, código postal e país.

Créditos por pedido: 1
Permissões necessárias: geocode

Inclua street, city ou postcode. País com duas letras; restantes campos até 100 caracteres. Componentes formam pesquisa textual. matched/different/missing e precisão da fonte não garantem validação do endereço.

POST /api/v1/search/structured

Corpo do pedido — Os campos * são obrigatórios.
`housenumber`	`string`	`maxLength: 100`
`street`	`string`	`maxLength: 100`
`city`	`string`	`maxLength: 100`
`state`	`string`	`maxLength: 100`
`postcode`	`string`	`maxLength: 100`
`countrycode`	`string`	`maxLength: 2`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/structured" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"street":"Friedrichstraße","city":"Berlin","countrycode":"DE"}'

Resposta

features[].id
features[].address
features[].precision
features[].match.components
features[].precision_basis
search_method: composed_address_query

Explorar a API Referência API

Suggest & Retrieve API

Crie pesquisa de locais com sugestões e recuperação segura.

Créditos por pedido: 1 + 1
Permissões necessárias: geocode

Suggest e retrieve custam 1 crédito cada. Consulta de 1–200 caracteres. Tokens válidos por 10 minutos, vinculados ao proprietário. Retrieve devolve a captura assinada, não uma nova pesquisa.

POST /api/v1/search/suggest

Corpo do pedido — Os campos * são obrigatórios.
`q *`	`string`	`maxLength: 200`

POST /api/v1/search/retrieve

Corpo do pedido — Os campos * são obrigatórios.
`token *`	`string`	`maxLength: 16384`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/suggest" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Paris"}'

Resposta

suggestions[].id
suggestions[].name
suggestions[].address
suggestions[].token
expires_in_seconds: 600

retrieve → place, retrieval: signed_suggestion_snapshot

cURL · retrieve

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/retrieve" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_SUGGEST"}'

Explorar a API Referência API

Studio API

Gira estilos, conjuntos de dados e publicação na sua aplicação.

Créditos por pedido: 0
Permissões necessárias: studio

Permissão studio explícita, mesmo para chaves sem restrições. GET lista estilos ou metadados; POST gere recursos. Estilos usam revisões e confirmação de publicação. Dados: criar/eliminar, sem edição direta. 30 leituras ou 5 escritas/minuto/chave; aplicam-se quotas do espaço.

GET / POST /api/v1/studio/{resource}

Corpo do pedido — Os campos * são obrigatórios.
`action *`	`string`
`id`	`string`
`revision`	`integer`
`name`	`string`	`maxLength: 80`
`design`	`object`
`data`	`object`
`confirmPublic`	`boolean`
`confirmDelete`	`boolean`
`version`	`integer`

cURL

curl --fail-with-body "https://osrmroute.com/api/v1/studio/styles" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY"

Resposta

GET styles → styles[]
GET datasets → datasets[]

Ações do Studio
`styles · create`	`name, design`
`styles · save / autosave`	`id, revision, name, design`
`styles · duplicate`	`id, revision, name`
`styles · restore`	`id, revision, version`
`styles · publish`	`id, revision, confirmPublic: true`
`styles · unpublish / delete`	`id, revision`
`datasets · create`	`name, data: GeoJSON FeatureCollection`
`datasets · delete`	`id, confirmDelete: true`

POST /api/v1/studio/styles · application/json

{
  "action": "create",
  "name": "Berlin",
  "design": {
    "preset": "light",
    "colors": {
      "land": "#f1f3f5",
      "water": "#a9d8ed",
      "park": "#c9dfc6",
      "road": "#ffffff",
      "highway": "#edc779",
      "building": "#d9dee3",
      "label": "#334155"
    },
    "visible": {
      "roads": true,
      "buildings": true,
      "parks": true,
      "labels": true,
      "pois": true,
      "boundaries": true
    },
    "center": [
      13.405,
      52.52
    ],
    "zoom": 11,
    "overlays": []
  }
}

POST /api/v1/studio/datasets · application/json

{
  "action": "create",
  "name": "Paris places",
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "name": "Paris"
        },
        "geometry": {
          "type": "Point",
          "coordinates": [
            2.3522,
            48.8566
          ]
        }
      }
    ]
  }
}

Explorar a API Referência API

APIs de mapas, pesquisa e Studio

Autenticação e erros

Pesquisa em linguagem natural

Detalhes dos locais

Prévia de estilo por texto

Static Maps API

Dataset Query API

Search Along Route API

Structured Geocoding API

Suggest & Retrieve API

Studio API

Suporte OSRMRoute

Como podemos ajudar?