Contract overview

Inspect the shape before using the source file.

The OpenAPI contract is the canonical machine-readable description of the public Places API. Use this page to scan the endpoint, auth model, parameters, and response families before downloading the YAML.

OpenAPI 3.1 Single public contract for client generation, tests, and schema inspection.

Bearer auth Server-side API keys in the opa_live_... format.

One search route GET /v1/places with location-scoped query parameters.

Area	What the contract defines
Server	`https://api.openplacesapi.com`
Operation	`searchPlaces` on `GET /v1/places`
Required query	`q`, `lat`, and `lon`
Optional query	`radius_mi`, `mode`, `limit`, `layers`, and `layer_preset`
Responses	Success, validation, auth, quota, layer authorization, rate limit, and service availability responses.

Download

Use the YAML when tooling needs the source contract.

Download the full file for generated clients, contract tests, or importing into API tooling. You can also open the raw YAML in the browser when you want the exact source text.

Download YAML View raw YAML Back to API reference

YAML preview

Representative excerpt from the contract.

OpenAPI excerpt

openapi: 3.1.0
info:
  title: Open Places API
  version: 1.0.0
servers:
  - url: https://api.openplacesapi.com
security:
  - bearerApiKey: []
paths:
  /v1/places:
    get:
      operationId: searchPlaces
      summary: Search places by text near a location
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 3
            maxLength: 128
        - name: lat
          in: query
          required: true
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: lon
          in: query
          required: true
          schema:
            type: number
            minimum: -180
            maximum: 180
      responses:
        "200":
          description: Search completed, including zero-result searches.
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthError"