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	`lat`, `lon`, plus either `q` or `category`
Optional query	`radius_mi`, `mode`, `limit`, `offset`, `min_confidence`, `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 or list a category near a location
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 128
        - name: category
          in: query
          required: false
          schema:
            type: string
            pattern: "^[a-z0-9][a-z0-9_:-]{0,127}$"
        - 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
        - name: min_confidence
          in: query
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 1
      responses:
        "200":
          description: Search completed, including zero-result searches.
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthError"