osrmroute-com Nearest API

openapi: 3.2.0
info:
  title: OSRMRoute Nearest 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: Nearest API
paths:
  /api/v1/osrm/nearest/v1/{profile}/{coordinates}:
    get:
      tags:
      - Nearest API
      summary: Nearest API
      description: The Nearest API snaps any coordinate to the closest point on the real road network and returns the matched location. It is the building block for cleaning user input before routing, validating pickup/drop-off points, and finding which road a coordinate belongs to. Fast and precise, it underpins reliable routing pipelines.
      operationId: get_nearest
      parameters:
      - name: profile
        in: path
        required: true
        description: Transport profile.
        schema:
          type: string
        example: driving
      - name: coordinates
        in: path
        required: true
        description: 'The point to search near. Format: lon,lat (a single pair).'
        schema:
          type: string
        example: 49.8516,40.3755
      - name: number
        in: query
        required: false
        description: The number of nearest road candidates to find.
        schema:
          type: integer
        example: '1'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                success:
                  summary: Illustrative abbreviated response; values vary with input and map data.
                  value:
                    code: Ok
                    waypoints:
                    - name: Example road
                      location:
                      - 49.8516
                      - 40.3777
                      distance: 4.2
        '400':
          description: Error Codes (HTTP 400)
          content:
            application/json:
              examples:
                InvalidQuery:
                  value:
                    code: InvalidQuery
                    error: Coordinates must be finite longitude,latitude pairs.
        '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
        '422':
          description: Error Codes (HTTP 422)
          content:
            application/json:
              examples:
                ProfileNotAvailable:
                  value:
                    code: ProfileNotAvailable
                    error: This travel profile is not available at one or more coordinates. No driving fallback was used.
                NoNearbyRoad:
                  value:
                    code: NoNearbyRoad
                    error: No connected route within 2000 metres of the requested coordinates.
        '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
      x-credit-cost: 1 credit
      x-request-limits:
      - 'coordinates: 1'
      - 'number: default = 1; example = 3'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
    bearerAuth:
      type: http
      scheme: bearer