{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/serpkite-com/json-schema/serpkite-com-place-request-schema.json",
  "title": "PlaceRequest",
  "description": "One of place_id, cid or fid (Google; place_id wins, then fid, then cid) or oid (Yandex Maps) is required",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/serpkite-com-place-api-openapi.yml#/components/schemas/PlaceRequest",
  "type": "object",
  "properties": {
    "place_id": {
      "type": "string",
      "description": "Google place id (\"ChIJ…\"), e.g. `place_id` of a /v1/maps result"
    },
    "cid": {
      "type": "string",
      "description": "Decimal customer id (`cid` of a result)"
    },
    "fid": {
      "type": "string",
      "description": "Feature id \"0x…:0x…\" (`fid` of a result)"
    },
    "oid": {
      "type": "string",
      "pattern": "^[0-9]{1,20}$",
      "description": "Yandex Maps organisation id (`oid` of an `engine=yandex` maps result). Implies `engine=yandex`; not with place_id, cid or fid"
    },
    "country": {
      "type": "string",
      "default": "us",
      "description": "Country code (ISO 3166-1 alpha-2); Google's regional view of the listing"
    },
    "language": {
      "type": "string",
      "default": "en",
      "description": "Language of the address, categories, hours and description (e.g. en, ru, de)"
    },
    "format": {
      "type": "string",
      "enum": [
        "json",
        "markdown",
        "compact"
      ],
      "default": "json"
    },
    "fields": {
      "type": "string"
    },
    "max_age": {
      "type": "integer",
      "minimum": 0,
      "description": "Accept a cached result up to this many seconds old (50% of credits on a hit)"
    },
    "engine": {
      "$ref": "#/$defs/EngineParam"
    }
  },
  "$defs": {
    "EngineParam": {
      "description": "Which search providers may answer. `google` (the default) is Google only; Google requests are retried internally before failing. `auto` allows falling back to other enabled providers, in route order, when Google is blocked or times out. A single other provider (`brave`) or a list (`[\"google\",\"brave\"]`, or `google,brave` in a query string) restricts the request to those providers. `meta.engine` always names the provider that answered and credits follow that provider's price. A key with \"Allow fallback to other search engines\" on treats a request without `engine` as `auto`. `consensus` (`/v1/search` only; 400 elsewhere, and it can't be combined with other names) queries several independent search indexes in parallel (at most one Bing-backed provider, so Yahoo or DuckDuckGo never count as agreeing with Bing), merges the results by URL and ranks them by how many providers returned each one. Each result lists its `sources`; `meta.engine` is `consensus` and `meta.route` lists every provider attempt. Up to three providers answer: a provider that fails or comes back empty hands its turn to the next one in the route. It stops once `num` unique results are in hand or after a few seconds, and costs the sum of one page at each provider that returned results (providers that failed, came back empty or were never started are free). `yandex` serves `/v1/search` from Yandex web search (no `time` filter or `safe: active`: a request naming it gets a 400 with them) and `/v1/maps`, `/v1/places` and `/v1/place` from Yandex Maps, where the deployment enables it (otherwise a 503 `unavailable`, not charged); with `auto` it is the last fallback there.",
      "oneOf": [
        {
          "type": "string",
          "default": "google"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Provider"
          },
          "minItems": 1
        }
      ]
    },
    "Provider": {
      "type": "string",
      "description": "A search provider (docs/providers). Which verticals each serves depends on the deployment.",
      "enum": [
        "google",
        "brave",
        "bing",
        "yahoo",
        "duckduckgo",
        "mojeek",
        "wikipedia",
        "yandex"
      ]
    }
  }
}