osrmroute-com Places API

openapi: 3.2.0
info:
  title: OSRMRoute Places API
  version: 1.1.0
  description: 'OSRMRoute — Maps, Routing, Truck Routing, Search, Road Data, Studio and integration APIs. Use `Authorization: Bearer ` unless an operation documents another flow. Legacy APIs also accept the key query parameter; New geospatial APIs, MCP and private map delivery require Bearer authentication. Mobile challenge/token endpoints use device attestation instead. Coordinates and units are documented per operation: GeoJSON uses longitude,latitude; some legacy and background-job inputs use latitude,longitude. Examples are illustrative, not guaranteed current results. Guides · Mobile Access · MCP · Postman collection.'
  contact:
    name: OSRMRoute Support
    url: https://osrmroute.com/contact
    email: support@osrmroute.com
  termsOfService: https://osrmroute.com/terms
servers:
- url: https://osrmroute.com
security:
- bearerAuth: []
- apiKeyQuery: []
tags:
- name: Places API
paths:
  /api/1/places:
    get:
      tags:
      - Places API
      summary: Places API
      description: The Places API discovers businesses and points of interest around any location — cafes, shops, hotels, ATMs, pharmacies and more. Provide a centre point, a radius and an optional category filter, and it returns nearby POIs sorted by distance, each with its name, type, address and exact coordinates. It runs on fresh OpenStreetMap data, so results stay current as the map evolves.
      operationId: get_places
      parameters:
      - name: point
        in: query
        required: true
        description: Center coordinate lat,lng to search around (required).
        schema:
          type: string
        example: 40.3755,49.8516
      - name: radius
        in: query
        required: false
        description: Search radius in kilometers (0.05–20, default 1).
        schema:
          type: number
        example: 1
      - name: category
        in: query
        required: false
        description: OSM tag filter, e.g. amenity:cafe, shop, tourism:hotel. Prefix with ! to exclude. Empty = all POIs.
        schema:
          type: string
        example: amenity:cafe
      - name: limit
        in: query
        required: false
        description: Max results to return (1–50, default 10).
        schema:
          type: integer
        example: 5
      - name: lang
        in: query
        required: false
        description: Preferred language for names (e.g. en, az, ru).
        schema:
          type: string
        example: en
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                success:
                  summary: Illustrative abbreviated response; values vary with input and map data.
                  value:
                    places:
                    - name: Example cafe
                      category: amenity
                      type: cafe
                      distance_m: 85
                      point:
                        lat: 40.3777
                        lng: 49.8516
                    took: 12
        '400':
          description: Error Codes (HTTP 400)
          content:
            application/json:
              examples:
                invalid:
                  value:
                    error: The "point" parameter (lat,lng) is required.
        '401':
          description: Error Codes (HTTP 401)
          content:
            application/json:
              examples:
                auth:
                  value:
                    error: Invalid API Key
        '402':
          description: Error Codes (HTTP 402)
          content:
            application/json:
              examples:
                balance:
                  value:
                    error: 'Insufficient balance: this request costs 1 credit and your balance is 0 credits. Top up your account to continue.'
        '403':
          description: Error Codes (HTTP 403)
          content:
            application/json:
              examples:
                plan:
                  value:
                    error: This API Key is disabled
        '429':
          description: Error Codes (HTTP 429)
          content:
            application/json:
              examples:
                rate:
                  value:
                    error: 'Rate limit exceeded: more than 60 requests per minute. Please slow down.'
        '500':
          description: Error Codes (HTTP 500)
          content:
            application/json:
              examples:
                upstream:
                  value:
                    error: Internal Server Error
        '502':
          description: Error Codes (HTTP 502)
          content:
            application/json:
              examples:
                upstream:
                  value:
                    error: Places service unavailable.
      x-credit-cost: 1 credit
      x-request-limits:
      - 'radius: 0.05–20 km'
      - 'limit: 1–50'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
    bearerAuth:
      type: http
      scheme: bearer