{
  "openapi": "3.1.0",
  "info": {
    "title": "Yahoo Search API Reference",
    "version": "1.0.0",
    "description": "SerpApi-compatible Yahoo Search (`engine=yahoo`) on Lempile's `GET /search.json`, from real browsers. Fresh searches are queue-first: the API stores the search, returns HTTP 202 with polling endpoints, and a browser runs it when an IP is free.",
    "contact": {}
  },
  "servers": [
    {
      "url": "https://api.lempile.com",
      "description": "Primary Lempile production API host."
    }
  ],
  "tags": [
    {
      "name": "Yahoo Search",
      "description": "SerpApi-compatible Yahoo organic results.",
      "externalDocs": {
        "url": "https://serpapi.com/yahoo-search-api",
        "description": "Compatibility target: SerpApi Yahoo Search API."
      }
    }
  ],
  "paths": {
    "/search.json": {
      "get": {
        "operationId": "YahooSearch_searchJson",
        "tags": [
          "Yahoo Search"
        ],
        "summary": "Search Yahoo as JSON",
        "description": "Creates a Yahoo search. A fresh search returns HTTP 202; poll `search_metadata.json_endpoint` until `search_metadata.status` is `Success` or `Error`. Once a search has finished, the same search within the hour returns its stored result with HTTP 200 unless `no_cache=true`; while the first is still Processing, the same request starts another search.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "QueryApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Engine"
          },
          {
            "$ref": "#/components/parameters/P"
          },
          {
            "$ref": "#/components/parameters/B"
          },
          {
            "$ref": "#/components/parameters/YahooDomain"
          },
          {
            "$ref": "#/components/parameters/Vc"
          },
          {
            "$ref": "#/components/parameters/Vl"
          },
          {
            "$ref": "#/components/parameters/Vm"
          },
          {
            "$ref": "#/components/parameters/Vs"
          },
          {
            "$ref": "#/components/parameters/Vf"
          },
          {
            "$ref": "#/components/parameters/Device"
          },
          {
            "$ref": "#/components/parameters/Output"
          },
          {
            "$ref": "#/components/parameters/NoCache"
          },
          {
            "$ref": "#/components/parameters/Async"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "The same search, finished within the last hour.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/YahooSearchResult"
                }
              }
            }
          },
          "202": {
            "description": "Search accepted and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SerpApiProcessingSearch"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/WorkspaceQueueFull"
          },
          "503": {
            "$ref": "#/components/responses/NoProxy"
          }
        }
      }
    },
    "/searches/{searchId}.json": {
      "get": {
        "operationId": "YahooSearch_retrieveJson",
        "tags": [
          "Yahoo Search"
        ],
        "summary": "Retrieve a Yahoo search",
        "description": "Polls or reads a Yahoo search. HTTP 202 while it is queued or running (`status: Processing`), HTTP 200 once it is `Success` or `Error`. Needs the `search.read` scope.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "QueryApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SearchId"
          },
          {
            "$ref": "#/components/parameters/ApiKeyQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "The finished search.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/YahooSearchResult"
                }
              }
            }
          },
          "202": {
            "description": "Still queued or running. Keep polling.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SerpApiProcessingSearch"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenRead"
          },
          "404": {
            "$ref": "#/components/responses/SearchNotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      },
      "QueryApiKeyAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key"
      }
    },
    "parameters": {
      "Engine": {
        "name": "engine",
        "in": "query",
        "required": true,
        "description": "Search engine: `yahoo` for this API.",
        "schema": {
          "type": "string",
          "enum": [
            "yahoo"
          ]
        }
      },
      "P": {
        "name": "p",
        "in": "query",
        "required": true,
        "description": "The query, as typed on Yahoo. Operators such as `site:` and quotes work. Yahoo's name for the query (not `q`).",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      "B": {
        "name": "b",
        "in": "query",
        "required": false,
        "description": "Position of the page's first result, from 1. A Yahoo page has 7 results: page 2 starts at `b=8`, page 3 at `b=15` (the `b` of `pagination.next`).",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "YahooDomain": {
        "name": "yahoo_domain",
        "in": "query",
        "required": false,
        "description": "`search.yahoo.com` or a country's Yahoo such as `fr.search.yahoo.com`.",
        "schema": {
          "type": "string",
          "default": "search.yahoo.com",
          "pattern": "^([a-z]{2}\\.)?search\\.yahoo\\.com$"
        }
      },
      "Vc": {
        "name": "vc",
        "in": "query",
        "required": false,
        "description": "Country of the results, 2 letters (`fr`). Sent to Yahoo as given.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z]{2}$"
        }
      },
      "Vl": {
        "name": "vl",
        "in": "query",
        "required": false,
        "description": "Language of the results, such as `lang_fr`. Sent to Yahoo as given.",
        "schema": {
          "type": "string"
        }
      },
      "Vm": {
        "name": "vm",
        "in": "query",
        "required": false,
        "description": "Adult filter: `r` (strict), `i` (moderate) or `p` (off).",
        "schema": {
          "type": "string",
          "enum": [
            "r",
            "i",
            "p"
          ]
        }
      },
      "Vs": {
        "name": "vs",
        "in": "query",
        "required": false,
        "description": "Only results from these domains or endings, comma-separated (`.fr,.com`).",
        "schema": {
          "type": "string",
          "maxLength": 200
        }
      },
      "Vf": {
        "name": "vf",
        "in": "query",
        "required": false,
        "description": "Only this file type, such as `pdf`.",
        "schema": {
          "type": "string",
          "maxLength": 200
        }
      },
      "Device": {
        "name": "device",
        "in": "query",
        "required": false,
        "description": "`desktop`, the only device for now.",
        "schema": {
          "type": "string",
          "enum": [
            "desktop"
          ],
          "default": "desktop"
        }
      },
      "Output": {
        "name": "output",
        "in": "query",
        "required": false,
        "description": "`json` or `html` (the page as Yahoo showed it).",
        "schema": {
          "type": "string",
          "enum": [
            "json",
            "html"
          ],
          "default": "json"
        }
      },
      "NoCache": {
        "name": "no_cache",
        "in": "query",
        "required": false,
        "description": "Set to `true` to run a new Yahoo search instead of returning the same finished search from the last hour.",
        "schema": {
          "type": "boolean",
          "default": false
        }
      },
      "Async": {
        "name": "async",
        "in": "query",
        "required": false,
        "description": "Accepted for SerpApi compatibility; a new search always answers 202 and is polled.",
        "schema": {
          "type": "boolean",
          "default": false
        }
      },
      "ApiKeyQuery": {
        "name": "api_key",
        "in": "query",
        "required": false,
        "description": "API key with `search.write` for search creation routes or `search.read` for archive routes. `X-API-KEY` may be used instead.",
        "schema": {
          "type": "string"
        }
      },
      "SearchId": {
        "name": "searchId",
        "in": "path",
        "required": true,
        "description": "Search archive id returned in `search_metadata.id`.",
        "schema": {
          "type": "string",
          "minLength": 8
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key does not include the required `search.write` scope.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            }
          }
        }
      },
      "ForbiddenRead": {
        "description": "The API key does not include the required `search.read` scope.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            }
          }
        }
      },
      "SearchNotFound": {
        "description": "Search archive id was not found for the current workspace.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            },
            "example": {
              "error": "Search not found."
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid search parameters (for example no `p`, a `b` below 1, a `device` other than desktop, a `yahoo_domain` that is not Yahoo's).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            },
            "example": {
              "error": "Missing required parameter: p",
              "error_code": "invalid_search_parameters"
            }
          }
        }
      },
      "WorkspaceQueueFull": {
        "description": "The workspace already has too many Yahoo searches queued or running.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            },
            "example": {
              "error": "Workspace Yahoo search queue is full. Please wait for existing searches to finish before adding more.",
              "error_code": "workspace_search_queue_full"
            }
          }
        }
      },
      "NoProxy": {
        "description": "Lempile has no IP that can run a Yahoo search right now. Retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SerpApiError"
            },
            "example": {
              "error": "Lempile has no IP that can run a Yahoo search right now. Retry later.",
              "error_code": "proxy_unavailable"
            }
          }
        }
      }
    },
    "schemas": {
      "SerpApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "SerpApi-compatible error message."
          },
          "error_code": {
            "type": "string",
            "description": "Machine-readable Lempile error code when available."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": true
      },
      "SerpApiProcessingSearch": {
        "type": "object",
        "description": "Processing payload returned while a search is queued or running.",
        "properties": {
          "search_metadata": {
            "$ref": "#/components/schemas/SerpApiSearchMetadata"
          },
          "search_parameters": {
            "$ref": "#/components/schemas/SerpApiSearchParameters"
          }
        },
        "required": [
          "search_metadata"
        ],
        "additionalProperties": true
      },
      "YahooSearchMetadata": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "Processing",
              "Success",
              "Error"
            ]
          },
          "status_detail": {
            "type": "string",
            "description": "On a failed search: why (`yahoo_blocked`, `yahoo_consent_wall`, `yahoo_search_failed`, `search_queue_timeout`)."
          },
          "json_endpoint": {
            "type": "string",
            "format": "uri"
          },
          "raw_html_file": {
            "type": "string",
            "format": "uri"
          },
          "yahoo_url": {
            "type": "string",
            "format": "uri",
            "description": "The Yahoo address the search opened."
          },
          "created_at": {
            "type": "string"
          },
          "processed_at": {
            "type": "string"
          },
          "total_time_taken": {
            "type": "number"
          }
        }
      },
      "YahooOrganicResult": {
        "type": "object",
        "required": [
          "position",
          "title",
          "link"
        ],
        "properties": {
          "position": {
            "type": "integer",
            "description": "1-based position on this page."
          },
          "title": {
            "type": "string"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "The result's own address, read from Yahoo's page."
          },
          "redirect_link": {
            "type": "string",
            "format": "uri",
            "description": "Yahoo's click link for the same result, when Yahoo's page wraps it (most results have none)."
          },
          "displayed_link": {
            "type": "string",
            "description": "The address as Yahoo shows it, parts separated by ›. Read `link` for the address."
          },
          "source": {
            "type": "string",
            "description": "The site's name as Yahoo shows it."
          },
          "snippet": {
            "type": "string"
          }
        }
      },
      "YahooPagination": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer"
          },
          "next": {
            "type": "string",
            "format": "uri"
          },
          "next_link": {
            "type": "string",
            "format": "uri"
          },
          "previous": {
            "type": "string",
            "format": "uri"
          },
          "previous_link": {
            "type": "string",
            "format": "uri"
          },
          "other_pages": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "YahooSearchResult": {
        "type": "object",
        "required": [
          "search_metadata",
          "search_parameters"
        ],
        "properties": {
          "search_metadata": {
            "$ref": "#/components/schemas/YahooSearchMetadata"
          },
          "search_parameters": {
            "type": "object",
            "additionalProperties": true,
            "description": "engine, p, yahoo_domain, device and the parameters given."
          },
          "search_information": {
            "type": "object",
            "properties": {
              "query_displayed": {
                "type": "string"
              },
              "organic_results_state": {
                "type": "string"
              }
            }
          },
          "organic_results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/YahooOrganicResult"
            }
          },
          "pagination": {
            "type": "object",
            "description": "The pages Yahoo offers, with Yahoo's own addresses: current, next, previous, other_pages. For the next page, send the same search with the b of next.",
            "additionalProperties": true
          },
          "serpapi_pagination": {
            "$ref": "#/components/schemas/YahooPagination",
            "description": "Lempile's own links for the pages, on the first answer to a search (202) or a stored result returned at once (200)."
          },
          "error": {
            "type": "string",
            "description": "On a failed search: what happened."
          }
        }
      },
      "SerpApiSearchParameters": {
        "type": "object",
        "description": "The search's stored parameters: engine, p, yahoo_domain, device and the parameters given.",
        "required": [
          "engine",
          "p",
          "yahoo_domain",
          "device"
        ],
        "additionalProperties": true
      },
      "SerpApiSearchMetadata": {
        "type": "object",
        "description": "SerpApi-compatible lifecycle metadata. Internal `Queued` and `Running` states are exposed as public `Processing` plus detail fields.",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "Processing",
              "Success",
              "Error"
            ]
          },
          "status_detail": {
            "type": "string",
            "description": "Internal state such as `Queued`, `Running`, or a final status detail."
          },
          "runner_status_detail": {
            "type": "string",
            "description": "Runner detail such as `queued`, `runner_claimed`, `lease_renewed`, `completed`, `search_queue_timeout`, or `runner_lease_expired`."
          },
          "json_endpoint": {
            "type": "string",
            "format": "uri"
          },
          "pixel_position_endpoint": {
            "type": "string",
            "format": "uri"
          },
          "raw_html_file": {
            "type": "string",
            "format": "uri"
          },
          "created_at": {
            "type": "string"
          },
          "queued_at": {
            "type": "string"
          },
          "started_at": {
            "type": "string"
          },
          "lease_expires_at": {
            "type": "string"
          },
          "processed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "total_time_taken": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "status"
        ],
        "additionalProperties": true
      }
    }
  }
}
