SearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usestring-ai/json-schema/usestring-ai-search-request-schema.json",
  "title": "SearchRequest",
  "description": "Request body for POST /search. Any other field is rejected with a 400.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usestring-ai-openapi.json#/components/schemas/SearchRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query to run."
    },
    "engine": {
      "type": "string",
      "enum": [
        "google",
        "duckduckgo",
        "brave",
        "mojeek",
        "google_ai_mode"
      ],
      "default": "google",
      "description": "Search engine. `google_ai_mode` returns Google's AI Mode answer in `aiMode` instead of ranked results."
    },
    "country": {
      "type": "string",
      "default": "US",
      "description": "ISO 3166-1 alpha-2 country code used to localize results. Case-insensitive. Applies to every engine."
    },
    "language": {
      "type": "string",
      "description": "Language tag for result language, such as `en` or `pt-br`. Applies to every engine."
    },
    "searchCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300,
      "description": "Number of organic results wanted. Google is paged until that many are collected (each page that answered bills as one search); the response then includes `paging`. With `page` N set, the maximum is 300 - (N-1)*10. Rejected with `format: raw` and with `google_ai_mode`. Without it, one results page is returned (about 8 to 10 Google results)."
    },
    "location": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Place name to search from, such as `London` or `Paris,Texas,United States`. `google` and `google_ai_mode` only. A name that cannot be placed is a 400; send `coordinates` instead."
    },
    "coordinates": {
      "allOf": [
        {
          "$ref": "#/$defs/SearchCoordinates"
        }
      ],
      "description": "Point to search from. `google` and `google_ai_mode` only. Wins over `location` if both are sent."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 30,
      "default": 1,
      "description": "Google results page to start from; page N is the page Google shows as N. On `images` the range is 1 to 3; on `shopping` it must be 1. A page past the last result returns empty `results` with `zeroResults: true`. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "dateRange": {
      "$ref": "#/$defs/SearchDateRange"
    },
    "sortBy": {
      "type": "string",
      "enum": [
        "relevance",
        "date"
      ],
      "default": "relevance",
      "description": "Result order. `date` puts the newest first. `web`, `videos` and `forums` search types only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "format": {
      "type": "string",
      "enum": [
        "structured",
        "raw"
      ],
      "default": "structured",
      "description": "`structured` returns results as JSON (recommended). `raw` returns the Google results page as HTML (`text/html`), one page per request; choose the page with `page`. `raw` applies to the `web` search type only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "aiOverview": {
      "type": "boolean",
      "default": false,
      "description": "Make a second, sequential fetch to fill an AI Overview that Google streams in after the page loads. Adds latency and bills as two searches. Without it, a streamed overview comes back as `declined: true`. `web` search type only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "searchType": {
      "type": "string",
      "enum": [
        "web",
        "images",
        "videos",
        "shopping",
        "books",
        "places",
        "forums"
      ],
      "default": "web",
      "description": "Google tab to search. `images` answers in `images`, `places` in `places`, `shopping` in `products` (with `results` empty); the other tabs answer in `results`. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "safeSearch": {
      "type": "boolean",
      "default": false,
      "description": "`true` removes explicit results (Google SafeSearch). `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "includeOmittedResults": {
      "type": "boolean",
      "default": false,
      "description": "`true` includes results Google normally hides as very similar to ones already shown. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "autocorrect": {
      "type": "boolean",
      "default": true,
      "description": "`false` searches the query exactly as sent instead of Google's corrected spelling. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "restrictCountry": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 code. Returns only pages from that country (unlike `country`, which sets where the search is made from). `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    },
    "verbatim": {
      "type": "boolean",
      "default": false,
      "description": "`true` matches the query's words exactly, without synonyms or variations. `web`, `videos` and `forums` search types only. `google` engine only; sending it with another engine (Google AI Mode included) is a 400."
    }
  },
  "$defs": {
    "SearchCoordinates": {
      "type": "object",
      "description": "An exact point to search from. Takes precedence over `location`.",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Decimal degrees."
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Decimal degrees."
        },
        "radius": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000,
          "default": 5000,
          "description": "How precise the point is, in meters."
        }
      }
    },
    "SearchDateRange": {
      "description": "Publication window. A preset (`hour`, `day`, `week`, `month`, `year` for the past hour through the past year), or a custom range of ISO calendar dates. `google` engine only; `web`, `videos` and `forums` search types only.",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "week",
            "month",
            "year"
          ]
        },
        {
          "type": "object",
          "description": "Custom range. Needs `from`, `to` or both, and `from` must not be after `to`.",
          "minProperties": 1,
          "properties": {
            "from": {
              "type": "string",
              "format": "date",
              "description": "First day of the range, inclusive (YYYY-MM-DD)."
            },
            "to": {
              "type": "string",
              "format": "date",
              "description": "Last day of the range, inclusive (YYYY-MM-DD)."
            }
          }
        }
      ]
    }
  }
}