{ "openapi": "3.1.0", "info": { "title": "Scrappa API Documentation", "version": "1.0.0", "description": "Scrappa API - Web scraping API for Google Maps, Search, Images, Jobs, YouTube, Kununu, Trustpilot and more." }, "servers": [ { "url": "https://scrappa.co/api" } ], "tags": [ { "name": "Baidu API" }, { "name": "Pinterest API" }, { "name": "Startpage Search" }, { "name": "Bing Search" }, { "name": "TikTok API" }, { "name": "Google Patents API" }, { "name": "Google Scholar API" }, { "name": "Google Maps", "description": "Google Maps API endpoints for places, businesses, reviews, and directions" }, { "name": "Google Search", "description": "Google Search API endpoints" }, { "name": "Google Images", "description": "Google Images search API" }, { "name": "Google Jobs", "description": "Google Jobs search API" }, { "name": "Google News", "description": "Google News search API" }, { "name": "Google Hotels", "description": "Search and compare hotel prices from Google Hotels" }, { "name": "Google Lens", "description": "Google Lens visual search API" }, { "name": "Google Trends", "description": "Google Trends API endpoints for search interest, related queries, and autocomplete" }, { "name": "YouTube", "description": "YouTube video search and metadata API" }, { "name": "ImmobilienScout24", "description": "ImmobilienScout24 real estate API" }, { "name": "Idealista API", "description": "Idealista real estate API" }, { "name": "Rentalia API", "description": "Rentalia holiday rental API" } ], "security": [ { "apiKey": [] } ], "paths": { "/baidu/search": { "get": { "operationId": "baidu.search", "tags": [ "Baidu API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "": {}, "page": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "limit": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 10 ] } ] } }, "required": [ "engine", null, "page", "limit" ] }, "": {}, "provider_response": {}, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", null, "provider_response", "response_time_ms" ] } } } }, "503": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "value": { "message": "Error" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/baidu/autocomplete": { "get": { "operationId": "baidu.autocomplete", "tags": [ "Baidu API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Partial search query.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "": {} }, "required": [ "engine", null ] }, "": {}, "provider_response": {}, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", null, "provider_response", "response_time_ms" ] } } } }, "503": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "value": { "message": "Error" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/baidu/trending": { "get": { "operationId": "baidu.trending", "tags": [ "Baidu API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "tab": {} }, "required": [ "engine", "tab" ] }, "": {}, "provider_response": {}, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", null, "provider_response", "response_time_ms" ] } } } }, "503": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "value": { "message": "Error" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/baidu/images": { "get": { "operationId": "baidu.images", "tags": [ "Baidu API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "": {}, "page": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "limit": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 10 ] } ] } }, "required": [ "engine", null, "page", "limit" ] }, "": {}, "provider_response": {}, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", null, "provider_response", "response_time_ms" ] } } } }, "503": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "value": { "message": "Error" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/baidu/developer-search": { "get": { "operationId": "baidu.developer-search", "tags": [ "Baidu API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "": {}, "page": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "limit": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 10 ] } ] } }, "required": [ "engine", null, "page", "limit" ] }, "": {}, "provider_response": {}, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", null, "provider_response", "response_time_ms" ] } } } }, "503": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "value": { "message": "Error" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/baidu/translation-suggestions": { "get": { "operationId": "baidu.translation-suggestions", "tags": [ "Baidu API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Word or phrase to look up.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "": {} }, "required": [ "engine", null ] }, "": {}, "provider_response": {}, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", null, "provider_response", "response_time_ms" ] } } } }, "503": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Baidu could not be reached after safe retries. The request is not billed.", "value": { "message": "Error" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/bing/search": { "get": { "operationId": "bing.search", "tags": [ "Bing Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query (max 500 characters).", "schema": { "type": "string", "maxLength": 500 } }, { "name": "page", "in": "query", "description": "Page number (1-50).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "num", "in": "query", "description": "Results per page (1-50).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "site", "in": "query", "description": "Restrict results to this domain, e.g. example.com.", "schema": { "type": [ "string", "null" ], "maxLength": 253 } }, { "name": "filetype", "in": "query", "description": "Restrict results to this file extension, e.g. pdf.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z0-9]+$", "maxLength": 20 } }, { "name": "safe", "in": "query", "description": "SafeSearch level: off, moderate or strict.", "schema": { "type": [ "string", "null" ], "enum": [ "off", "moderate", "strict" ] } }, { "name": "hl", "in": "query", "description": "Language code, e.g. en or en-GB.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z]{2})?$", "maxLength": 20 } }, { "name": "include_html", "in": "query", "description": "Set to true to include the raw HTML in the response. Default: false.", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "domain": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "integer" }, { "type": "object" }, { "type": "string" } ] } }, "required": [ "position", "title", "description", "url", "domain" ] } }, "people_also_search_for": { "type": "array", "items": {} }, "people_also_ask": { "type": "array", "items": {} }, "knowledge_graph": { "type": "null" }, "see_results_about": { "type": "null" }, "twitter_card": { "type": "null" }, "results_on_page": { "type": "integer" }, "source": { "type": "string", "const": "bing" }, "html": { "type": "string", "description": "Log::debug(\"Successful request to {$url} via proxy {$proxy}. Status: \" . $response->status());" } }, "required": [ "data", "people_also_search_for", "people_also_ask", "knowledge_graph", "see_results_about", "twitter_card", "results_on_page", "source", "html" ] } } } }, "422": { "description": "The query is missing, or a pagination, locale, safe-search, site, filetype, or include_html parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "description": "The query is missing, or a pagination, locale, safe-search, site, filetype, or include_html parameter failed validation.", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "The approved mobile-proxy pool was unavailable, Bing returned a blocking HTTP response, the transport failed, or the returned HTML did not contain valid Bing result markers after the bounded proxy rotation. The request is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "bing_upstream_unavailable": { "description": "The approved mobile-proxy pool was unavailable, Bing returned a blocking HTTP response, the transport failed, or the returned HTML did not contain valid Bing result markers after the bounded proxy rotation. The request is not billed.", "value": { "error": "Bing upstream is temporarily unavailable. Please retry shortly.", "service": "BingSearchService", "retryable": true, "error_code": "bing_upstream_unavailable", "failed_stage": "upstream_http" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-patents/search": { "get": { "operationId": "google-patents.search", "description": "Search for patents on Google Patents using keywords, filters, and date ranges.\nSupports Boolean operators, country filtering, patent status, and sorting by date.", "summary": "Search Patents", "tags": [ "Google Patents API" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Required", "schema": { "type": "string", "maxLength": 500 } }, { "name": "page", "in": "query", "description": "Pagination", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "num", "in": "query", "description": "Number of results per page. Range: 1-100. Default: 10", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "sort", "in": "query", "description": "Sorting", "schema": { "type": [ "string", "null" ], "enum": [ "new", "old" ] } }, { "name": "before", "in": "query", "description": "Upper date bound as type:YYYYMMDD, where type is filing, publication or priority (e.g. filing:20231231).", "schema": { "type": [ "string", "null" ], "pattern": "^(filing|publication|priority):\\d{8}$" } }, { "name": "after", "in": "query", "description": "Filter patents after this date. Format: filing:YYYYMMDD or publication:YYYYMMDD. Example: `publication:20230101`", "schema": { "type": [ "string", "null" ], "pattern": "^(filing|publication|priority):\\d{8}$" } }, { "name": "country", "in": "query", "description": "Filters", "schema": { "type": [ "string", "null" ] } }, { "name": "language", "in": "query", "description": "Language filter. Example: `ENGLISH`, `GERMAN`", "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "description": "Patent status filter. Values: `GRANT`, `APPLICATION`", "schema": { "type": [ "string", "null" ], "enum": [ "GRANT", "APPLICATION" ] } }, { "name": "type", "in": "query", "description": "Patent type filter. Values: `PATENT`, `DESIGN`", "schema": { "type": [ "string", "null" ], "enum": [ "PATENT", "DESIGN" ] } }, { "name": "inventor", "in": "query", "description": "Inventor name filter. Example: `John Smith,Jane Doe`", "schema": { "type": [ "string", "null" ] } }, { "name": "assignee", "in": "query", "description": "Assignee/company name filter. Example: `Tesla Inc,Apple Inc`", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "total_results": { "type": "integer" }, "total_pages": { "type": "integer" }, "current_page": { "type": "integer" }, "patents": { "type": "array", "items": { "type": "object", "properties": { "patent_id": { "type": "string" }, "rank": { "type": "integer" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "publication_number": { "type": "string" }, "language": { "type": "string" }, "dates": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "inventor": { "type": "string" }, "assignee": { "type": "string" }, "thumbnail": { "type": [ "string", "null" ] }, "pdf": { "type": [ "string", "null" ] }, "family_status": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } }, "required": [ "patent_id", "rank", "title", "snippet", "publication_number", "language", "dates", "inventor", "assignee", "thumbnail", "pdf", "family_status" ] } } }, "required": [ "total_results", "total_pages", "current_page", "patents" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more parameters failed validation", "value": { "errors": { "q": [ "The search query is required." ], "page": [ "The page must be a non-negative integer." ], "sort": [ "The sort must be one of: new, old." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Service temporarily unavailable or failed to fetch data from Google Patents", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to fetch data from Google Patents", "value": { "error": "Failed to fetch data from Google Patents", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/google-patents/details": { "get": { "operationId": "google-patents.details", "description": "Retrieve comprehensive details about a specific patent including full metadata,\ncitations (forward and backward), patent family information, and description.", "summary": "Patent Details", "tags": [ "Google Patents API" ], "parameters": [ { "name": "patent_id", "in": "query", "required": true, "description": "Required", "schema": { "type": "string", "pattern": "^(patent\\/)?[A-Z]{2}\\d+[A-Z]?\\d*(\\/[a-z]{2})?$", "minLength": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "patent_id": { "type": "string" }, "publication_number": { "type": "string" }, "title": { "type": "string" }, "abstract": { "type": "string" }, "inventors": { "type": "array", "items": { "type": "string" } }, "assignees": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "dates": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "application_number": { "type": [ "string", "null" ] }, "prior_art_keywords": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "citations": { "type": "object", "additionalProperties": { "type": "array", "items": {} } } }, "required": [ "patent_id", "publication_number", "title", "abstract", "inventors", "assignees", "dates", "country", "language", "application_number", "prior_art_keywords", "links", "citations" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Invalid patent ID format", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Invalid patent ID format", "value": { "errors": { "patent_id": [ "The patent ID is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Patent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Patent not found", "value": { "error": "Patent not found", "message": "The requested patent ID was not found in Google Patents." } } } } } }, "500": { "description": "Service temporarily unavailable or failed to fetch patent details", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to fetch patent details", "value": { "error": "Failed to fetch patent details", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/google/scholar": { "get": { "operationId": "google-scholar.search", "description": "Search scholarly publications or follow a cited-by/version relationship.", "summary": "Search Google Scholar", "tags": [ "Google Scholar API" ], "parameters": [ { "name": "q", "in": "query", "description": "Scholar search query. Optional when cites or cluster is supplied.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "hl", "in": "query", "description": "Two-letter interface language, optionally with a region. Defaults to en.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(?:-[a-z]{2})?$" } }, { "name": "start", "in": "query", "description": "Zero-based result offset from 0 to 990. Defaults to 0.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 990 } }, { "name": "num", "in": "query", "description": "Results per request from 1 to 20. Defaults to 10.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "as_ylo", "in": "query", "description": "Earliest publication year to include.", "schema": { "type": [ "integer", "null" ], "minimum": 1000, "maximum": 2100 } }, { "name": "as_yhi", "in": "query", "description": "Latest publication year to include.", "schema": { "type": [ "integer", "null" ], "minimum": 1000, "maximum": 2100 } }, { "name": "scisbd", "in": "query", "description": "0 for relevance, 1 for recent abstracts, or 2 for all recent additions.", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1", "2" ] } }, { "name": "cites", "in": "query", "description": "Numeric publication ID for a cited-by search. May be combined with q.", "schema": { "type": [ "string", "null" ], "pattern": "^\\d{1,30}$" } }, { "name": "cluster", "in": "query", "description": "Numeric publication ID for an all-versions search. Must be used alone.", "schema": { "type": [ "string", "null" ], "pattern": "^\\d{1,30}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" } }, "required": [ "duration_ms" ] } }, "required": [ "success", "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/pinterest/search": { "get": { "operationId": "pinterest.search", "description": "This endpoint allows you to search for pins on Pinterest using a keyword query.\nReturns a list of pins with their titles, descriptions, images, and pinner information.\nSupports pagination using the bookmark parameter for retrieving large result sets.", "summary": "Search Pinterest for pins by keyword", "tags": [ "Pinterest API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query for Pinterest pins", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "description": "Number of results to request from Pinterest (max 250). Default: 250. Note: Pinterest may return a different number of results than requested.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 250 } }, { "name": "bookmark", "in": "query", "description": "Pagination token from a previous response.", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "results_count": { "type": "integer" }, "nextBookmark": { "type": [ "string", "null" ] }, "pins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "images": { "type": "object", "properties": { "orig": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [ "url", "width", "height" ] }, "736x": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [ "url", "width", "height" ] }, "474x": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [ "url", "width", "height" ] }, "236x": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [ "url", "width", "height" ] }, "170x": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [ "url", "width", "height" ] } }, "required": [ "orig", "736x", "474x", "236x", "170x" ] }, "link": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "pinner": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "profile_url": { "type": [ "string", "null" ] }, "follower_count": { "type": [ "integer", "null" ] } }, "required": [ "id", "username", "full_name", "profile_url", "follower_count" ] }, "board": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url" ] }, "created_at": { "type": [ "string", "null" ] }, "dominant_color": { "type": [ "string", "null" ] }, "is_video": { "type": "boolean" }, "video_url": { "type": [ "string", "null" ] }, "video_duration": { "type": [ "number", "null" ] }, "saves": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "description", "image_url", "images", "link", "domain", "pinner", "board", "created_at", "dominant_color", "is_video", "video_url", "video_duration", "saves", "likes", "comments", "hashtags" ] } } }, "required": [ "query", "count", "results_count", "nextBookmark", "pins" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/startpage/search": { "get": { "operationId": "startpage.search", "description": "Search the web using Startpage, a privacy-focused search engine that provides anonymous search results without tracking users.", "summary": "Search using Startpage", "tags": [ "Startpage Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The search query string. Example: `privacy tips`", "schema": { "type": "string", "maxLength": 500 } }, { "name": "language", "in": "query", "description": "Language filter for search results. Values: `english`, `deutsch`, `french`, `spanish`, `italian`, `portuguese`, `dutch`, `russian`, `chinese`, `japanese`, `arabic`, `all`. Default: `english`", "schema": { "type": [ "string", "null" ], "enum": [ "english", "deutsch", "french", "spanish", "italian", "portuguese", "dutch", "russian", "chinese", "japanese", "arabic", "all" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination. Range: 0-10. Default: 0", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10 } }, { "name": "safe_search", "in": "query", "description": "Safe search filter to exclude adult content. Values: `true`, `false`. Default: `false`", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "service": { "type": "string", "const": "StartpageSearchService" }, "exception_class": { "type": "string" }, "trace": { "type": "string" } }, "required": [ "error", "service", "exception_class", "trace" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": {}, "people_also_search_for": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "people_also_ask": { "type": "array", "description": "Startpage doesn't typically have this", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "knowledge_graph": { "type": "null", "description": "Startpage doesn't typically have this" }, "see_results_about": { "type": "null", "description": "Startpage doesn't have knowledge graph" }, "twitter_card": { "type": "null", "description": "Startpage doesn't have this" }, "total_results": { "type": "integer", "description": "Startpage doesn't have this" }, "source": { "type": "string", "const": "startpage" }, "html": { "type": "string" } }, "required": [ "data", "people_also_search_for", "people_also_ask", "knowledge_graph", "see_results_about", "twitter_card", "total_results", "source", "html" ] }, { "type": "object", "properties": { "html": {} }, "required": [ "html" ] } ] } } } }, "422": { "description": "Validation failed for one or more Startpage Search request parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "startpage_validation_failed": { "summary": "The request parameters were invalid.", "description": "Validation failed for one or more Startpage Search request parameters.", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "The query field is required." } } } } } }, "503": { "description": "The upstream request path was temporarily unavailable or exhausted before Scrappa received a parseable Startpage response. Scrappa received an upstream Startpage response, but the parser could not find known result markers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "startpage_fetch": { "summary": "Startpage Search could not be fetched right now.", "description": "The upstream request path was temporarily unavailable or exhausted before Scrappa received a parseable Startpage response.", "value": { "error": "Startpage upstream is temporarily unavailable. Please retry shortly.", "service": "StartpageSearchService", "retryable": true, "error_code": "startpage_upstream_unavailable", "failed_stage": "startpage_fetch" } }, "parser_no_result_markers": { "summary": "Startpage Search returned a page without result markers.", "description": "Scrappa received an upstream Startpage response, but the parser could not find known result markers.", "value": { "error": "Startpage upstream is temporarily unavailable. Please retry shortly.", "service": "StartpageSearchService", "retryable": true, "error_code": "startpage_upstream_unavailable", "failed_stage": "parser_no_result_markers" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/video": { "get": { "operationId": "tiktok.video", "description": "Resolve a TikTok video, photo post, short URL, or raw video ID into metadata and playback URLs.", "summary": "Get TikTok Video", "tags": [ "TikTok API" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "TikTok video URL, short URL, photo URL, or raw video ID.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "hd", "in": "query", "description": "Request the HD playback URL when available. Accepts true/false or 1/0.", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "id": { "type": "string" }, "region": { "type": "string" }, "title": { "type": "string" }, "content_desc": { "type": "array", "items": {} }, "cover": { "type": "string" }, "ai_dynamic_cover": { "type": "string" }, "origin_cover": { "type": "string" }, "duration": { "type": "integer" }, "play": { "type": "string" }, "wmplay": { "type": "string" }, "hdplay": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "wm_size": { "type": "integer" }, "hd_size": { "type": [ "integer", "null" ] }, "music": { "type": "string" }, "music_info": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "play": { "type": "string" }, "cover": { "type": "string" }, "author": { "type": "string" }, "original": { "type": "boolean" }, "duration": { "type": "integer" }, "album": { "type": "string" } }, "required": [ "id", "title", "play", "cover", "author", "original", "duration", "album" ] }, "play_count": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "download_count": { "type": "integer" }, "collect_count": { "type": "integer" }, "create_time": { "type": "integer" }, "anchors": {}, "anchors_extras": { "type": "string" }, "is_ad": { "type": "boolean" }, "commerce_info": { "type": [ "object", "null" ], "additionalProperties": {} }, "commercial_video_info": { "type": "string" }, "item_comment_settings": { "type": "integer" }, "mentioned_users": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "id", "unique_id", "nickname", "avatar" ] } }, "required": [ "aweme_id", "id", "region", "title", "content_desc", "cover", "ai_dynamic_cover", "origin_cover", "duration", "play", "wmplay", "hdplay", "size", "wm_size", "hd_size", "music", "music_info", "play_count", "digg_count", "comment_count", "share_count", "download_count", "collect_count", "create_time", "anchors", "anchors_extras", "is_ad", "commerce_info", "commercial_video_info", "item_comment_settings", "mentioned_users", "author" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/search": { "get": { "operationId": "tiktok.user.search", "description": "Search public TikTok users by keywords.", "summary": "Search TikTok users", "tags": [ "TikTok API" ], "parameters": [ { "name": "keywords", "in": "query", "required": true, "description": "Search text for public TikTok users. Use a username fragment, brand name, creator niche, product category, or campaign keyword.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "count", "in": "query", "description": "Number of user matches to return for the page, up to 50.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from the previous response. Pass this value with the same `keywords` query when `hasMore` is true.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" }, "follower_count": { "type": "integer" }, "verified": { "type": "boolean" } }, "required": [ "user_id", "unique_id", "nickname", "avatar", "follower_count", "verified" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "users", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/posts": { "get": { "operationId": "tiktok.user.posts", "description": "Fetch public TikTok posts for a user by unique ID or user ID.", "summary": "Get posts by user", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of posts to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 35 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for fetching the next page of results.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "play_count": { "type": "integer" } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "play_count" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/similar": { "get": { "operationId": "tiktok.user.similar", "description": "The upstream provider deprecated this endpoint without an equivalent replacement.", "summary": "Get similar users", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of users to return (1-50).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "integer", "const": 503 } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/followers": { "get": { "operationId": "tiktok.user.followers", "description": "Fetch the accounts that follow a TikTok user.\nNote: This endpoint uses 'time' (int) for pagination instead of 'cursor' (string)\nas the upstream API uses a time-based pagination mechanism.", "summary": "Get user followers list", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of results to return (1-50).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "time", "in": "query", "description": "Followers pagination token/time marker.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "followers": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" }, "follower_count": { "type": "integer" }, "verified": { "type": "boolean" } }, "required": [ "user_id", "unique_id", "nickname", "avatar", "follower_count", "verified" ] } }, "hasMore": { "type": "boolean" }, "time": { "type": "integer" } }, "required": [ "followers", "hasMore", "time" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/favorites": { "get": { "operationId": "tiktok.user.favorites", "description": "Fetch public favorite videos for a TikTok user when available upstream.", "summary": "Get user favorite videos", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "time", "in": "query", "description": "Optional favorites time marker when provided by the upstream.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "count", "in": "query", "description": "Number of favorites to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for the favorites list.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "play_count": { "type": "integer" } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "play_count" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/following": { "get": { "operationId": "tiktok.user.following", "description": "Fetch the accounts a TikTok user follows.\nNote: This endpoint uses 'time' (int) for pagination instead of 'cursor' (string)\nas the upstream API uses a time-based pagination mechanism.", "summary": "Get user following list", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of results to return (1-50).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "time", "in": "query", "description": "Following pagination token/time marker.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "following": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" }, "follower_count": { "type": "integer" }, "verified": { "type": "boolean" } }, "required": [ "user_id", "unique_id", "nickname", "avatar", "follower_count", "verified" ] } }, "hasMore": { "type": "boolean" }, "time": { "type": "integer" } }, "required": [ "following", "hasMore", "time" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/profile": { "get": { "operationId": "tiktok.user.profile", "description": "Fetch public TikTok profile data by unique ID or user ID.", "summary": "Get user profile", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" }, "avatar_larger": { "type": "string" }, "signature": { "type": "string" }, "verified": { "type": "boolean" }, "follower_count": { "type": "integer" }, "following_count": { "type": "integer" }, "heart_count": { "type": "integer" }, "video_count": { "type": "integer" }, "digg_count": { "type": "integer" }, "private_account": { "type": "boolean" }, "region": { "type": "string" }, "language": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar", "avatar_larger", "signature", "verified", "follower_count", "following_count", "heart_count", "video_count", "digg_count", "private_account", "region", "language" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/user/story": { "get": { "operationId": "tiktok.user.story", "description": "Fetch TikTok story data for a user by unique ID or user ID.", "summary": "Get user story", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "stories": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time" ] } } }, "required": [ "stories" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/music/posts": { "get": { "operationId": "tiktok.music.posts", "description": "Fetch TikTok posts that use a specific music track.", "summary": "Get videos for a music track", "tags": [ "TikTok API" ], "parameters": [ { "name": "music_id", "in": "query", "required": true, "description": "TikTok music identifier.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of videos to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 35 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/music/details": { "get": { "operationId": "tiktok.music.details", "description": "Fetch TikTok music metadata by music URL or ID.", "summary": "Get music details", "tags": [ "TikTok API" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "TikTok music URL or music ID.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "music_id": { "type": "string" }, "title": { "type": "string" }, "play": { "type": "string" }, "cover": { "type": "string" }, "author": { "type": "string" }, "duration": { "type": "integer" }, "original": { "type": "boolean" }, "album": { "type": "string" } }, "required": [ "music_id", "title", "play", "cover", "author", "duration", "original", "album" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/feed/search": { "get": { "operationId": "tiktok.feed.search", "description": "Search TikTok feed videos by keywords with optional region and sorting filters.", "summary": "Search videos by keyword", "tags": [ "TikTok API" ], "parameters": [ { "name": "keywords", "in": "query", "required": true, "description": "Feed search keywords.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "count", "in": "query", "description": "Number of results to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor for continuing a previous feed search.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "region", "in": "query", "description": "Optional region code such as US or JP.", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "publish_time", "in": "query", "description": "Optional publish-time filter supported by the upstream.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "sort_type", "in": "query", "description": "Optional upstream sort type value for feed search ordering.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "author" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/feed/list": { "get": { "operationId": "tiktok.feed.list", "description": "Fetch TikTok feed videos for a specific supported region.", "summary": "Get feed videos by region", "tags": [ "TikTok API" ], "parameters": [ { "name": "region", "in": "query", "required": true, "description": "Region code such as US or JP.", "schema": { "type": "string", "maxLength": 10 } }, { "name": "count", "in": "query", "description": "Number of videos to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "author" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/regions": { "get": { "operationId": "tiktok.regions", "description": "List the region codes available for feed-based TikTok endpoints.", "summary": "Get supported regions", "tags": [ "TikTok API" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/comments/list": { "get": { "operationId": "tiktok.comments.list", "description": "Fetch comments for a TikTok video URL.", "summary": "Get comments for a video", "tags": [ "TikTok API" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "TikTok video URL.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "count", "in": "query", "description": "Number of comments to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "comment_id": { "type": "string" }, "text": { "type": "string" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "reply_count": { "type": "integer" }, "user": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "comment_id", "text", "create_time", "digg_count", "reply_count", "user" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "comments", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/comments/replies": { "get": { "operationId": "tiktok.comments.replies", "description": "Fetch replies for a TikTok comment.", "summary": "Get replies for a comment", "tags": [ "TikTok API" ], "parameters": [ { "name": "comment_id", "in": "query", "required": true, "description": "TikTok comment identifier.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "video_id", "in": "query", "description": "Optional TikTok video identifier.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of replies to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "replies": { "type": "array", "items": { "type": "object", "properties": { "comment_id": { "type": "string" }, "text": { "type": "string" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "reply_count": { "type": "integer" }, "user": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "comment_id", "text", "create_time", "digg_count", "reply_count", "user" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "replies", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/challenges/posts": { "get": { "operationId": "tiktok.challenges.posts", "description": "Fetch TikTok posts for a challenge by challenge ID or challenge name.", "summary": "Get videos for a challenge", "tags": [ "TikTok API" ], "parameters": [ { "name": "challenge_id", "in": "query", "description": "TikTok challenge identifier.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "challenge_name", "in": "query", "description": "Challenge slug or name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "region", "in": "query", "description": "Optional region code.", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "count", "in": "query", "description": "Number of posts to return (1-50).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "author" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/challenges/search": { "get": { "operationId": "tiktok.challenges.search", "description": "Search TikTok challenges by keyword.", "summary": "Search challenges", "tags": [ "TikTok API" ], "parameters": [ { "name": "keywords", "in": "query", "required": true, "description": "Challenge search keywords.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "count", "in": "query", "description": "Number of results to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "challenges": { "type": "array", "items": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "challenge_name": { "type": "string" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "view_count": { "type": "integer" } }, "required": [ "challenge_id", "challenge_name", "description", "video_count", "view_count" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "challenges", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/challenges/details": { "get": { "operationId": "tiktok.challenges.details", "description": "Fetch challenge metadata by challenge ID or challenge name.", "summary": "Get challenge details", "tags": [ "TikTok API" ], "parameters": [ { "name": "challenge_id", "in": "query", "description": "TikTok challenge identifier.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "challenge_name", "in": "query", "description": "Challenge slug or name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "challenge_name": { "type": "string" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "view_count": { "type": "integer" }, "cover": { "type": [ "string", "null" ] } }, "required": [ "challenge_id", "challenge_name", "description", "video_count", "view_count", "cover" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/playlists/posts": { "get": { "operationId": "tiktok.playlists.posts", "description": "Fetch TikTok posts from a playlist or mix.", "summary": "Get playlist videos", "tags": [ "TikTok API" ], "parameters": [ { "name": "mix_id", "in": "query", "required": true, "description": "TikTok mix or playlist identifier.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of videos to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "author" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/playlists/details": { "get": { "operationId": "tiktok.playlists.details", "description": "Fetch TikTok playlist or mix metadata.", "summary": "Get playlist details", "tags": [ "TikTok API" ], "parameters": [ { "name": "mix_id", "in": "query", "required": true, "description": "TikTok mix or playlist identifier.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "mix_id": { "type": "string" }, "mix_name": { "type": "string" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "cover": { "type": "string" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "mix_id", "mix_name", "description", "video_count", "cover", "author" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/playlists/list": { "get": { "operationId": "tiktok.playlists.list", "description": "Fetch TikTok playlists created by a user.", "summary": "Get playlists by user", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of playlists to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "mixes": { "type": "array", "items": { "type": "object", "properties": { "mix_id": { "type": "string" }, "mix_name": { "type": "string" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "cover": { "type": "string" } }, "required": [ "mix_id", "mix_name", "description", "video_count", "cover" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "mixes", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/collections/posts": { "get": { "operationId": "tiktok.collections.posts", "description": "Fetch TikTok posts from a collection.", "summary": "Get collection videos", "tags": [ "TikTok API" ], "parameters": [ { "name": "collection_id", "in": "query", "required": true, "description": "TikTok collection identifier.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of videos to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "aweme_id": { "type": "string" }, "title": { "type": "string" }, "cover": { "type": "string" }, "play": { "type": "string" }, "duration": { "type": "integer" }, "create_time": { "type": "integer" }, "digg_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "aweme_id", "title", "cover", "play", "duration", "create_time", "digg_count", "comment_count", "share_count", "author" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "videos", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/collections/details": { "get": { "operationId": "tiktok.collections.details", "description": "Fetch TikTok collection metadata.", "summary": "Get collection details", "tags": [ "TikTok API" ], "parameters": [ { "name": "collection_id", "in": "query", "required": true, "description": "TikTok collection identifier.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "collection_id": { "type": "string" }, "collection_name": { "type": "string" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "cover": { "type": "string" }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "unique_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "user_id", "unique_id", "nickname", "avatar" ] } }, "required": [ "collection_id", "collection_name", "description", "video_count", "cover", "author" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/collections/list": { "get": { "operationId": "tiktok.collections.list", "description": "Fetch TikTok collections created by a user.", "summary": "Get collections by user", "tags": [ "TikTok API" ], "parameters": [ { "name": "unique_id", "in": "query", "description": "TikTok username, with or without @.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "description": "Numeric TikTok user ID.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "description": "Number of collections to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response. Omit for the first page.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "properties": { "collection_id": { "type": "string" }, "collection_name": { "type": "string" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "cover": { "type": "string" } }, "required": [ "collection_id", "collection_name", "description", "video_count", "cover" ] } }, "hasMore": { "type": "boolean" }, "cursor": { "type": [ "string", "null" ] } }, "required": [ "collections", "hasMore", "cursor" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/tiktok/ads/details": { "get": { "operationId": "tiktok.ads.details", "description": "Resolve a TikTok Creative Center ad URL into ad metadata.", "summary": "Get ad details", "tags": [ "TikTok API" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "TikTok Creative Center ad URL.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "processed_time": { "type": "number" }, "data": { "type": "object", "properties": { "ad_id": { "type": "string" }, "brand_name": { "type": "string" }, "industry": { "type": "string" }, "objective": { "type": "string" }, "video_url": { "type": "string" }, "cover": { "type": "string" }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "cta": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "ad_id", "brand_name", "industry", "objective", "video_url", "cover", "like_count", "comment_count", "share_count", "cta", "destination" ] } }, "required": [ "code", "msg", "processed_time", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/details": { "get": { "operationId": "apple.app-store.details", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple product id (numeric adam id; UMC ids also accepted for movies/TV)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/product": { "get": { "operationId": "apple.app-store.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple product id (numeric adam id; UMC ids also accepted for movies/TV)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/apps/product": { "get": { "operationId": "apple.app-store.apps.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple app id (numeric adam id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/books/product": { "get": { "operationId": "apple.app-store.books.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple book id (numeric adam id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/audiobooks/product": { "get": { "operationId": "apple.app-store.audiobooks.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple audiobook id (numeric adam id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/movies/product": { "get": { "operationId": "apple.app-store.movies.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple movie id (numeric adam id or UMC id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/tv/product": { "get": { "operationId": "apple.app-store.tv.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple TV show id (numeric adam id or UMC id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/music/product": { "get": { "operationId": "apple.app-store.music.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple Music album id (numeric adam id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/podcasts/product": { "get": { "operationId": "apple.app-store.podcasts.product", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple Podcasts show id (numeric adam id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Apple store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/product/reviews": { "get": { "operationId": "apple.app-store.product.reviews", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Apple product id (numeric adam id)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "store", "in": "query", "description": "Store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "season_id", "in": "query", "description": "TV season id; returns the season product instead of the show.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "num", "in": "query", "description": "Requested review result count per page", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "description": "Review offset", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token from a previous response", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/search": { "get": { "operationId": "apple.app-store.search", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search term (q is accepted as an alias)", "schema": { "type": "string", "maxLength": 500 } }, { "name": "store", "in": "query", "description": "Store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/charts": { "get": { "operationId": "apple.app-store.charts", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "store", "in": "query", "description": "Store vertical: apps, mac, books, audiobooks, movies, tv, music, or podcasts", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "mac", "books", "audiobooks", "movies", "tv", "music", "podcasts" ] } }, { "name": "chart", "in": "query", "description": "Chart type: top-free, top-paid, top-grossing, most-played, top-subscriber, or top-episodes. Music serves most-played albums, podcasts serve top shows; the response echoes requested and served chart types", "schema": { "type": [ "string", "null" ], "enum": [ "top-free", "top-paid", "top-grossing", "most-played", "top-subscriber", "top-episodes" ] } }, { "name": "genre", "in": "query", "description": "Apple genre id, passed through to the charts feeds as-is", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "description": "Maximum number of chart items", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/apple/app-store/developer": { "get": { "operationId": "apple.app-store.developer", "tags": [ "AppleAppStore" ], "parameters": [ { "name": "artist_id", "in": "query", "description": "Apple artist/developer id", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "country", "in": "query", "description": "Two-letter Apple storefront country code (default: us)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The product_id or another parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product_id or another parameter failed validation.", "value": { "message": "Error" } } } } } }, "404": { "description": "The product is legitimately absent in the requested storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The product is legitimately absent in the requested storefront.", "value": { "error": "Apple App Store product not found.", "retryable": false, "error_code": "apple_app_store_not_found" } } } } } }, "503": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Apple could not be fetched through the configured proxy tiers after the full attempt budget.", "value": { "error": "Apple App Store upstream is temporarily unavailable.", "retryable": true, "error_code": "apple_app_store_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/arbeitsagentur/locations": { "get": { "operationId": "arbeitsagentur.locations.search", "description": "Search for German locations by postal code or city name.", "summary": "Search Arbeitsagentur Locations", "tags": [ "ArbeitsagenturJobs" ], "parameters": [ { "name": "plz", "in": "query", "description": "German postal code to look up (e.g. \"10115\")", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "suchwort", "in": "query", "description": "City or location name to search for (e.g. \"Berlin\")", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plz": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "plz" ] } } }, "required": [ "success", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/arbeitsagentur/jobs": { "get": { "operationId": "arbeitsagentur.jobs.search", "description": "Search for job listings from Germany's Federal Employment Agency with various filters.", "summary": "Search Arbeitsagentur Jobs", "tags": [ "ArbeitsagenturJobs" ], "parameters": [ { "name": "was", "in": "query", "description": "Job title, keyword, or occupation to search for (e.g. \"Software Entwickler\")", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "wo", "in": "query", "description": "Location to search in, e.g. city name or postal code (e.g. \"Berlin\" or \"10115\")", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "berufsfeld", "in": "query", "description": "Occupational field code to filter results by profession category", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "arbeitgeber", "in": "query", "description": "Filter by employer/company name", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts at 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "size", "in": "query", "description": "Number of results per page (1-100)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "angebotsart", "in": "query", "description": "Type of job offer: 1 = employment, 2 = self-employment, 4 = apprenticeships/dual study, 34 = internship/trainee", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2", "4", "34" ] } }, { "name": "arbeitszeit", "in": "query", "description": "Working hours type: vz = full-time, tz = part-time, snw = shift/night/weekend, ho = home office, mj = mini job", "schema": { "type": [ "string", "null" ], "pattern": "^(vz|tz|snw|ho|mj)(;(vz|tz|snw|ho|mj))*$" } }, { "name": "befristung", "in": "query", "description": "Contract duration: 1 = fixed-term, 2 = permanent/unlimited", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2" ] } }, { "name": "veroeffentlichtseit", "in": "query", "description": "Filter by publication date in days (e.g. 1 = last 24 hours, 7 = last week, 30 = last month)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "umkreis", "in": "query", "description": "Search radius in kilometers around the specified location (e.g. 25)", "schema": { "type": [ "integer", "null" ], "enum": [ "10", "25", "50", "100", "150", "200" ] } }, { "name": "zeitarbeit", "in": "query", "description": "Include temporary work positions: 1 (yes) or 0 (no)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "pav", "in": "query", "description": "Include listings from private employment agencies: 1 (yes) or 0 (no)", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "maxErgebnisse": { "type": "string" }, "page": { "type": "integer" }, "size": { "type": "integer" }, "stellenangebote": { "type": "array", "items": { "type": "object", "properties": { "beruf": { "type": [ "string", "null" ] }, "titel": { "type": "string" }, "refnr": { "type": "string" }, "aktuelleVeroeffentlichungsdatum": { "type": [ "string", "null" ] }, "eintrittsdatum": { "type": [ "string", "null" ] }, "arbeitgeber": { "type": [ "string", "null" ] }, "externeUrl": { "type": [ "string", "null" ] }, "arbeitsort": { "type": [ "object", "null" ], "properties": { "plz": { "type": [ "string", "null" ] }, "ort": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "land": { "type": [ "string", "null" ] }, "koordinaten": { "type": [ "object", "null" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } }, "required": [ "lat", "lon" ] }, "entfernung": { "type": [ "string", "null" ] } }, "required": [ "plz", "ort", "region", "land", "koordinaten", "entfernung" ] } }, "required": [ "beruf", "titel", "refnr", "aktuelleVeroeffentlichungsdatum", "eintrittsdatum", "arbeitgeber", "externeUrl", "arbeitsort" ] } }, "facetten": { "type": "object", "additionalProperties": { "type": "object", "properties": { "counts": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "counts" ] } } }, "required": [ "maxErgebnisse", "page", "size", "stellenangebote", "facetten" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "arbeitsagentur_jobs_validation_failed": { "summary": "One or more job-search parameters failed validation.", "value": { "errors": { "size": [ "Size cannot exceed 100 results per request." ] }, "message": "The given data was invalid." } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "arbeitsagentur_jobs_retry_exhausted": { "summary": "The VPN-only Arbeitsagentur request could not complete within its bounded retry budget.", "value": { "error": { "code": 503, "message": "Arbeitsagentur upstream is temporarily unavailable. Please retry shortly." }, "success": false } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/arbeitsagentur/job": { "get": { "operationId": "arbeitsagentur.job", "description": "Returns the raw upstream job-detail object for a specific `refnr`.", "summary": "Get Arbeitsagentur Job Details", "tags": [ "ArbeitsagenturJobs" ], "parameters": [ { "name": "refnr", "in": "query", "required": true, "description": "Arbeitsagentur reference number for the listing, usually returned from the Job Search endpoint", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "success", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/billiger/search": { "get": { "operationId": "billiger.search", "tags": [ "Billiger" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search text. Alias: q.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "description": "Search term (1-200 characters). Alias for query.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, { "name": "page_no", "in": "query", "description": "Page number (1-100). Alias for page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "1-based page number. Defaults to 1.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page_size", "in": "query", "description": "Results per page. Defaults to 20, maximum 50.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "sort", "in": "query", "description": "relevance, clickout_relevance, price, price_rev, rating, or disjunctive.", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "clickout_relevance", "price", "price_rev", "rating", "disjunctive" ] } }, { "name": "cat", "in": "query", "description": "Billiger category ID.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "doctype", "in": "query", "description": "auto, offer, product, or product_offer.", "schema": { "type": [ "string", "null" ], "enum": [ "auto", "offer", "product", "product_offer" ] } }, { "name": "filters[]", "in": "query", "required": true, "description": "Associative facet values returned by a previous search, for example filters[brand]=2220.", "schema": { "type": "array", "items": { "type": "string", "maxLength": 500 } } }, { "name": "fuzzy", "in": "query", "description": "Enable fuzzy matching.", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/billiger/baseproduct": { "get": { "operationId": "billiger.baseproduct", "tags": [ "Billiger" ], "parameters": [ { "name": "baseproduct_id", "in": "query", "required": true, "description": "Canonical Billiger baseproduct identifier from search.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/billiger/product": { "get": { "operationId": "billiger.product", "tags": [ "Billiger" ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "description": "Canonical Billiger product identifier from search or a product group.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/billiger/offers": { "get": { "operationId": "billiger.offers", "tags": [ "Billiger" ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "description": "Canonical Billiger product identifier.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_no", "in": "query", "description": "Page number (1-100). Alias for page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "1-based page number. Defaults to 1.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page_size", "in": "query", "description": "Offers per page. Defaults to 20, maximum 50.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "product_offers_sorting", "in": "query", "description": "Sort offers by: relevance, price, total_price, shop_userreview_rating or shop_userreview_count. Alias for sort.", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "price", "total_price", "shop_userreview_rating", "shop_userreview_count" ] } }, { "name": "sort", "in": "query", "description": "relevance, price, total_price, shop_userreview_rating, shop_userreview_count, or shop_rating alias.", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "price", "total_price", "shop_userreview_rating", "shop_userreview_count", "shop_rating" ] } }, { "name": "product_offers_sorting_direction", "in": "query", "description": "Sort direction: asc or desc. Alias for direction.", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] } }, { "name": "direction", "in": "query", "description": "Sort direction: asc or desc.", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] } }, { "name": "product_offers_group_by_shop", "in": "query", "description": "Group offers by shop. Alias for group_by_shop.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "group_by_shop", "in": "query", "description": "Must remain false so offer pagination stays item-level and exhaustive.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "all", "in": "query", "description": "Set true to exhaust every expected offer page.", "schema": { "type": "boolean" } }, { "name": "offer_conditions", "in": "query", "description": "Numeric condition IDs such as 1 or 1,2,3.", "schema": { "type": [ "string", "null" ], "pattern": "^\\d+(,\\d+)*$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/billiger/shop": { "get": { "operationId": "billiger.shop", "tags": [ "Billiger" ], "parameters": [ { "name": "shop_id", "in": "query", "required": true, "description": "Canonical Billiger shop identifier from an offer.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/hotel": { "get": { "operationId": "booking.hotel", "summary": "Get hotel details from a Booking.com property page", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Booking.com hotel URL (e.g. https://www.booking.com/hotel/fr/ritz-paris.html). Either url OR (country + slug) is required.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/#i", "maxLength": 2048 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g. fr, us, de). Used together with slug.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "slug", "in": "query", "description": "Hotel slug from the Booking.com URL (e.g. ritz-paris). The trailing .html is optional.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9._-]+(?:\\.html)?$", "minLength": 2, "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "canonical_url": { "type": [ "string", "null" ] }, "og": { "type": "object", "additionalProperties": { "type": "string" } }, "twitter": { "type": "object", "additionalProperties": { "type": "string" } }, "hotel_schema": { "type": [ "object", "null" ], "additionalProperties": {} }, "aggregate_rating": { "type": [ "object", "null" ], "additionalProperties": {} }, "json_ld": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "parsed": { "type": "boolean" } }, "required": [ "title", "canonical_url", "og", "twitter", "hotel_schema", "aggregate_rating", "json_ld", "parsed" ] }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "url", "duration_ms", "scraped_at", "cached" ] } }, "required": [ "success", "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/search": { "get": { "operationId": "booking.search", "summary": "Search hotels on Booking.com", "tags": [ "Booking" ], "parameters": [ { "name": "ss", "in": "query", "required": true, "description": "Destination, e.g. \"Paris\" or \"New York\".", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "checkin", "in": "query", "description": "Check-in date (YYYY-MM-DD). Required for property cards to render.", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "checkout", "in": "query", "description": "Check-out date (YYYY-MM-DD). Required for property cards to render.", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "group_adults", "in": "query", "description": "Number of adults (1-30). Defaults to Booking.com default.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "group_children", "in": "query", "description": "Number of children (0-20).", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "no_rooms", "in": "query", "description": "Number of rooms (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "dest_id", "in": "query", "description": "Booking.com destination id when known (e.g. -1456928 for Paris). Helps Booking render resolved city result pages.", "schema": { "type": [ "integer", "null" ] } }, { "name": "dest_type", "in": "query", "description": "Booking.com destination type when known: city, region, district, hotel, landmark, or airport.", "schema": { "type": [ "string", "null" ], "enum": [ "city", "region", "district", "hotel", "landmark", "airport" ] } }, { "name": "lang", "in": "query", "description": "UI language hint (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "3-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "canonical_url": { "type": [ "string", "null" ] }, "og": { "type": "object", "additionalProperties": { "type": "string" } }, "h1": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "review_score": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "price": { "type": [ "string", "null" ] } }, "required": [ "name", "url", "image", "review_score", "location", "price" ] } }, "total_results": { "type": "integer" }, "json_ld": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "parsed": { "type": "boolean" } }, "required": [ "title", "canonical_url", "og", "h1", "results", "total_results", "json_ld", "parsed" ] }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "url", "duration_ms", "scraped_at", "cached" ] } }, "required": [ "success", "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/destinations": { "get": { "operationId": "booking.destinations", "tags": [ "Booking" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Destination query, e.g. Paris or New York.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "lang", "in": "query", "description": "UI language hint (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "3-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/search-by-url": { "get": { "operationId": "booking.search-by-url", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full Booking.com search or destination URL.", "schema": { "type": "string", "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/(?:searchresults\\.html|city/|region/|district/|landmark/|airport/)#i", "maxLength": 4096 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/review-scores": { "get": { "operationId": "booking.review-scores", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Booking.com hotel URL (e.g. https://www.booking.com/hotel/fr/ritz-paris.html). Either url OR (country + slug) is required.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/hotel/#i", "maxLength": 4096 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g. fr, us, de). Used together with slug.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "slug", "in": "query", "description": "Hotel slug from the Booking.com URL (e.g. ritz-paris). The trailing .html is optional.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9._-]+(?:\\.html)?$", "minLength": 2, "maxLength": 255 } }, { "name": "checkin", "in": "query", "description": "Check-in date (YYYY-MM-DD).", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "checkout", "in": "query", "description": "Check-out date (YYYY-MM-DD). Must be after checkin.", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "group_adults", "in": "query", "description": "Number of adults (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "group_children", "in": "query", "description": "Number of children (0-20).", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "no_rooms", "in": "query", "description": "Number of rooms (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "lang", "in": "query", "description": "Language code for the response (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "Three-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/reviews": { "get": { "operationId": "booking.reviews", "summary": "Extract paginated public guest review records from a Booking.com hotel", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Booking.com hotel URL (e.g. https://www.booking.com/hotel/fr/ritz-paris.html). Either url OR (country + slug) is required.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/hotel/#i", "maxLength": 4096 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g. fr, us, de). Used together with slug.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "slug", "in": "query", "description": "Hotel slug from the Booking.com URL (e.g. ritz-paris). The trailing .html is optional.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9._-]+(?:\\.html)?$", "minLength": 2, "maxLength": 255 } }, { "name": "lang", "in": "query", "description": "Review language hint (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "3-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "page", "in": "query", "description": "Review page number, 1-100. Defaults to 1.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "limit", "in": "query", "description": "Reviews per page, 1-25. Defaults to 10.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 25 } }, { "name": "sort", "in": "query", "description": "Sort order: recent_desc, recent_asc, score_desc, or score_asc. Defaults to recent_desc.", "schema": { "type": [ "string", "null" ], "enum": [ "recent_desc", "recent_asc", "score_desc", "score_asc" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "canonical_url": { "type": [ "string", "null" ] }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "string" }, "rating": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "positive_text": { "type": [ "string", "null" ] }, "negative_text": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "traveler_type": { "type": [ "string", "null" ] }, "stay_date": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } }, "required": [ "review_id", "rating", "title", "text", "positive_text", "negative_text", "author", "traveler_type", "stay_date", "created_at", "language" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "returned": { "type": "integer" }, "total_reviews": { "type": [ "integer", "null" ] }, "has_next_page": { "type": "boolean" } }, "required": [ "page", "limit", "offset", "returned", "total_reviews", "has_next_page" ] }, "parsed": { "type": "boolean" } }, "required": [ "title", "canonical_url", "reviews", "pagination", "parsed" ] }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "url", "duration_ms", "scraped_at", "cached" ] } }, "required": [ "success", "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/photos": { "get": { "operationId": "booking.photos", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Booking.com hotel URL (e.g. https://www.booking.com/hotel/fr/ritz-paris.html). Either url OR (country + slug) is required.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/hotel/#i", "maxLength": 4096 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g. fr, us, de). Used together with slug.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "slug", "in": "query", "description": "Hotel slug from the Booking.com URL (e.g. ritz-paris). The trailing .html is optional.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9._-]+(?:\\.html)?$", "minLength": 2, "maxLength": 255 } }, { "name": "checkin", "in": "query", "description": "Check-in date (YYYY-MM-DD).", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "checkout", "in": "query", "description": "Check-out date (YYYY-MM-DD). Must be after checkin.", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "group_adults", "in": "query", "description": "Number of adults (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "group_children", "in": "query", "description": "Number of children (0-20).", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "no_rooms", "in": "query", "description": "Number of rooms (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "lang", "in": "query", "description": "Language code for the response (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "Three-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/facilities": { "get": { "operationId": "booking.facilities", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Booking.com hotel URL (e.g. https://www.booking.com/hotel/fr/ritz-paris.html). Either url OR (country + slug) is required.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/hotel/#i", "maxLength": 4096 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g. fr, us, de). Used together with slug.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "slug", "in": "query", "description": "Hotel slug from the Booking.com URL (e.g. ritz-paris). The trailing .html is optional.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9._-]+(?:\\.html)?$", "minLength": 2, "maxLength": 255 } }, { "name": "checkin", "in": "query", "description": "Check-in date (YYYY-MM-DD).", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "checkout", "in": "query", "description": "Check-out date (YYYY-MM-DD). Must be after checkin.", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "group_adults", "in": "query", "description": "Number of adults (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "group_children", "in": "query", "description": "Number of children (0-20).", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "no_rooms", "in": "query", "description": "Number of rooms (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "lang", "in": "query", "description": "Language code for the response (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "Three-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/rooms": { "get": { "operationId": "booking.rooms", "tags": [ "Booking" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Booking.com hotel URL (e.g. https://www.booking.com/hotel/fr/ritz-paris.html). Either url OR (country + slug) is required.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "#^https?://(?:[a-z0-9-]+\\.)*booking\\.com/hotel/#i", "maxLength": 4096 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g. fr, us, de). Used together with slug.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "slug", "in": "query", "description": "Hotel slug from the Booking.com URL (e.g. ritz-paris). The trailing .html is optional.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9._-]+(?:\\.html)?$", "minLength": 2, "maxLength": 255 } }, { "name": "checkin", "in": "query", "description": "Check-in date (YYYY-MM-DD).", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "checkout", "in": "query", "description": "Check-out date (YYYY-MM-DD).", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "group_adults", "in": "query", "description": "Number of adults (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "group_children", "in": "query", "description": "Number of children (0-20).", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "no_rooms", "in": "query", "description": "Number of rooms (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "lang", "in": "query", "description": "UI language hint (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "3-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/prices": { "get": { "operationId": "booking.prices", "tags": [ "Booking" ], "parameters": [ { "name": "ss", "in": "query", "required": true, "description": "Destination, e.g. \"Paris\" or \"New York\".", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "checkin", "in": "query", "required": true, "description": "Check-in date (YYYY-MM-DD). Required for price cards to render.", "schema": { "type": "string", "format": "date" } }, { "name": "checkout", "in": "query", "required": true, "description": "Check-out date (YYYY-MM-DD). Required for price cards to render.", "schema": { "type": "string", "format": "date" } }, { "name": "group_adults", "in": "query", "description": "Number of adults (1-30). Defaults to Booking.com default.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "group_children", "in": "query", "description": "Number of children (0-20).", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "no_rooms", "in": "query", "description": "Number of rooms (1-30).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "dest_id", "in": "query", "description": "Booking.com destination id when known (e.g. -1456928 for Paris). Helps Booking render resolved city result pages.", "schema": { "type": [ "integer", "null" ] } }, { "name": "dest_type", "in": "query", "description": "Booking.com destination type when known: city, region, district, hotel, landmark, or airport.", "schema": { "type": [ "string", "null" ], "enum": [ "city", "region", "district", "hotel", "landmark", "airport" ] } }, { "name": "lang", "in": "query", "description": "UI language hint (e.g. en-us, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "currency", "in": "query", "description": "3-letter currency code (e.g. EUR, USD).", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "booking_pool_attempts": { "type": "string" }, "booking_pool_stages": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached", "booking_pool_attempts", "booking_pool_stages" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/booking/bulk-prices": { "post": { "operationId": "booking.bulk-prices", "tags": [ "Booking" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingBulkPricesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Booking bulk prices are temporarily disabled." } }, "required": [ "success", "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/domains/availability": { "get": { "operationId": "domains.availability", "tags": [ "DomainAvailability" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "The fully qualified domain name to check. Example: `example.com`", "schema": { "type": "string", "maxLength": 253 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "null" }, "registered": { "type": "null" }, "status": { "type": "string", "const": "unknown" }, "confidence": { "type": "string", "const": "low" }, "source": { "type": "string", "const": "rdap" }, "proxy_type": { "type": "string", "const": "vpn" }, "proxy_used": { "type": "string" }, "rdap_url": { "type": "string" }, "rdap_status_code": { "type": "integer" }, "message": { "type": "string", "const": "RDAP returned an inconclusive response." } }, "required": [ "domain", "available", "registered", "status", "confidence", "source", "proxy_type", "proxy_used", "rdap_url", "rdap_status_code", "message" ] }, { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": [ "boolean", "null" ] }, "registered": { "type": [ "boolean", "null" ] }, "status": { "type": "string", "enum": [ "registered", "unknown" ] }, "confidence": { "type": "string", "enum": [ "high", "low" ] }, "source": { "type": "string", "const": "rdap" }, "proxy_type": { "type": "string", "const": "vpn" }, "proxy_used": { "type": "string" }, "rdap_url": { "type": "string" }, "rdap_status_code": { "type": "integer" }, "rdap_events": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "date": { "type": "string" } }, "required": [ "action", "date" ] } }, "nameservers": { "type": "array", "items": {} } }, "required": [ "domain", "available", "registered", "status", "confidence", "source", "proxy_type", "proxy_used", "rdap_url", "rdap_status_code", "rdap_events", "nameservers" ] }, { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "boolean" }, "registered": { "type": "boolean" }, "status": { "type": "string", "const": "probably_available" }, "confidence": { "type": "string", "const": "medium" }, "source": { "type": "string", "const": "rdap" }, "proxy_type": { "type": "string", "const": "vpn" }, "proxy_used": { "type": "string" }, "rdap_url": { "type": "string" }, "rdap_status_code": { "type": "integer", "const": 404 }, "message": { "type": "string", "const": "RDAP returned not found. This usually means the domain is not registered, but it does not prove checkout availability, premium pricing, or registry restrictions." } }, "required": [ "domain", "available", "registered", "status", "confidence", "source", "proxy_type", "proxy_used", "rdap_url", "rdap_status_code", "message" ] }, { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "null" }, "registered": { "type": "null" }, "status": { "type": "string", "const": "unknown" }, "confidence": { "type": "string", "const": "low" }, "source": { "type": "string", "const": "iana_rdap_bootstrap" }, "proxy_type": { "type": "null" }, "proxy_used": { "type": "null" }, "message": { "type": "string", "const": "No RDAP server is listed for this TLD in the IANA bootstrap data." } }, "required": [ "domain", "available", "registered", "status", "confidence", "source", "proxy_type", "proxy_used", "message" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/economy-car-rentals/autocomplete": { "get": { "operationId": "economy-car-rentals.autocomplete", "summary": "Resolve EconomyCarRentals locations", "tags": [ "EconomyCarRentals" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Unicode location text containing 3 to 120 characters.", "schema": { "type": "string", "minLength": 3, "maxLength": 120 } }, { "name": "limit", "in": "query", "description": "Maximum matches to consider, from 1 to 200. Defaults to 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "language_id", "in": "query", "description": "Response language identifier. Version 1 supports 01 only.", "schema": { "type": "string", "enum": [ "01" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "query": { "type": "string" }, "limit": { "type": "integer" }, "language_id": { "type": "string" } }, "required": [ "engine", "query", "limit", "language_id" ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "country_code": { "type": "string" }, "country_name": { "type": "string" }, "country_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "hierarchy_key": { "type": "string" }, "selection_key": { "type": "string" } }, "required": [ "name", "country_code", "country_name", "country_id", "hierarchy_key", "selection_key" ] } } }, "required": [ "type", "label", "icon", "locations" ] } }, "related_searches": { "type": "array", "items": {} }, "related_searches_label": { "type": "string" }, "meta": { "type": "object", "properties": { "endpoint_family": { "type": "string" }, "proxy_tier": { "type": "string" }, "attempts": { "type": "integer" }, "duration_ms": { "type": "integer" } }, "required": [ "endpoint_family", "proxy_tier", "attempts", "duration_ms" ] } }, "required": [ "search_parameters", "groups", "related_searches", "related_searches_label", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "503": { "description": "Service unavailable. The request is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "endpoint_family": { "type": "string" }, "proxy_tier": { "type": "string" }, "attempts": { "type": "integer" }, "duration_ms": { "type": "integer" }, "retryable": { "type": "boolean" }, "billable": { "type": "boolean" } }, "required": [ "endpoint_family", "proxy_tier", "attempts", "duration_ms", "retryable", "billable" ] } }, "required": [ "error", "meta" ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/geizhals/search": { "get": { "operationId": "geizhals.search", "tags": [ "Geizhals" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keyword, e.g. thinkpad.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "loc", "in": "query", "description": "Market code: de, at, eu, pl, or uk. Defaults to de.", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "eu", "pl", "uk" ] } }, { "name": "lang", "in": "query", "description": "Response language: de or en. Defaults to de.", "schema": { "type": [ "string", "null" ], "enum": [ "de", "en" ] } }, { "name": "page", "in": "query", "description": "1-based page number. Defaults to 1.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "pagesize", "in": "query", "description": "Results per page, between 1 and 1000. Defaults to 10.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "sort", "in": "query", "description": "Optional sort key as used by Geizhals (e.g. price). Defaults to relevance.", "schema": { "type": [ "string", "null" ], "maxLength": 20 } }, { "name": "category", "in": "query", "description": "Optional Geizhals category id to constrain results.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "manufacturer", "in": "query", "description": "Optional manufacturer id to constrain results.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "string" }, "loc": { "type": "string" }, "lang": { "type": "string" }, "page": { "type": [ "object", "null" ] }, "pagesize": { "type": "integer" }, "total": { "type": "integer" }, "products": { "type": "array", "items": {} }, "pager": { "type": "object", "properties": { "first_page": { "type": "integer", "const": 1 }, "next_page": { "type": [ "string", "null" ] }, "last_page": { "type": [ "object", "null" ] } }, "required": [ "first_page", "next_page", "last_page" ] }, "facets": { "type": [ "string", "null" ] }, "category_suggestions": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "string" } }, "required": [ "duration_ms", "attempts" ] } }, "required": [ "success", "query", "loc", "lang", "page", "pagesize", "total", "products", "pager", "facets", "category_suggestions", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "enum": [ "Geizhals product API is temporarily unavailable. Please retry.", "Geizhals product API is currently unavailable." ] }, "failure_type": { "type": "string", "const": "unexpected_response_shape" }, "http_status": { "type": "integer" } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_REJECTED" }, "message": { "type": "string", "const": "Geizhals could not process this request." }, "failure_type": { "type": "string", "const": "upstream_rejected" }, "http_status": { "type": "integer", "const": 422 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "attempts": { "type": "integer" } }, "required": [ "success", "data", "attempts" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "const": "Geizhals product API is temporarily unavailable. Please retry." }, "failure_type": { "type": "string", "const": "proxy_pool_empty" }, "http_status": { "type": "integer", "const": 503 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "const": "Geizhals product API is temporarily unavailable. Please retry." }, "failure_type": { "type": "string", "const": "not_configured" }, "http_status": { "type": "integer", "const": 503 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/geizhals/product": { "get": { "operationId": "geizhals.product", "tags": [ "Geizhals" ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "description": "Known Geizhals product id from product URLs such as ...-a2194110.html or a search gzhid.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "loc", "in": "query", "description": "Market code: de, at, eu, pl, or uk. Defaults to de.", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "eu", "pl", "uk" ] } }, { "name": "lang", "in": "query", "description": "Response language: de or en. Defaults to de.", "schema": { "type": [ "string", "null" ], "enum": [ "de", "en" ] } }, { "name": "offers", "in": "query", "description": "Maximum number of merchant offers to include (1-100). Defaults to 20.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "merchant_details", "in": "query", "description": "Include merchant/shop details on offers. Defaults to true.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "reviews", "in": "query", "description": "Include test reviews and review details. Defaults to true.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "videos", "in": "query", "description": "Include product videos. Defaults to true.", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "product_id": { "type": "integer" }, "loc": { "type": "string" }, "lang": { "type": "string" }, "product": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "string" } }, "required": [ "duration_ms", "attempts" ] } }, "required": [ "success", "product_id", "loc", "lang", "product", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "PRODUCT_NOT_FOUND" }, "message": { "type": "string", "const": "Geizhals has no product for the requested id." }, "failure_type": { "type": "string", "const": "empty_product" }, "http_status": { "type": "integer", "const": 404 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "string" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "enum": [ "Geizhals product API is temporarily unavailable. Please retry.", "Geizhals product API is currently unavailable." ] }, "failure_type": { "type": "string", "const": "unexpected_response_shape" }, "http_status": { "type": "integer" } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_REJECTED" }, "message": { "type": "string", "const": "Geizhals could not process this request." }, "failure_type": { "type": "string", "const": "upstream_rejected" }, "http_status": { "type": "integer", "const": 422 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "attempts": { "type": "integer" } }, "required": [ "success", "data", "attempts" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "const": "Geizhals product API is temporarily unavailable. Please retry." }, "failure_type": { "type": "string", "const": "proxy_pool_empty" }, "http_status": { "type": "integer", "const": 503 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "const": "Geizhals product API is temporarily unavailable. Please retry." }, "failure_type": { "type": "string", "const": "not_configured" }, "http_status": { "type": "integer", "const": 503 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/geizhals/price-history": { "get": { "operationId": "geizhals.price-history", "tags": [ "Geizhals" ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "description": "Known Geizhals product id from product URLs such as ...-a2194110.html.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "days", "in": "query", "description": "History window in days. Defaults to 31. Maximum 3650.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650 } }, { "name": "loc", "in": "query", "description": "Market code: de, at, eu, pl, or uk. Defaults to de.", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "eu", "pl", "uk" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "const": "Geizhals price history is temporarily unavailable. Please retry." }, "failure_type": { "type": "string", "const": "unexpected_response_shape" }, "http_status": { "type": "integer", "enum": [ 502, 503 ] } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "product_id": { "type": "integer" }, "loc": { "type": "string" }, "days": { "type": "integer" }, "current_best": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "first_timestamp": { "type": "integer" }, "last_timestamp": { "type": "integer" }, "last_formatted": { "type": [ "string", "null" ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "timestamp_ms": { "type": "integer" }, "timestamp": { "type": "integer" }, "price": { "type": "number" }, "marker": { "type": [ "integer", "null" ] } }, "required": [ "timestamp_ms", "timestamp", "price", "marker" ] } }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "history_count": { "type": "integer" }, "attempts": { "type": "string" } }, "required": [ "duration_ms", "history_count", "attempts" ] } }, "required": [ "success", "product_id", "loc", "days", "current_best", "min", "max", "first_timestamp", "last_timestamp", "last_formatted", "history", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_UNAVAILABLE" }, "message": { "type": "string", "const": "Geizhals price history is temporarily unavailable. Please retry." }, "failure_type": { "type": "string", "const": "proxy_pool_empty" }, "http_status": { "type": "integer", "const": 503 } }, "required": [ "code", "message", "failure_type", "http_status" ] }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "integer" }, "attempts": { "type": "integer" }, "billable": { "type": "boolean" }, "retryable": { "type": "boolean" } }, "required": [ "duration_ms", "attempts", "billable", "retryable" ] } }, "required": [ "success", "error", "meta" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-hotels/search": { "get": { "operationId": "google-hotels.search", "tags": [ "Google Hotels" ], "parameters": [ { "name": "engine", "in": "query", "description": "SerpAPI-compatible engine identifier. Only google_hotels is accepted.", "schema": { "type": [ "string", "null" ], "enum": [ "google_hotels" ] } }, { "name": "q", "in": "query", "required": true, "description": "Location query for hotel search (e.g., \"Paris, France\", \"Near Eiffel Tower\")", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "check_in_date", "in": "query", "required": true, "description": "Check-in date in YYYY-MM-DD format (must be today or future date)", "schema": { "type": "string", "format": "date" } }, { "name": "check_out_date", "in": "query", "required": true, "description": "Check-out date in YYYY-MM-DD format (must be after check-in date)", "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "description": "Number of adult guests (1-10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "children", "in": "query", "description": "Number of children (0-6)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6 } }, { "name": "currency", "in": "query", "description": "3-letter currency code for prices (e.g., USD, EUR, GBP)", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "gl", "in": "query", "description": "2-letter country code for localization (e.g., us, gb, de, fr)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "description": "2-letter language code for results (e.g., en, es, fr, de)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "sort_by", "in": "query", "description": "Sort order: 3 (price lowest first), 8 (rating highest first), 13 (most reviewed first)", "schema": { "type": [ "integer", "null" ], "enum": [ "3", "8", "13" ] } }, { "name": "min_price", "in": "query", "description": "Minimum price per night filter", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "description": "Maximum price per night filter (must be greater than min_price)", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "hotel_class", "in": "query", "description": "Filter by hotel star rating IDs (comma-separated): 2, 3, 4, or 5", "schema": { "type": [ "integer", "null" ], "enum": [ "2", "3", "4", "5" ] } }, { "name": "free_cancellation", "in": "query", "description": "Filter for hotels with free cancellation (true/false)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "children_ages[]", "in": "query", "description": "Comma-separated children ages (1-17 years old). Count must match children.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 17 } } }, { "name": "rating", "in": "query", "description": "Minimum guest rating filter: 7 (3.5+), 8 (4.0+), 9 (4.5+)", "schema": { "type": [ "integer", "null" ], "enum": [ "7", "8", "9" ] } }, { "name": "amenities[]", "in": "query", "description": "Filter by amenity IDs (SerpAPI list, comma-separated). Example: 35 (Free Wi-Fi), 9 (Free breakfast), 15 (Bar)", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "vacation_rentals", "in": "query", "description": "Filter for vacation rental properties only (Airbnb-style properties) instead of hotels", "schema": { "type": [ "boolean", "null" ] } }, { "name": "eco_certified", "in": "query", "description": "Filter for eco-certified/sustainable hotels only", "schema": { "type": [ "boolean", "null" ] } }, { "name": "special_offers", "in": "query", "description": "Filter for hotels with special offers/deals", "schema": { "type": [ "boolean", "null" ] } }, { "name": "property_types[]", "in": "query", "description": "Filter by property type IDs (SerpAPI list, comma-separated). Example: 12 (Beach hotels), 1 (Apartments)", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "brands[]", "in": "query", "description": "Filter by brand IDs (use brands[].id from response)", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "bedrooms", "in": "query", "description": "Minimum number of bedrooms (1-20, vacation rentals only)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "bathrooms", "in": "query", "description": "Minimum number of bathrooms (1-20, vacation rentals only)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "next_page_token", "in": "query", "description": "Pagination token from previous response", "schema": { "type": [ "string", "null" ] } }, { "name": "property_token", "in": "query", "description": "Property token for a specific hotel (from search results)", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-hotels/autocomplete": { "get": { "operationId": "google-hotels.autocomplete", "tags": [ "Google Hotels" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Location search query", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "hl", "in": "query", "description": "2-letter language code for results (e.g., en, es, fr, de)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "2-letter country code for localization (e.g., us, gb, de, fr)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "currency", "in": "query", "description": "3-letter currency code used in suggestion links (e.g., USD, EUR, GBP)", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "type", "in": "query", "description": "Type of suggestions to return: location (cities/locations only), hotel (accommodations only), all (both). Default: hotel", "schema": { "type": [ "string", "null" ], "enum": [ "location", "hotel", "all" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "The q, hl, gl, currency, or type query parameter failed validation before the Google Hotels autocomplete request ran.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The q, hl, gl, currency, or type query parameter failed validation before the Google Hotels autocomplete request ran.", "value": { "errors": { "q": [ "The q field is required." ] }, "message": "The request validation failed" } } } } } }, "403": { "description": "Google returned a blocking or forbidden response through the configured cookie/proxy session path.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_hotels_autocomplete_upstream_forbidden": { "summary": "Google Hotels autocomplete upstream blocked the request.", "description": "Google returned a blocking or forbidden response through the configured cookie/proxy session path.", "value": { "error": "Google Hotels autocomplete upstream blocked the request.", "retryable": true, "error_code": "google_hotels_autocomplete_upstream_forbidden", "status_code": 403, "upstream_status": 403 } } } } } }, "429": { "description": "Google rate limited the autocomplete request through the configured cookie/proxy session path.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_hotels_autocomplete_rate_limited": { "summary": "Google Hotels autocomplete upstream is rate limited.", "description": "Google rate limited the autocomplete request through the configured cookie/proxy session path.", "value": { "error": "Google Hotels autocomplete upstream is rate limited.", "retryable": true, "error_code": "google_hotels_autocomplete_rate_limited", "status_code": 429, "upstream_status": 429 } } } } } }, "502": { "description": "Google returned an unavailable non-200 response through the configured cookie/proxy session path. Google returned HTTP 200, but the response could not be parsed into the documented autocomplete suggestion shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_hotels_autocomplete_upstream_bad_response": { "summary": "Google Hotels autocomplete upstream returned an unavailable response.", "description": "Google returned an unavailable non-200 response through the configured cookie/proxy session path.", "value": { "error": "Google Hotels autocomplete upstream returned an unavailable response.", "retryable": true, "error_code": "google_hotels_autocomplete_upstream_bad_response", "status_code": 502, "upstream_status": 500 } }, "google_hotels_autocomplete_parse_failed": { "summary": "Google Hotels autocomplete returned an unparseable response.", "description": "Google returned HTTP 200, but the response could not be parsed into the documented autocomplete suggestion shape.", "value": { "error": "Google Hotels autocomplete returned an unparseable response.", "retryable": true, "error_code": "google_hotels_autocomplete_parse_failed", "status_code": 502, "upstream_status": 200 } } } } } }, "503": { "description": "The upstream returned HTTP 503, the provider-backed request could not connect, or Scrappa hit an unexpected temporary autocomplete failure after validation passed. Scrappa could not acquire a usable provider-backed Google cookie/proxy se...", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_hotels_autocomplete_temporary_unavailable": { "summary": "Google Hotels autocomplete is temporarily unavailable.", "description": "The upstream returned HTTP 503, the provider-backed request could not connect, or Scrappa hit an unexpected temporary autocomplete failure after validation passed.", "value": { "error": "Google Hotels autocomplete is temporarily unavailable.", "retryable": true, "error_code": "google_hotels_autocomplete_temporary_unavailable", "status_code": 503 } }, "google_hotels_autocomplete_cookie_session_unavailable": { "summary": "Google Hotels autocomplete cookie session is temporarily unavailable.", "description": "Scrappa could not acquire a usable provider-backed Google cookie/proxy session before the autocomplete request ran.", "value": { "error": "Google Hotels autocomplete cookie session is temporarily unavailable.", "retryable": true, "error_code": "google_hotels_autocomplete_cookie_session_unavailable", "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/images": { "get": { "operationId": "google.search.images", "summary": "Search Images", "tags": [ "Google Images" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Required", "schema": { "type": "string", "minLength": 1 } }, { "name": "hl", "in": "query", "description": "Localization", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "ISO 3166-1 alpha-2 country code for geo-targeting (e.g., `us`, `de`, `uk`, `jp`). Prioritizes images from websites in the specified country.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "imgsz", "in": "query", "description": "Image Filters", "schema": { "type": [ "string", "null" ], "enum": [ "large", "medium", "icon" ] } }, { "name": "imgtype", "in": "query", "description": "Filter by image type. Accepted values: `photo` (photographs), `clipart` (clip art), `lineart` (line drawings), `gif` (animated GIFs), `face` (images containing faces).", "schema": { "type": [ "string", "null" ], "enum": [ "photo", "clipart", "lineart", "gif", "face" ] } }, { "name": "imgcolor", "in": "query", "description": "Filter by dominant color. Accepted values: `color`, `gray`, `trans` (transparent), `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `white`, `black`, `brown`.", "schema": { "type": [ "string", "null" ], "enum": [ "color", "gray", "trans", "red", "orange", "yellow", "green", "teal", "blue", "purple", "pink", "white", "black", "brown" ] } }, { "name": "imgar", "in": "query", "description": "Filter by aspect ratio. Accepted values: `tall` (portrait orientation), `square` (1:1 ratio), `wide` (landscape orientation).", "schema": { "type": [ "string", "null" ], "enum": [ "tall", "square", "wide" ] } }, { "name": "tbs", "in": "query", "description": "Advanced Google filter string (e.g. isz:l to restrict to large images).", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "safe", "in": "query", "description": "Safe search filtering. Accepted values: `active` (filter explicit content), `off` (no filtering). Recommended to set `active` for public-facing applications.", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "page", "in": "query", "description": "Pagination", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "The q, page, locale, safe search, or image filter parameters are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The q, page, locale, safe search, or image filter parameters are missing or invalid.", "value": { "errors": { "q": [ "The q field is required." ] }, "message": "The request validation failed" } } } } } }, "502": { "description": "The primary VPN proxy fetch and configured recovery paths could not return usable Google Images HTML or JSON, including blocked/captcha responses, empty upstream bodies, parser failures, or provider/proxy failures.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "temporary_upstream_proxy_failure": { "summary": "Google Images results are temporarily unavailable.", "description": "The primary VPN proxy fetch and configured recovery paths could not return usable Google Images HTML or JSON, including blocked/captcha responses, empty upstream bodies, parser failures, or provider/proxy failures.", "value": { "error": "Google Images results are temporarily unavailable." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/jobs": { "get": { "operationId": "google-jobs.search", "summary": "Search for jobs", "tags": [ "Google Jobs" ], "parameters": [ { "name": "q", "in": "query", "description": "Search query. Required unless next_page_token is supplied.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "next_page_token", "in": "query", "description": "Pagination token from a previous response. Must be valid base64.", "schema": { "type": [ "string", "null" ] } }, { "name": "uule", "in": "query", "description": "Encoded location used to localise results.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "lrad", "in": "query", "description": "Search radius in kilometres: 5, 10, 25, 50 or 100.", "schema": { "type": [ "integer", "null" ], "enum": [ "5", "10", "25", "50", "100" ] } }, { "name": "uds", "in": "query", "description": "Filters", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } }, { "name": "date_posted", "in": "query", "description": "Only return jobs posted within this window: today, 3days, week, month, or a day count (1, 3, 7 or 14).", "schema": { "type": [ "string", "null" ], "enum": [ "today", "3days", "week", "month", "1", "3", "7", "14" ] } }, { "name": "job_type", "in": "query", "description": "Job type filter", "schema": { "type": [ "string", "null" ], "enum": [ "full_time", "part_time", "contract", "internship", "remote" ] } }, { "name": "hl", "in": "query", "description": "Interface language code (2 letters, e.g. en, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Country code for geographic targeting (2 letters, e.g. de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "google_domain", "in": "query", "description": "Google domain to query (e.g. google.com, google.de).", "schema": { "type": [ "string", "null" ], "maxLength": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/lens": { "get": { "operationId": "googleLens.lens", "summary": "Google Lens visual search", "tags": [ "Google Lens" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public HTTPS URL for the image to search.", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "q", "in": "query", "description": "Optional text used to refine visual or product matches.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "type", "in": "query", "description": "One of `all`, `products`, `exact_matches`, or `visual_matches`.", "schema": { "type": [ "string", "null" ], "enum": [ "all", "products", "exact_matches", "visual_matches" ] } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Lens could not complete the request." }, "error_code": { "type": "string", "const": "INTERNAL_ERROR" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "url": { "type": "string" }, "q": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "all" ] } ] } }, "required": [ "url", "q", "type" ] }, "visual_matches": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "exact_matches": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "related_content": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "search_parameters", "visual_matches", "exact_matches", "related_content" ] } ] } } } }, "422": { "description": "The URL is unsafe or the image is invalid. Not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "INVALID_IMAGE_URL": { "description": "The URL is unsafe or the image is invalid. Not billed.", "value": { "error": "The image URL must be a public HTTPS URL.", "retryable": false, "error_code": "INVALID_IMAGE_URL" } } } } } }, "502": { "description": "Google blocked the request. Not billed and retryable. Google returned an unexpected result layout. Not billed and retryable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "GOOGLE_LENS_BLOCKED": { "description": "Google blocked the request. Not billed and retryable.", "value": { "error": "Google Lens blocked the visual search request.", "retryable": true, "error_code": "GOOGLE_LENS_BLOCKED" } }, "PARSE_DRIFT": { "description": "Google returned an unexpected result layout. Not billed and retryable.", "value": { "error": "Google Lens returned an unexpected result layout.", "retryable": true, "error_code": "PARSE_DRIFT" } } } } } }, "503": { "description": "No approved proxy/browser session was available. Not billed and retryable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "PROXY_EXHAUSTED": { "description": "No approved proxy/browser session was available. Not billed and retryable.", "value": { "error": "No approved proxy/browser session was available for Google Lens.", "retryable": true, "error_code": "PROXY_EXHAUSTED" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/autocomplete": { "get": { "operationId": "google-maps-api.autocomplete", "description": "Get autocomplete suggestions for a search query.", "summary": "Autocomplete", "tags": [ "Google Maps" ], "parameters": [ { "name": "query", "in": "query", "description": "Search text to autocomplete (1-255 characters). Required unless q is supplied.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "q", "in": "query", "description": "Alias for query. Takes precedence when both are supplied.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "hl", "in": "query", "description": "Language code for results. Default: en. Examples: en, de, fr, es. Format: ISO 639-1 two-letter language code.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Country/region code for geo-filtering results. Examples: us, de, uk, jp. Format: ISO 3166-1 alpha-2 country code.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "ll", "in": "query", "description": "Latitude and longitude to bias results toward a specific location. Format: \"latitude,longitude\" (e.g., 40.7128,-74.0060 for New York City).", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.?\\d*,-?\\d+\\.?\\d*$" } }, { "name": "google_domain", "in": "query", "description": "Google domain to use for the search. Examples: google.com, google.de, google.com.br, google.co.uk.", "schema": { "type": [ "string", "null" ], "pattern": "^google\\.(?:[a-z]{2}|com|com\\.[a-z]{2}|co\\.[a-z]{2})$", "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "q": { "type": "string" }, "hl": { "type": "string" }, "gl": { "type": [ "string", "null" ] }, "google_domain": { "type": [ "string", "null" ] }, "ll": { "type": [ "string", "null" ] } }, "required": [ "engine", "q", "hl", "gl", "google_domain", "ll" ] }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "google_id": { "type": [ "string", "null" ] }, "place_id": { "type": [ "string", "null" ] }, "main_text": { "type": [ "string", "null" ] }, "subtext": { "type": [ "string", "null" ] }, "main_text_highlights": { "type": "array", "items": { "type": "object", "properties": { "offset": { "type": "integer" }, "length": { "type": "integer" } }, "required": [ "offset", "length" ] } }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "type", "google_id", "place_id", "main_text", "subtext", "main_text_highlights", "latitude", "longitude", "country" ] } }, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", "suggestions", "response_time_ms" ] } } } }, "422": { "description": "The q/query, locale, domain, or ll parameters failed validation before the Google Maps autocomplete request ran.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "description": "The q/query, locale, domain, or ll parameters failed validation before the Google Maps autocomplete request ran.", "value": { "errors": { "query": [ "The query field is required when q is not present." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "No provider/proxy path was available to complete the Google Maps autocomplete request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_maps_autocomplete_temporarily_unavailable": { "description": "No provider/proxy path was available to complete the Google Maps autocomplete request.", "value": { "error": "Service temporarily unavailable. Please retry.", "suggestions": [], "response_time_ms": 1500, "search_parameters": { "q": "bakery", "gl": "us", "hl": "en", "engine": "google_maps_autocomplete", "google_domain": "google.com" } } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/advanced-search": { "get": { "operationId": "google-maps-api.advanced-search", "description": "Search for businesses on Google Maps with advanced filtering options.", "summary": "Advanced Search", "tags": [ "Google Maps" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The search term that will be used by the API.", "schema": { "type": "string" } }, { "name": "lon", "in": "query", "description": "Longitude coordinate for the search center.", "schema": { "type": [ "number", "null" ] } }, { "name": "lat", "in": "query", "description": "Latitude coordinate for the search center.", "schema": { "type": [ "number", "null" ] } }, { "name": "zoom", "in": "query", "required": true, "description": "The level of detail displayed on the map.", "schema": { "type": "number", "minimum": 3, "maximum": 21 } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return.", "schema": { "type": [ "number", "null" ], "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number for pagination (0-based). Default: 0", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "hl", "in": "query", "description": "Language code for results (en, de, fr, es). Default: en", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code for geo-filtering (us, de, uk, jp).", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "google_domain", "in": "query", "description": "Google domain to use for the search (e.g., google.com, google.de).", "schema": { "type": [ "string", "null" ], "pattern": "^google\\.(?:[a-z]{2}|com|com\\.[a-z]{2}|co\\.[a-z]{2})$", "maxLength": 100 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to return (e.g., name,rating,review_count).", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_,.\\s]+$", "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "place_id": { "type": [ "string", "null" ] }, "rating": { "type": [ "number", "null" ] }, "review_count": { "type": [ "integer", "null" ] }, "price_level": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "phone_numbers": { "type": "array", "items": { "type": "string" } }, "full_address": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "subtypes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "type": { "type": [ "string", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "opening_hours": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "day": { "type": [ "string", "null" ] }, "hours": { "type": "array", "items": { "type": [ "string", "null" ] } }, "date": { "type": [ "string", "null" ] } }, "required": [ "day", "hours", "date" ] } }, "current_status": { "type": [ "string", "null" ] }, "photos_sample": { "type": "array", "items": { "type": "object", "properties": { "photo_id": { "type": "string" }, "photo_url": { "type": "string" } }, "required": [ "photo_id", "photo_url" ] } } }, "required": [ "name", "business_id", "place_id", "rating", "review_count", "price_level", "website", "domain", "phone_numbers", "full_address", "district", "latitude", "longitude", "subtypes", "type", "short_description", "opening_hours", "current_status", "photos_sample" ] } } }, "required": [ "items" ] } } } }, "422": { "description": "The query, zoom, coordinates, pagination, field projection, locale, or domain parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "description": "The query, zoom, coordinates, pagination, field projection, locale, or domain parameters failed validation.", "value": { "errors": { "zoom": [ "Zoom level must be between 3 and 21." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "The approved provider/proxy path was temporarily unavailable or blocked before usable Google Maps advanced search HTML was returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_maps_advanced_search_upstream_unavailable": { "description": "The approved provider/proxy path was temporarily unavailable or blocked before usable Google Maps advanced search HTML was returned.", "value": { "error": "Google Maps advanced search is temporarily unavailable. Please retry.", "items": [], "retryable": true, "error_code": "google_maps_advanced_search_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/business-details": { "get": { "operationId": "google-maps-api.business-details", "summary": "Fetch business details directly from Google Maps", "tags": [ "Google Maps" ], "parameters": [ { "name": "business_id", "in": "query", "required": true, "description": "Google Maps business identifier in google_id (0x...:0x...) or place_id (ChIJ...) format.", "schema": { "type": "string", "pattern": "^(0x[a-f0-9]{2,}:0x[a-f0-9]{2,}|ChIJ[A-Za-z0-9_-]+={0,2})$" } }, { "name": "hl", "in": "query", "description": "Language code for results. Default: en", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code for geo-filtering. Default: us", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "business_id": { "type": "string" }, "google_id": { "type": "string" }, "place_id": { "type": [ "string", "null" ] }, "google_mid": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "full_address": { "type": [ "string", "null" ] }, "review_count": { "type": "integer" }, "rating": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "opening_status": { "type": [ "string", "null" ] }, "working_hours": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "day": { "type": "string" }, "hours": { "type": "string" } }, "required": [ "day", "hours" ] } }, "website": { "type": [ "string", "null" ] }, "tld": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" }, "place_link": { "type": "string" }, "cid": { "type": [ "string", "null" ] }, "reviews_link": { "type": [ "string", "null" ] }, "web_reviews_url": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ] }, "owner_link": { "type": [ "string", "null" ] }, "owner_name": { "type": [ "string", "null" ] }, "booking_link": { "type": [ "string", "null" ] }, "reservations_link": { "type": [ "string", "null" ] }, "business_status": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "subtypes": { "type": "array", "items": { "type": "string" } }, "subtype_gcids": { "type": "array", "items": { "type": "string" } }, "photos_sample": { "type": "array", "items": { "type": "object", "properties": { "photo_id": { "type": [ "string", "null" ] }, "photo_url": { "type": "string" }, "photo_url_large": { "type": [ "string", "null" ] }, "video_thumbnail_url": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "photo_datetime_utc": { "type": [ "string", "null" ] }, "photo_timestamp": { "type": [ "integer", "null" ] } }, "required": [ "photo_id", "photo_url", "photo_url_large", "video_thumbnail_url", "latitude", "longitude", "type", "photo_datetime_utc", "photo_timestamp" ] } }, "global_plus_code": { "type": [ "string", "null" ] }, "compound_plus_code": { "type": [ "string", "null" ] }, "reviews_per_rating": { "type": [ "array", "null" ], "prefixItems": [ { "type": "integer" }, { "type": "integer" }, { "type": "integer" }, { "type": "integer" }, { "type": "integer" } ], "minItems": 5, "maxItems": 5, "additionalItems": false }, "reviews_removed_due_to_defamation": { "type": [ "object", "null" ], "properties": { "message": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "help_link": { "type": [ "string", "null" ] }, "help_link_text": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "is_active": { "type": [ "boolean", "null" ] }, "range_bucket": { "type": [ "integer", "null" ] }, "language": { "type": [ "string", "null" ] }, "minimum_removed_review_count": { "type": [ "integer", "null" ] }, "maximum_removed_review_count": { "type": [ "integer", "null" ] }, "count_text": { "type": [ "string", "null" ] } }, "required": [ "message", "title", "help_link", "help_link_text", "summary", "is_active", "range_bucket", "language", "minimum_removed_review_count", "maximum_removed_review_count", "count_text" ] }, "photo_count": { "type": "integer" }, "about": { "type": "array", "items": {} }, "address": { "type": [ "string", "null" ] }, "menu_link": { "type": [ "string", "null" ] }, "order_link": { "type": [ "string", "null" ] }, "price_level": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "street_address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "emails_and_contacts": { "type": "array", "items": {} }, "share_link": { "type": [ "string", "null" ] } }, "required": [ "business_id", "google_id", "place_id", "google_mid", "phone_number", "name", "latitude", "longitude", "full_address", "review_count", "rating", "timezone", "opening_status", "working_hours", "website", "tld", "verified", "place_link", "cid", "reviews_link", "web_reviews_url", "owner_id", "owner_link", "owner_name", "booking_link", "reservations_link", "business_status", "type", "subtypes", "subtype_gcids", "photos_sample", "global_plus_code", "compound_plus_code", "reviews_per_rating", "reviews_removed_due_to_defamation", "photo_count", "about", "address", "menu_link", "order_link", "price_level", "district", "street_address", "city", "zipcode", "state", "country", "emails_and_contacts", "share_link" ] } } } } }, "422": { "description": "The business_id parameter is required and must be a Google Maps google_id in 0x...:0x... format or a place_id starting with ChIJ. Locale parameters must use valid hl and gl codes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "description": "The business_id parameter is required and must be a Google Maps google_id in 0x...:0x... format or a place_id starting with ChIJ. Locale parameters must use valid hl and gl codes.", "value": { "errors": { "business_id": [ "The business ID must be either a google_id (e.g., 0x1234abcd:0x5678efgh) or a place_id (e.g., ChIJ...)." ] }, "message": "The business ID must be either a google_id (e.g., 0x1234abcd:0x5678efgh) or a place_id (e.g., ChIJ...)." } } } } } }, "404": { "description": "Google Maps did not return a business profile for the supplied business_id. This can happen when the ID is stale, the place is no longer public, or the ID points to a profile Google cannot serve in the requested locale.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "NOT_FOUND": { "description": "Google Maps did not return a business profile for the supplied business_id. This can happen when the ID is stale, the place is no longer public, or the ID points to a profile Google cannot serve in the requested locale.", "value": { "data": [], "status": "NOT_FOUND", "message": "Business not found. Please check the business ID and try again.", "business_id": "0x8640b88f75b395a3:0x8771a1c312c0bd48" } } } } } }, "503": { "description": "Scrappa could not fetch or parse the Google Maps business details response after the configured upstream and proxy attempts. This covers upstream Google Maps unavailability, blocked provider sessions, and proxy capacity exhaustion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_ERROR": { "description": "Scrappa could not fetch or parse the Google Maps business details response after the configured upstream and proxy attempts. This covers upstream Google Maps unavailability, blocked provider sessions, and proxy capacity exhaustion.", "value": { "data": [], "error": { "code": "UPSTREAM_ERROR", "message": "Unable to fetch business details due to a technical error." }, "status": "ERROR", "message": "Unable to fetch business details due to a technical error.", "retryable": true, "business_id": "0x8640b88f75b395a3:0x8771a1c312c0bd48" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/photos": { "get": { "operationId": "google-maps-api.photos", "description": "Retrieve photos for a Google Maps business/place with pagination support.", "summary": "Get Photos", "tags": [ "Google Maps" ], "parameters": [ { "name": "business_id", "in": "query", "required": true, "description": "Google Maps business identifier in google_id (0x...:0x...) or place_id (ChIJ...) format.", "schema": { "type": "string", "pattern": "^(0x[a-f0-9]{2,}:0x[a-f0-9]{2,}|ChIJ[A-Za-z0-9_-]+={0,2})$" } }, { "name": "page", "in": "query", "description": "Page token for pagination.", "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of photos to return (1-20).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "photo_id": { "type": [ "string", "null" ] }, "photo_url": { "type": "string" }, "photo_url_large": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "contributor_name": { "type": [ "string", "null" ] }, "contributor_url": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ] } }, "required": [ "photo_id", "photo_url", "photo_url_large", "width", "height", "contributor_name", "contributor_url", "posted_at" ] } }, "nextPage": { "type": [ "string", "null" ] } }, "required": [ "items", "nextPage" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/reviews": { "get": { "operationId": "google-maps-api.reviews", "description": "Fetch reviews for a Google Maps business.", "summary": "Get Reviews", "tags": [ "Google Maps" ], "parameters": [ { "name": "business_id", "in": "query", "required": true, "description": "Google Maps business identifier in google_id (0x...:0x...) or place_id (ChIJ...) format.", "schema": { "type": "string", "pattern": "^(0x[a-f0-9]{2,}:0x[a-f0-9]{2,}|ChIJ[A-Za-z0-9_-]+={0,2})$" } }, { "name": "page", "in": "query", "description": "Continuation token returned as nextPage by a previous response. Reusable for 30 minutes with the same business ID. Invalid or expired tokens return a non-billable 410 response.", "schema": { "type": [ "string", "null" ], "maxLength": 512 } }, { "name": "pages", "in": "query", "description": "Number of pages to fetch in a single request (1-50). Each successfully fetched page counts as one API credit. Multi-page requests are preferred for deeper pagination and include termination diagnostics.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "search", "in": "query", "description": "Filter reviews by keyword.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "sort", "in": "query", "description": "Sorting order: 1 for Most Relevant, 2 for Newest, 3 for Highest Rating, 4 for Lowest Rating.", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2", "3", "4" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of reviews to return per page.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "hl", "in": "query", "description": "Language code for results. Default: en", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code for geo-filtering. Default: us", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": [ "string", "null" ] }, "review_text": { "type": [ "array", "null" ], "items": { "type": "string" } }, "rating": { "type": [ "integer", "null" ] }, "timestamp": { "type": [ "integer", "null" ] }, "review_updated_timestamp": { "type": [ "integer", "null" ] }, "review_link": { "type": [ "string", "null" ] }, "review_source": { "type": "string" }, "is_google_review": { "type": "boolean" }, "review_likes": { "type": [ "integer", "null" ] }, "author_id": { "type": [ "string", "null" ] }, "author_link": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "author_profile_photo": { "type": [ "string", "null" ] }, "author_review_count": { "type": [ "integer", "null" ] }, "author_reviews_link": { "type": [ "string", "null" ] }, "author_photo_count": { "type": [ "integer", "null" ] }, "author_local_guide_level": { "type": [ "integer", "null" ] }, "owner_response_timestamp": { "type": [ "integer", "null" ] }, "owner_response_text": { "type": [ "array", "null" ], "items": { "type": "string" } }, "owner_response_language": { "type": [ "string", "null" ] }, "review_language": { "type": [ "array", "null" ], "items": { "type": "string" } }, "review_form": { "type": "object", "additionalProperties": {} }, "images": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "review_id", "review_text", "rating", "timestamp", "review_updated_timestamp", "review_link", "review_source", "is_google_review", "review_likes", "author_id", "author_link", "author_name", "author_profile_photo", "author_review_count", "author_reviews_link", "author_photo_count", "author_local_guide_level", "owner_response_timestamp", "owner_response_text", "owner_response_language", "review_language", "review_form", "images" ] } }, "nextPage": { "type": [ "string", "null" ] }, "termination_reason": { "type": "string" }, "feed_exhausted": { "type": [ "boolean", "null" ] }, "continuation_retries": { "type": "integer" }, "continuation_recovered": { "type": "boolean" }, "pages_fetched": { "type": [ "integer", "null" ] }, "pages_requested": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] } }, "required": [ "items", "nextPage", "termination_reason", "feed_exhausted", "continuation_retries", "continuation_recovered", "pages_fetched", "pages_requested", "error", "error_code", "retryable" ] } } } }, "422": { "description": "The business ID, pagination, sorting, or locale parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The business ID, pagination, sorting, or locale parameters failed validation.", "value": { "errors": { "business_id": [ "The business ID must be either a google_id or a place_id." ] }, "message": "The request validation failed" } } } } } }, "410": { "description": "The continuation token is invalid, expired, or belongs to a different business. This response is not billed; omit page to restart pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": {} }, "nextPage": { "type": "null" }, "error": { "type": "string" }, "error_code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "items", "nextPage", "error", "error_code", "retryable" ] } } } }, "503": { "description": "No review pages could be fetched after proxy or upstream attempts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "No review pages could be fetched after proxy or upstream attempts.", "value": { "error": "Page 1 failed after 3 attempts: could not obtain valid proxy", "items": [], "nextPage": null } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/review": { "get": { "operationId": "google-maps-api.single-review", "summary": "Get a single review by review ID", "tags": [ "Google Maps" ], "parameters": [ { "name": "review_id", "in": "query", "required": true, "description": "The Google review ID.", "schema": { "type": "string", "pattern": "^C[A-Za-z0-9_-]+$", "minLength": 10, "maxLength": 100 } }, { "name": "business_id", "in": "query", "required": true, "description": "Google Maps business identifier in google_id (0x...:0x...) or place_id (ChIJ...) format.", "schema": { "type": "string", "pattern": "^(0x[a-f0-9]{2,}:0x[a-f0-9]{2,}|ChIJ[A-Za-z0-9_-]+={0,2})$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": [ "object", "null" ], "properties": { "review_id": { "type": "string" }, "reviewer_name": { "type": [ "string", "null" ] }, "reviewer_image": { "type": [ "string", "null" ] }, "reviewer_url": { "type": [ "string", "null" ] }, "reviewer_id": { "type": [ "string", "null" ] }, "reviewer_review_count": { "type": [ "integer", "null" ] }, "reviewer_info": { "type": [ "string", "null" ] }, "local_guide_level": { "type": [ "integer", "null" ] }, "rating": { "type": "integer" }, "text": { "type": [ "string", "null" ] }, "time": { "type": [ "string", "null" ] }, "review_timestamp": { "type": [ "integer", "null" ] }, "review_datetime_utc": { "type": [ "string", "null" ] }, "review_language": { "type": [ "string", "null" ] }, "like_count": { "type": "integer" }, "review_source": { "type": "string" }, "owner_response": { "type": [ "string", "null" ] }, "owner_response_timestamp": { "type": [ "integer", "null" ] }, "owner_response_datetime_utc": { "type": [ "string", "null" ] }, "owner_response_language": { "type": [ "string", "null" ] }, "additional_ratings": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "photos": { "type": "array", "items": { "type": "object", "properties": { "photo_id": { "type": "string" }, "photo_url": { "type": "string" } }, "required": [ "photo_id", "photo_url" ] } } }, "required": [ "review_id", "reviewer_name", "reviewer_image", "reviewer_url", "reviewer_id", "reviewer_review_count", "reviewer_info", "local_guide_level", "rating", "text", "time", "review_timestamp", "review_datetime_utc", "review_language", "like_count", "review_source", "owner_response", "owner_response_timestamp", "owner_response_datetime_utc", "owner_response_language", "additional_ratings", "photos" ] }, "business_info": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "rating": { "type": [ "number", "null" ] }, "review_count": { "type": [ "integer", "null" ] } }, "required": [ "name", "business_id", "rating", "review_count" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "review", "business_info", "error" ] } } } }, "422": { "description": "The review_id or business_id parameter failed validation before the single review lookup ran.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "description": "The review_id or business_id parameter failed validation before the single review lookup ran.", "value": { "errors": { "review_id": [ "The review ID is required." ] }, "message": "The request validation failed" } } } } } }, "404": { "description": "Google Maps did not return the requested review for the supplied review_id and business_id pair.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_maps_single_review_not_found": { "description": "Google Maps did not return the requested review for the supplied review_id and business_id pair.", "value": { "error": "The requested review ID does not exist or has been removed.", "message": "Review not found" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/simple-search": { "get": { "operationId": "google-maps-api.simple-search", "description": "Search for businesses on Google Maps with a simple query.", "summary": "Simple Search", "tags": [ "Google Maps" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The search term that the API will use.", "schema": { "type": "string" } }, { "name": "hl", "in": "query", "description": "Language code for results. Default: en", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code for geo-filtering results.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "google_domain", "in": "query", "description": "Google domain to use for the search (e.g., google.com, google.de).", "schema": { "type": [ "string", "null" ], "pattern": "^google\\.(?:[a-z]{2}|com|com\\.[a-z]{2}|co\\.[a-z]{2})$", "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (1-200).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } }, { "name": "page", "in": "query", "description": "Page number for pagination (0-based). Default: 0", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to return (e.g., name,rating,review_count).", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "price_level": { "type": [ "string", "null" ] }, "price_level_text": { "type": [ "string", "null" ] }, "review_count": { "type": [ "integer", "null" ] }, "rating": { "type": [ "number", "null" ] }, "website": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "subtypes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "district": { "type": [ "string", "null" ] }, "full_address": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "full_description": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ] }, "owner_name": { "type": [ "string", "null" ] }, "owner_link": { "type": [ "string", "null" ] }, "order_link": { "type": [ "string", "null" ] }, "google_mid": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "phone_numbers": { "type": "array", "items": { "type": "string" } }, "place_id": { "type": [ "string", "null" ] }, "photos_sample": { "type": "array", "items": { "type": "object", "properties": { "photo_id": { "type": [ "string", "null" ] }, "photo_url": { "type": [ "string", "null" ] }, "photo_url_large": { "type": [ "string", "null" ] }, "video_thumbnail_url": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "type": { "type": "string" } }, "required": [ "photo_id", "photo_url", "photo_url_large", "video_thumbnail_url", "latitude", "longitude", "type" ] } }, "opening_hours": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "day": { "type": [ "string", "null" ] }, "hours": { "type": "array", "items": { "type": [ "string", "null" ] } }, "date": { "type": [ "string", "null" ] }, "special_day": { "type": [ "string", "null" ] } }, "required": [ "day", "hours", "date", "special_day" ] } }, "current_status": { "type": [ "string", "null" ] } }, "required": [ "name", "price_level", "price_level_text", "review_count", "rating", "website", "domain", "latitude", "longitude", "business_id", "subtypes", "district", "full_address", "timezone", "short_description", "full_description", "owner_id", "owner_name", "owner_link", "order_link", "google_mid", "type", "phone_numbers", "place_id", "photos_sample", "opening_hours", "current_status" ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "total_results": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "current_page", "limit", "total_results", "has_more" ] } }, "required": [ "items", "pagination" ] } } } }, "422": { "description": "The query, zoom, coordinates, pagination, field projection, locale, or domain parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "description": "The query, zoom, coordinates, pagination, field projection, locale, or domain parameters failed validation.", "value": { "errors": { "zoom": [ "Zoom level must be between 3 and 21." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "The approved provider/proxy path was temporarily unavailable or blocked before usable Google Maps advanced search HTML was returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_maps_advanced_search_upstream_unavailable": { "description": "The approved provider/proxy path was temporarily unavailable or blocked before usable Google Maps advanced search HTML was returned.", "value": { "error": "Google Maps advanced search is temporarily unavailable. Please retry.", "items": [], "retryable": true, "error_code": "google_maps_advanced_search_upstream_unavailable" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/maps/directions": { "get": { "operationId": "google-maps-api.directions", "description": "Get directions between two locations with route information.\nResponse format is compatible with SerpAPI's google_maps_directions engine.", "summary": "Get Directions", "tags": [ "Google Maps" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Starting point - address, place name, or coordinates.", "schema": { "type": "string", "minLength": 2, "maxLength": 500 } }, { "name": "destination", "in": "query", "required": true, "description": "Ending point - address, place name, or coordinates.", "schema": { "type": "string", "minLength": 2, "maxLength": 500 } }, { "name": "mode", "in": "query", "description": "Mode: driving, walking, bicycling, or transit. Default: driving", "schema": { "type": [ "string", "null" ], "enum": [ "driving", "walking", "bicycling", "transit" ] } }, { "name": "hl", "in": "query", "description": "Language code for results. Default: en", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code for geo-filtering.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_metadata": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "engine": { "type": "string" } }, "required": [ "id", "status", "created_at", "engine" ] }, "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "start_addr": { "type": "string" }, "end_addr": { "type": "string" }, "travel_mode": { "type": "string" } }, "required": [ "engine", "start_addr", "end_addr", "travel_mode" ] }, "places_info": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "data_id": { "type": "string" }, "gps_coordinates": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ] } }, "required": [ "address", "data_id", "gps_coordinates" ] } }, "directions": { "type": "array", "items": { "type": "object", "properties": { "travel_mode": { "type": "string" }, "via": { "type": [ "string", "null" ] }, "distance": { "type": "integer" }, "duration": { "type": "integer" }, "formatted_distance": { "type": "string" }, "formatted_duration": { "type": "string" }, "extensions": { "type": "array", "items": {} }, "trips": { "type": "array", "items": { "type": "object", "properties": { "travel_mode": { "type": "string" }, "distance": { "type": "integer" }, "duration": { "type": "integer" }, "formatted_distance": { "type": "string" }, "formatted_duration": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "action": { "type": "string" }, "distance": { "type": "integer" }, "duration": { "type": "integer" }, "formatted_distance": { "type": "string" }, "formatted_duration": { "type": "string" }, "gps_coordinates": { "type": "array", "items": {} } }, "required": [ "title", "action", "distance", "duration", "formatted_distance", "formatted_duration", "gps_coordinates" ] } } }, "required": [ "travel_mode", "distance", "duration", "formatted_distance", "formatted_duration", "details" ] } }, "duration_in_traffic": { "type": [ "integer", "null" ] }, "formatted_duration_in_traffic": { "type": [ "string", "null" ] }, "typical_duration_range": { "type": [ "string", "null" ] } }, "required": [ "travel_mode", "via", "distance", "duration", "formatted_distance", "formatted_duration", "extensions", "trips", "duration_in_traffic", "formatted_duration_in_traffic", "typical_duration_range" ] } }, "status": { "type": "string" }, "routes_count": { "type": "integer" } }, "required": [ "search_metadata", "search_parameters", "places_info", "directions", "status", "routes_count" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/news": { "get": { "operationId": "google.search.news", "description": "Search and scrape news articles from Google News.", "summary": "Search News", "tags": [ "Google News" ], "parameters": [ { "name": "q", "in": "query", "description": "Search query for news articles (optional if using tokens)", "schema": { "type": "string", "maxLength": 500 } }, { "name": "gl", "in": "query", "description": "Country code for geographic location (2 characters, e.g., us, uk, de)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "description": "Language code for the search interface (2 characters, e.g., en, de, fr). Default: en", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "topic_token", "in": "query", "description": "Token for specific news topic browsing (cannot use with q parameter)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "kgmid", "in": "query", "description": "Knowledge Graph entity ID (format: /m/... or /g/..., use alone)", "schema": { "type": [ "string", "null" ], "pattern": "^\\/[mg]\\/", "maxLength": 100 } }, { "name": "publication_token", "in": "query", "description": "Token for specific publication browsing (cannot use with q parameter)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "section_token", "in": "query", "description": "Token for specific news section (cannot use with q parameter)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "story_token", "in": "query", "description": "Token for specific story cluster (cannot use with q parameter)", "schema": { "type": [ "string", "null" ], "maxLength": 2000 } }, { "name": "so", "in": "query", "description": "Sort order (0 = relevance, 1 = date)", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "start", "in": "query", "description": "Starting offset for pagination (0-based). Cannot be used with page parameter.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-based). Default: 1", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "news_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "type": { "type": "string" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" }, "authors": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "title" ] }, "authors": { "type": "array", "items": { "type": "string" } }, "date": { "type": "string" }, "iso_date": { "type": "string" }, "published_at": { "type": "string" }, "thumbnail": { "type": "string" }, "thumbnail_small": { "type": "string" }, "snippet": { "type": "string" }, "story_token": { "type": "string" } }, "required": [ "position", "title", "link", "type" ] } }, "menu_links": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "topic_token": { "type": "string" } }, "required": [ "title", "link" ] } }, "related_publications": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "publication_token": { "type": "string" } }, "required": [ "title", "link" ] } }, "sub_menu_links": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "topic_token": { "type": "string" } }, "required": [ "title", "link" ] } }, "highlight": { "type": [ "object", "null" ], "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "source": { "type": "string" }, "date": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "title", "link" ] }, "related_topics": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" } }, "required": [ "title", "link" ] } }, "related_searches": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "query": { "type": "string" }, "link": { "type": "string" } }, "required": [ "position", "query", "link" ] } }, "stories": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "source": { "type": "string" }, "date": { "type": "string" } }, "required": [ "title", "link", "source" ] } } }, "required": [ "title", "link", "articles" ] } } }, "required": [ "news_results", "menu_links", "related_publications", "sub_menu_links", "highlight" ] } } } }, "422": { "description": "Provide a query or exactly one supported Google News token, and keep pagination and locale parameters valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "Provide a query or exactly one supported Google News token, and keep pagination and locale parameters valid.", "value": { "errors": { "q": [ "The q field is required when no token parameter is present." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "500": { "description": "Google News could not be fetched because the provider-backed cookie session or proxy request timed out. Usable Google News HTML was fetched, but Scrappa could not parse it into the documented response shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_news_cookie_session_timeout": { "summary": "Network error while fetching Google News page.", "description": "Google News could not be fetched because the provider-backed cookie session or proxy request timed out.", "value": { "error": "Network error while fetching Google News page." } }, "google_news_parse_error": { "summary": "An unexpected error occurred while parsing news results.", "description": "Usable Google News HTML was fetched, but Scrappa could not parse it into the documented response shape.", "value": { "error": "An unexpected error occurred while parsing news results." } } } } } }, "502": { "description": "Google News returned blocked, consent, captcha, or otherwise unusable HTML after provider-backed retries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_news_upstream_html_unusable": { "summary": "Failed to fetch Google News page.", "description": "Google News returned blocked, consent, captcha, or otherwise unusable HTML after provider-backed retries.", "value": { "error": "Failed to fetch Google News page." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/search": { "get": { "operationId": "google-search-api.search", "description": "Perform a Google search and get structured results including organic results,\nrelated searches, knowledge graphs, and more.", "summary": "Search Google", "tags": [ "Google Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Required", "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Geographic location for the search (e.g. \"Berlin, Germany\"). Cannot be combined with uule.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uule", "in": "query", "description": "Encoded location (deprecated; supported)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "google_domain", "in": "query", "description": "Google domain (e.g., google.de)", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "gl", "in": "query", "description": "Country code (e.g., us, de, fr)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "cr", "in": "query", "description": "Restrict results to countries (e.g., countryUS|countryDE)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "hl", "in": "query", "description": "Interface language code (2 letters, e.g. en, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "description": "Restrict results to language (e.g., lang_en)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "ludocid", "in": "query", "description": "Google local business identifier used to target a specific listing.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "lsig", "in": "query", "description": "Knowledge graph map signature", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "kgmid", "in": "query", "description": "Knowledge graph entity ID (e.g., /g/11b6gq7c8p)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "si", "in": "query", "description": "Encrypted cached search parameters", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "ibp", "in": "query", "description": "Controls rendering layouts and expansions", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uds", "in": "query", "description": "Google-provided filter strings", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "tbs", "in": "query", "description": "Advanced Google filter string (e.g. qdr:d to restrict to the past day).", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "as_qdr", "in": "query", "description": "Simple time range filter (e.g., d, w, m, y)", "schema": { "type": [ "string", "null" ] } }, { "name": "safe", "in": "query", "description": "Safe search mode (active, off)", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "nfpr", "in": "query", "description": "Exclude auto-corrected results (0 or 1)", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "filter", "in": "query", "description": "Enable/disable similar/omitted filters (0 or 1)", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "tbm", "in": "query", "description": "Search vertical: isch (images), vid (videos), nws (news), lcl (local), shop (shopping) or pts (patents). Omit for web results.", "schema": { "type": [ "string", "null" ], "enum": [ "isch", "vid", "nws", "lcl", "shop", "pts" ] } }, { "name": "start", "in": "query", "description": "Result offset for pagination (0-indexed)", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "description": "Page number (0-100). Convenience alternative to start.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "amount", "in": "query", "description": "Results per page (1-10, may return fewer)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_information": { "type": "object", "properties": { "query_displayed": { "type": "string" }, "total_results": { "type": "integer" }, "time_taken_displayed": { "type": "number" } }, "required": [ "query_displayed" ] }, "organic_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "redirect_link": { "type": "string" }, "displayed_link": { "type": "string" }, "snippet": { "type": "string" }, "snippet_highlighted_words": { "type": "array", "items": { "type": "string" } }, "thumbnail": { "type": "string" }, "favicon": { "type": "string" }, "source": { "type": "string" }, "followers": { "type": "string" }, "followers_count": { "type": "integer" }, "sitelinks": { "type": "object", "properties": { "inline": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" } }, "required": [ "title", "link" ] } } }, "required": [ "inline" ] }, "rich_snippet": { "type": "array", "items": { "type": "string" } } }, "required": [ "position", "title", "link" ] } }, "related_searches": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "link": { "type": "string" } }, "required": [ "query", "link" ] } }, "people_also_search_for": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "query": { "type": "string" }, "link": { "type": "string" }, "thumbnail": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "query", "link" ] } }, "related_questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "text_blocks": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "question" ] } }, "things_to_know": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "question": { "type": "string" } }, "required": [ "category", "question" ] } }, "knowledge_graph": { "type": [ "object", "null" ], "additionalProperties": {} }, "see_results_about": { "type": [ "object", "null" ], "properties": { "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "link": { "type": "string" }, "search_term": { "type": [ "string", "null" ] } }, "required": [ "title", "description", "link", "search_term" ] }, "twitter_card": { "type": [ "object", "null" ], "additionalProperties": {} }, "inline_videos": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "inline_images": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "local_map": { "type": [ "object", "null" ], "additionalProperties": {} }, "local_results": { "type": [ "object", "null" ], "properties": { "places": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "places" ] }, "popular_products": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {} } }, "perspectives": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {} } }, "nutrition_information": { "type": [ "object", "null" ], "additionalProperties": {} }, "refine_this_search": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {} } }, "total_results": { "type": "integer" }, "engine_used": { "type": "string" }, "service_used": { "type": "string" } }, "required": [ "search_information", "organic_results", "related_searches", "people_also_search_for", "related_questions", "things_to_know", "knowledge_graph", "see_results_about", "twitter_card", "inline_videos", "inline_images", "local_map", "local_results", "popular_products", "perspectives", "nutrition_information", "refine_this_search", "total_results", "engine_used", "service_used" ] } } } }, "422": { "description": "One or more query parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more query parameters failed validation.", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "The request validation failed" } } } } } }, "429": { "description": "No Google Search worker is currently available. Retry after a short delay.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "No Google Search worker is currently available. Retry after a short delay.", "value": { "error": "No workers are currently available. Please retry shortly." } } } } } }, "503": { "description": "Google Search and fallback providers are temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Google Search and fallback providers are temporarily unavailable.", "value": { "error": "Search providers are temporarily unavailable. Please retry shortly.", "retry_after": 30 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/search-advanced": { "get": { "operationId": "google-search-advanced.search", "tags": [ "Google Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Required", "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Geographic location for the search (e.g. \"Berlin, Germany\"). Cannot be combined with uule.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uule", "in": "query", "description": "Encoded location (deprecated; supported)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "google_domain", "in": "query", "description": "Google domain (e.g., google.de)", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "gl", "in": "query", "description": "Country code (e.g., us, de, fr)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "cr", "in": "query", "description": "Restrict results to countries (e.g., countryUS|countryDE)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "hl", "in": "query", "description": "Interface language code (2 letters, e.g. en, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "description": "Restrict results to language (e.g., lang_en)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "ludocid", "in": "query", "description": "Google local business identifier used to target a specific listing.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "lsig", "in": "query", "description": "Google local listing signature, used with ludocid to target one listing.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "kgmid", "in": "query", "description": "Google Knowledge Graph machine ID of the entity to target (e.g. /m/0dr90d).", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "si", "in": "query", "description": "Opaque Google search context token, passed through unchanged.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "ibp", "in": "query", "description": "Opaque Google interface parameter, passed through unchanged.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uds", "in": "query", "description": "Opaque Google filter token from a previous result page, passed through unchanged.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "tbs", "in": "query", "description": "Advanced Google filter string (e.g. qdr:d to restrict to the past day).", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "as_qdr", "in": "query", "description": "Simple time range filter (e.g., d, w, m, y)", "schema": { "type": [ "string", "null" ] } }, { "name": "safe", "in": "query", "description": "Safe search mode (active, off)", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "nfpr", "in": "query", "description": "Exclude auto-corrected results (0 or 1)", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "filter", "in": "query", "description": "Enable/disable similar/omitted filters (0 or 1)", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "tbm", "in": "query", "description": "Search vertical: isch (images), vid (videos), nws (news), lcl (local), shop (shopping) or pts (patents). Omit for web results.", "schema": { "type": [ "string", "null" ], "enum": [ "isch", "vid", "nws", "lcl", "shop", "pts" ] } }, { "name": "start", "in": "query", "description": "Result offset for pagination (0-indexed)", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "description": "Page number (0-100). Convenience alternative to start.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "amount", "in": "query", "description": "Results per page (1-10, may return fewer)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "device", "in": "query", "description": "Device used to fetch results: desktop (default), tablet, or mobile.", "schema": { "type": [ "string", "null" ], "enum": [ "desktop", "tablet", "mobile" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "The browser orchestrator, Google Search providers, or upstream SERP parsing are temporarily unable to return a valid result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The browser orchestrator, Google Search providers, or upstream SERP parsing are temporarily unable to return a valid result.", "value": { "error": "Google Search Advanced is temporarily unable to return a valid SERP." } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "One or more query parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more query parameters failed validation.", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "The request validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/search-light": { "get": { "operationId": "google-search-light.search", "description": "Perform a lightweight Google search. Returns structured JSON results.\n\nLimitations:\n- Max 200 results per query (10 pages \u00d7 20 results)\n\nTip: Use query modifiers like `filetype:pdf`, `site:reddit.com`, or `\"exact phrase\"` in your query.\n *\n * Response includes total_results at the root level as a convenience accessor\n * that mirrors search_information.total_results. people_also_search_for is\n * best-effort autocomplete enrichment and may be empty.\n *\n * @queryParam query string required The search query. Use modifiers like filetype:pdf, site:reddit.com, or \"exact phrase\". Example: artificial intelligence\n * @queryParam num integer Number of results per page (1-20). Default: 10. Example: 10\n * @queryParam page integer Page number for pagination (1-10). Mutually exclusive with \"start\". Example: 1\n * @queryParam start integer Starting index for offset-based pagination (0-170). Mutually exclusive with \"page\". Example: 0", "summary": "Google Search (Light)", "tags": [ "Google Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Required", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "num", "in": "query", "description": "Results per page (1-20, default 10).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "start", "in": "query", "description": "Starting index for offset-based pagination (0-170). Mutually exclusive with \"page\".", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 170 } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-10, default: 1). Mutually exclusive with \"start\". Internally converted to a start offset after validation.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "hl", "in": "query", "description": "Language", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "description": "Restrict results to language (e.g., lang_en)", "schema": { "type": [ "string", "null" ], "pattern": "^lang_[a-z]{2}$" } }, { "name": "gl", "in": "query", "description": "Geolocation", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "cr", "in": "query", "description": "Restrict to country (e.g., countryUS)", "schema": { "type": [ "string", "null" ], "pattern": "^country[A-Z]{2}$" } }, { "name": "safe", "in": "query", "description": "Safety", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "dateRestrict", "in": "query", "description": "Date filtering", "schema": { "type": [ "string", "null" ], "pattern": "^[dwmy]\\d*$" } }, { "name": "sort", "in": "query", "description": "Sort order (e.g., date)", "schema": { "type": [ "string", "null" ], "enum": [ "date", "date:r", "date:d" ] } }, { "name": "filter", "in": "query", "description": "Duplicate-content filter: 1 to omit near-duplicate results (default), 0 to keep them.", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "rights", "in": "query", "description": "Filter by usage rights (cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived)", "schema": { "type": [ "string", "null" ], "enum": [ "cc_publicdomain", "cc_attribute", "cc_sharealike", "cc_noncommercial", "cc_nonderived" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "organic_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "displayed_link": { "type": "string" }, "snippet": { "type": [ "string", "null" ] }, "snippet_highlighted_words": { "type": "array", "items": { "type": "string" } }, "thumbnail": { "type": [ "string", "null" ] }, "rich_snippet": { "type": [ "array", "null" ], "items": {} } }, "required": [ "position", "title", "link", "displayed_link", "snippet", "snippet_highlighted_words", "thumbnail", "rich_snippet" ] } }, "people_also_search_for": { "type": "array", "items": { "type": "string" } }, "search_information": { "type": "object", "properties": { "query_displayed": { "type": "string" }, "total_results": { "type": "integer" }, "time_taken": { "type": "number" } }, "required": [ "query_displayed", "total_results", "time_taken" ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "pages": { "type": "array", "items": {} } }, "required": [ "current_page", "pages" ] }, "total_results": { "type": "integer" } }, "required": [ "organic_results", "people_also_search_for", "search_information", "pagination", "total_results" ] } } } }, "422": { "description": "The query, pagination, localization, safe search, date, sort, duplicate filter, or rights parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_light_validation_failed": { "summary": "The request validation failed.", "description": "The query, pagination, localization, safe search, date, sort, duplicate filter, or rights parameters failed validation.", "value": { "errors": { "page": [ "Cannot use both \"page\" and \"start\" parameters together. Use \"page\" for page-based pagination (1, 2, 3...) or \"start\" for offset-based pagination (0, 10, 20...)." ], "query": [ "A search query is required." ] }, "message": "The request validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "403": { "description": "The API key is valid, but the account cannot use Search Light because email verification, free request, subscription, or credit-pack access is blocked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "FORBIDDEN": { "summary": "You've ran out of credits to use please purchase a subscription or a package.", "description": "The API key is valid, but the account cannot use Search Light because email verification, free request, subscription, or credit-pack access is blocked.", "value": { "code": "FORBIDDEN", "error": "You've ran out of credits to use please purchase a subscription or a package.", "status": 403 } } } } } }, "503": { "description": "Search Light could not fetch search results through the configured worker and proxy-backed fallback path. Search Light could not load the upstream configuration required to build the search request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_light_upstream_unavailable": { "summary": "Search request failed.", "description": "Search Light could not fetch search results through the configured worker and proxy-backed fallback path.", "value": { "error": "Internal server error", "service": "google_search_light" } }, "google_search_light_search_config_unavailable": { "summary": "Failed to prepare search request.", "description": "Search Light could not load the upstream configuration required to build the search request.", "value": { "error": "Internal server error", "service": "google_search_light" } } } } } }, "500": { "description": "Search Light fetched a response but could not parse it into the documented JSON result structure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_light_parse_failed": { "summary": "Failed to parse search response.", "description": "Search Light fetched a response but could not parse it into the documented JSON result structure.", "value": { "error": "Internal server error", "service": "google_search_light" } } } } } } } } }, "/search-light/autocomplete": { "get": { "operationId": "google-search-light.autocomplete", "description": "Get search suggestions for a query prefix. Returns up to 10 suggestions.", "summary": "Google Search Autocomplete", "tags": [ "Google Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query prefix", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "hl", "in": "query", "description": "Language code (default: en)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "description": "Max suggestions (default: 10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } } }, "required": [ "query", "suggestions" ] } } } }, "422": { "description": "The query, language, or limit parameters failed validation before autocomplete ran.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_autocomplete_validation_failed": { "summary": "The request validation failed.", "description": "The query, language, or limit parameters failed validation before autocomplete ran.", "value": { "errors": { "query": [ "A search query is required." ] }, "message": "The request validation failed" } } } } } }, "429": { "description": "Google or the gateway path returned a rate-limit, block, or non-JSONP response instead of autocomplete suggestions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_autocomplete_upstream_rate_limited": { "summary": "Google Search Autocomplete is temporarily unable to return suggestions.", "description": "Google or the gateway path returned a rate-limit, block, or non-JSONP response instead of autocomplete suggestions.", "value": { "error": "Google Search Autocomplete is temporarily unable to return suggestions.", "service": "google_search_autocomplete" } } } } } }, "502": { "description": "The AWS gateway returned an empty body, malformed JSONP, or content that could not be decoded into the autocomplete response shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_autocomplete_gateway_bad_response": { "summary": "Google Search Autocomplete is temporarily unable to return suggestions.", "description": "The AWS gateway returned an empty body, malformed JSONP, or content that could not be decoded into the autocomplete response shape.", "value": { "error": "Google Search Autocomplete is temporarily unable to return suggestions.", "service": "google_search_autocomplete" } } } } } }, "503": { "description": "The configured AWS gateway/proxy path was unavailable, timed out, or could not connect to the upstream autocomplete service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_search_autocomplete_temporarily_unavailable": { "summary": "Google Search Autocomplete is temporarily unable to return suggestions.", "description": "The configured AWS gateway/proxy path was unavailable, timed out, or could not connect to the upstream autocomplete service.", "value": { "error": "Google Search Autocomplete is temporarily unable to return suggestions.", "service": "google_search_autocomplete" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-translate": { "get": { "operationId": "google-translate-api.translate", "summary": "Translate text between languages", "tags": [ "Google Translate" ], "parameters": [ { "name": "source", "in": "query", "required": true, "description": "Source language code (e.g., \"en\", \"de\")", "schema": { "type": "string", "enum": [ "ab", "ace", "ach", "af", "sq", "alz", "am", "ar", "hy", "as", "awa", "ay", "az", "ban", "bm", "ba", "eu", "btx", "bts", "bbc", "be", "bem", "bn", "bew", "bho", "bik", "bs", "br", "bg", "bua", "yue", "ca", "ceb", "ny", "zh-CN", "zh-TW", "cv", "co", "crh", "hr", "cs", "da", "din", "dv", "doi", "dov", "nl", "dz", "en", "eo", "et", "ee", "fj", "fil", "tl", "fi", "fr", "fr-CA", "fy", "ff", "gaa", "gl", "lg", "ka", "de", "el", "gn", "gu", "ht", "cnh", "ha", "haw", "iw", "he", "hil", "hi", "hmn", "hu", "hrx", "is", "ig", "ilo", "id", "ga", "it", "ja", "jw", "jv", "kn", "pam", "kk", "km", "cgg", "rw", "ktu", "gom", "ko", "kri", "ku", "ckb", "ky", "lo", "ltg", "la", "lv", "lij", "li", "ln", "lt", "lmo", "luo", "lb", "mk", "mai", "mak", "mg", "ms", "ms-Arab", "ml", "mt", "mi", "mr", "chm", "mni-Mtei", "min", "lus", "mn", "my", "nr", "new", "ne", "nso", "no", "nus", "oc", "or", "om", "pag", "pap", "ps", "fa", "pl", "pt", "pt-PT", "pa", "pa-Arab", "qu", "rom", "ro", "rn", "ru", "sm", "sg", "sa", "gd", "sr", "st", "crs", "shn", "sn", "scn", "szl", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "ss", "sv", "tg", "ta", "tt", "te", "tet", "th", "ti", "ts", "tn", "tr", "tk", "ak", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "yua", "zu" ] } }, { "name": "text", "in": "query", "required": true, "description": "The text to translate", "schema": { "type": "string", "minLength": 1 } }, { "name": "target", "in": "query", "required": true, "description": "Target language code (e.g., \"en\", \"de\")", "schema": { "type": "string", "enum": [ "ab", "ace", "ach", "af", "sq", "alz", "am", "ar", "hy", "as", "awa", "ay", "az", "ban", "bm", "ba", "eu", "btx", "bts", "bbc", "be", "bem", "bn", "bew", "bho", "bik", "bs", "br", "bg", "bua", "yue", "ca", "ceb", "ny", "zh-CN", "zh-TW", "cv", "co", "crh", "hr", "cs", "da", "din", "dv", "doi", "dov", "nl", "dz", "en", "eo", "et", "ee", "fj", "fil", "tl", "fi", "fr", "fr-CA", "fy", "ff", "gaa", "gl", "lg", "ka", "de", "el", "gn", "gu", "ht", "cnh", "ha", "haw", "iw", "he", "hil", "hi", "hmn", "hu", "hrx", "is", "ig", "ilo", "id", "ga", "it", "ja", "jw", "jv", "kn", "pam", "kk", "km", "cgg", "rw", "ktu", "gom", "ko", "kri", "ku", "ckb", "ky", "lo", "ltg", "la", "lv", "lij", "li", "ln", "lt", "lmo", "luo", "lb", "mk", "mai", "mak", "mg", "ms", "ms-Arab", "ml", "mt", "mi", "mr", "chm", "mni-Mtei", "min", "lus", "mn", "my", "nr", "new", "ne", "nso", "no", "nus", "oc", "or", "om", "pag", "pap", "ps", "fa", "pl", "pt", "pt-PT", "pa", "pa-Arab", "qu", "rom", "ro", "rn", "ru", "sm", "sg", "sa", "gd", "sr", "st", "crs", "shn", "sn", "scn", "szl", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "ss", "sv", "tg", "ta", "tt", "te", "tet", "th", "ti", "ts", "tn", "tr", "tk", "ak", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "yua", "zu" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "translated_text": { "type": "string" } }, "required": [ "translated_text" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-trends/interest": { "get": { "operationId": "google-trends.interest", "summary": "Get Interest Over Time", "tags": [ "Google Trends" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The search keyword to analyze (e.g., \"tesla\", \"bitcoin\", \"covid\")", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "geo", "in": "query", "description": "Geographic location code (e.g., \"US\", \"DE\", \"GB\", \"Worldwide\")", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "time_range", "in": "query", "description": "Time period for data: 1h, 4h, 1d, 7d, 30d, 90d, 1y, 5y, all", "schema": { "type": [ "string", "null" ], "enum": [ "1h", "4h", "1d", "7d", "30d", "90d", "1y", "5y", "all" ] } }, { "name": "hl", "in": "query", "description": "2-letter language code for results (e.g., en, es, fr, de)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "search_type", "in": "query", "description": "Type of search: web, images, news, youtube, shopping", "schema": { "type": [ "string", "null" ], "enum": [ "web", "images", "news", "youtube", "shopping" ] } } ], "responses": { "200": { "description": "Interest over time data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "keyword": { "type": "string" }, "geo": { "type": "string" }, "time_range": { "type": "string" }, "hl": { "type": "string" }, "search_type": { "type": "string" } }, "required": [ "keyword", "geo", "time_range", "hl", "search_type" ] }, "timeline_data": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "date": { "type": "string" }, "value": { "type": "integer" } }, "required": [ "timestamp", "date", "value" ] } }, "interest_over_time": { "type": "object", "properties": { "average": { "type": "number" }, "max_value": { "type": "integer" }, "min_value": { "type": "integer" }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "date": { "type": "string" }, "value": { "type": "integer" } }, "required": [ "timestamp", "date", "value" ] } } }, "required": [ "average", "max_value", "min_value", "data_points" ] }, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", "timeline_data", "interest_over_time", "response_time_ms" ] } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "422": { "summary": "Invalid time_range or search_type parameter", "value": { "message": "Invalid time_range or search_type parameter" } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "502": { "summary": "Bad gateway - upstream service error", "value": { "message": "Bad gateway - upstream service error" } } } } } }, "503": { "description": "Service Unavailable - Google Trends upstream is rate limited or the cookie session pool is exhausted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_code": { "type": "string" }, "degraded_reason": { "type": "string" }, "upstream_status_code": { "type": "integer" }, "retryable": { "type": "boolean" }, "retry_after": { "type": "integer" } }, "required": [ "error", "error_code" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Missing required query parameter", "value": { "message": "Missing required query parameter" } } } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Trends request failed", "value": { "message": "Google Trends request failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-trends/related": { "get": { "operationId": "google-trends.related", "summary": "Get Related Queries", "tags": [ "Google Trends" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The search keyword to analyze", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "geo", "in": "query", "description": "Geographic location code (e.g., \"US\", \"DE\", \"Worldwide\")", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "time_range", "in": "query", "description": "Time period for data: 1h, 4h, 1d, 7d, 30d, 90d, 1y, 5y, all", "schema": { "type": [ "string", "null" ], "enum": [ "1h", "4h", "1d", "7d", "30d", "90d", "1y", "5y", "all" ] } }, { "name": "hl", "in": "query", "description": "2-letter language code for results", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "search_type", "in": "query", "description": "Type of search: web, images, news, youtube, shopping", "schema": { "type": [ "string", "null" ], "enum": [ "web", "images", "news", "youtube", "shopping" ] } } ], "responses": { "200": { "description": "Related queries and topics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "keyword": { "type": "string" }, "geo": { "type": "string" }, "hl": { "type": "string" }, "search_type": { "type": "string" } }, "required": [ "keyword", "geo", "hl", "search_type" ] }, "related_queries": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "value": { "type": "integer" }, "formatted_value": { "type": "string" } }, "required": [ "query", "value", "formatted_value" ] } }, "related_topics": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "integer" }, "formatted_value": { "type": "string" } }, "required": [ "topic", "type", "value", "formatted_value" ] } }, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", "related_queries", "related_topics", "response_time_ms" ] } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "Invalid time_range or search_type parameter", "value": { "message": "Invalid time_range or search_type parameter" } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_trends_related_upstream_unavailable": { "summary": "Google Trends returned an unusable upstream response", "value": { "message": "Google Trends returned an unusable upstream response" } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_trends_related_upstream_rate_limited": { "summary": "Google Trends is temporarily rate limited or the cookie session pool is exhausted", "value": { "message": "Google Trends is temporarily rate limited or the cookie session pool is exhausted" } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "missing_query": { "summary": "Missing required query parameter", "value": { "message": "Missing required query parameter" } } } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_trends_related_internal_error": { "summary": "Google Trends request failed unexpectedly", "value": { "message": "Google Trends request failed unexpectedly" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-trends/autocomplete": { "get": { "operationId": "google-trends.autocomplete", "summary": "Get Autocomplete Suggestions", "tags": [ "Google Trends" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The partial search query to get suggestions for", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "geo", "in": "query", "description": "Geographic location code (e.g., \"US\", \"DE\", \"Worldwide\")", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "hl", "in": "query", "description": "2-letter language code for results", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "Autocomplete suggestions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "keyword": { "type": "string" }, "geo": { "type": "string" }, "hl": { "type": "string" } }, "required": [ "keyword", "geo", "hl" ] }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "value", "type" ] } }, "response_time_ms": { "type": "integer" } }, "required": [ "search_parameters", "suggestions", "response_time_ms" ] } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "502": { "summary": "Bad gateway - upstream service error", "value": { "message": "Bad gateway - upstream service error" } } } } } }, "503": { "description": "Service Unavailable - Google Trends upstream is rate limited or the cookie session pool is exhausted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_code": { "type": "string" }, "degraded_reason": { "type": "string" }, "upstream_status_code": { "type": "integer" }, "retryable": { "type": "boolean" }, "retry_after": { "type": "integer" } }, "required": [ "error", "error_code" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Missing required query parameter", "value": { "message": "Missing required query parameter" } } } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Trends request failed", "value": { "message": "Google Trends request failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-finance/search": { "get": { "operationId": "google-finance.search", "tags": [ "GoogleFinance" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (stock symbol, company name, or crypto)", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code (default: us)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Finance request failed", "value": { "message": "Google Finance request failed" } } } } } }, "200": { "description": "Search results retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": [ "string", "null" ] }, "exchange": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "current_price": { "type": [ "number", "null" ] }, "price_change": { "type": [ "number", "null" ] }, "percent_change": { "type": [ "number", "null" ] }, "previous_close": { "type": [ "number", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "symbol", "exchange", "name", "type", "currency", "current_price", "price_change", "percent_change", "previous_close", "country" ] } } }, "required": [ "results" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No results found for the given query" }, "code": { "type": "string", "const": "NOT_FOUND" }, "status": { "type": "integer", "const": 404 }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Rate limit exceeded. Please try again later." }, "code": { "type": "string", "const": "RATE_LIMITED" }, "status": { "type": "integer", "const": 429 }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "code", "status", "errors" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Missing required query parameter", "value": { "message": "Missing required query parameter" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-finance/quote": { "get": { "operationId": "google-finance.quote", "summary": "Get complete stock quote", "tags": [ "GoogleFinance" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "Stock symbol (e.g., AAPL)", "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "exchange", "in": "query", "description": "Exchange code (e.g., NASDAQ). If not provided, the API will attempt to auto-resolve via an internal search. This adds latency and may fail for less common symbols.", "schema": { "type": [ "string", "null" ] } }, { "name": "period_type", "in": "query", "description": "Filter financials by period: quarterly or annual (default: returns visible data, typically quarterly)", "schema": { "type": [ "string", "null" ], "enum": [ "quarterly", "annual" ] } }, { "name": "hl", "in": "query", "description": "Language code (default: en)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(-[a-z]{2})?$", "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code (default: us)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}$", "maxLength": 10 } } ], "responses": { "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Finance request failed", "value": { "message": "Google Finance request failed" } } } } } }, "200": { "description": "Quote data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "exchange": { "type": "string" }, "current_price": { "type": "string" }, "price_change": { "type": "string" }, "percent_change": { "type": "string" }, "currency": { "type": "string" }, "market": { "type": "string" }, "extensions": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "symbol", "exchange", "current_price", "price_change", "percent_change", "currency", "market", "extensions" ] }, "key_stats": { "type": "object", "properties": { "previous_close": { "type": "string" }, "day_range": { "type": "string" }, "year_range": { "type": "string" }, "market_cap": { "type": "string" }, "avg_volume": { "type": "string" }, "pe_ratio": { "type": "string" }, "dividend_yield": { "type": "string" }, "primary_exchange": { "type": "string" }, "climate_change": { "type": "string" }, "stats": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "description": { "type": "string" } }, "required": [ "label", "value", "description" ] } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "link": { "type": "string" }, "description": { "type": "string" } }, "required": [ "text", "link", "description" ] } } }, "required": [ "previous_close", "day_range", "year_range", "market_cap", "avg_volume", "pe_ratio", "dividend_yield", "primary_exchange", "climate_change", "stats", "tags" ] }, "about": { "type": "object", "properties": { "description": { "type": "string" }, "ceo": { "type": "string" }, "founded": { "type": "string" }, "headquarters": { "type": "string" }, "employees": { "type": "string" }, "website": { "type": "string" }, "info": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "link": { "type": "string" } }, "required": [ "label", "value", "link" ] } } }, "required": [ "description", "ceo", "founded", "headquarters", "employees", "website", "info" ] }, "financials": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "period_type": { "type": "string" }, "table": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "value": { "type": "string" }, "change": { "type": "string" } }, "required": [ "title", "description", "value", "change" ] } } }, "required": [ "date", "period_type", "table" ] } } }, "required": [ "title", "results" ] } }, "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "snippet": { "type": "string" }, "link": { "type": "string" }, "source": { "type": "string" }, "date": { "type": "string" }, "iso_date": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "snippet", "link", "source", "date", "iso_date", "thumbnail" ] } } }, "required": [ "title", "items" ] } }, "discover_more": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "link": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" }, "extracted_price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "price_movement": { "type": "object", "properties": { "percentage": { "type": [ "number", "null" ] }, "movement": { "type": "string" } }, "required": [ "percentage", "movement" ] } }, "required": [ "stock", "link", "name", "price", "extracted_price", "currency", "price_movement" ] } } }, "required": [ "title", "items" ] } } }, "required": [ "summary", "key_stats", "about", "financials", "news", "discover_more" ] } }, "required": [ "quote" ] } } } }, "404": { "description": "Symbol not found - Could not determine exchange for symbol", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "error", "code", "status" ] } } } }, "503": { "description": "Service unavailable - Google Finance is temporarily unavailable or blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "error", "code", "status" ] } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "code", "status", "errors" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Missing required symbol parameter", "value": { "message": "Missing required symbol parameter" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-finance/historical": { "get": { "operationId": "google-finance.historical", "tags": [ "GoogleFinance" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "Stock symbol (e.g., AAPL)", "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "exchange", "in": "query", "description": "Exchange code (e.g., NASDAQ)", "schema": { "type": [ "string", "null" ] } }, { "name": "range", "in": "query", "description": "Time range: 1=1d, 2=5d, 3=1m, 4=6m, 5=YTD, 6=1y, 7=5y, 8=max (default: 6)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 8 } }, { "name": "start_date", "in": "query", "description": "Start date for custom range (YYYY-MM-DD)", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date for custom range (YYYY-MM-DD)", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "interval", "in": "query", "description": "Data interval: daily, weekly, monthly (default: daily)", "schema": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly" ] } }, { "name": "hl", "in": "query", "description": "Language code (default: en)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code (default: us)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Finance request failed", "value": { "message": "Google Finance request failed" } } } } } }, "200": { "description": "Historical data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": [ "string", "null" ] }, "exchange": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "previous_close": { "type": [ "number", "null" ] }, "prices": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "integer" }, "close": { "type": "number" }, "change": { "type": "number" }, "percent_change": { "type": "number" }, "volume": { "type": "integer" } }, "required": [ "date", "close", "change", "percent_change", "volume" ] } } }, "required": [ "symbol", "exchange", "currency", "previous_close", "prices" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No historical data found for the given symbol" }, "code": { "type": "string", "const": "NOT_FOUND" }, "status": { "type": "integer", "const": 404 }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Rate limit exceeded. Please try again later." }, "code": { "type": "string", "const": "RATE_LIMITED" }, "status": { "type": "integer", "const": 429 }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "code", "status", "errors" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Missing required symbol parameter", "value": { "message": "Missing required symbol parameter" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-finance/indices": { "get": { "operationId": "google-finance.indices", "summary": "Get market indices", "tags": [ "GoogleFinance" ], "parameters": [ { "name": "indices", "in": "query", "description": "Comma-separated list of index symbols (default: S&P 500, Dow Jones, NASDAQ, Russell 2000)", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "description": "Language code (default: en)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code (default: us)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "200": { "description": "Market indices retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "indices": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "exchange": { "type": [ "string", "null" ] }, "full_symbol": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "current_price": { "type": [ "number", "null" ] }, "price_change": { "type": [ "number", "null" ] }, "percent_change": { "type": [ "number", "null" ] }, "previous_close": { "type": [ "number", "null" ] }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "symbol", "name", "exchange", "full_symbol", "currency", "current_price", "price_change", "percent_change", "previous_close", "price_movement" ] } } }, "required": [ "indices" ] } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "code", "status", "errors" ] } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Invalid indices parameter", "value": { "message": "Invalid indices parameter" } } } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Finance request failed", "value": { "message": "Google Finance request failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-finance/intraday": { "get": { "operationId": "google-finance.intraday", "tags": [ "GoogleFinance" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "Stock symbol (e.g., AAPL)", "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "exchange", "in": "query", "description": "Exchange code (e.g., NASDAQ)", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "description": "Language code (default: en)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code (default: us)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Finance request failed", "value": { "message": "Google Finance request failed" } } } } } }, "200": { "description": "Intraday graph data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": [ "string", "null" ] }, "exchange": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "graph": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "percent_change": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] }, "volume": { "type": [ "integer", "null" ] } }, "required": [ "price", "change", "percent_change", "currency", "date", "volume" ] } } }, "required": [ "symbol", "exchange", "currency", "graph" ] } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "code", "status", "errors" ] } } } }, "400": { "description": "Invalid characters in request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "error", "code", "status" ] } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "404": { "summary": "Symbol not found", "value": { "message": "Symbol not found" } } } } } }, "503": { "description": "Google Finance returned a retryable block or unrecognized response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "error", "code", "status" ] } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "429": { "summary": "Rate limited", "value": { "message": "Rate limited" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google-finance/markets": { "get": { "operationId": "google-finance.markets", "tags": [ "GoogleFinance" ], "parameters": [ { "name": "hl", "in": "query", "description": "Language code (default: en)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code (default: us)", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "trend", "in": "query", "description": "Market trend filter. One of: indexes, most-active, gainers, losers, climate-leaders, cryptocurrencies, currencies", "schema": { "type": [ "string", "null" ], "enum": [ "indexes", "most-active", "gainers", "losers", "climate-leaders", "cryptocurrencies", "currencies" ] } }, { "name": "index_market", "in": "query", "description": "Regional filter for indexes trend. One of: americas, europe-middle-east-africa, asia-pacific. Only used when trend=indexes.", "schema": { "type": [ "string", "null" ], "enum": [ "americas", "europe-middle-east-africa", "asia-pacific" ] } } ], "responses": { "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "500": { "summary": "Google Finance request failed", "value": { "message": "Google Finance request failed" } } } } } }, "200": { "description": "Markets data retrieved successfully. Returns either markets overview or trend data based on trend parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "markets": { "type": "object", "properties": { "us": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "exchange": { "type": "string" }, "price": { "type": "number" }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "stock", "name", "symbol", "exchange", "price", "price_movement" ] } }, "europe": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "exchange": { "type": "string" }, "price": { "type": "number" }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "stock", "name", "symbol", "exchange", "price", "price_movement" ] } }, "asia": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "exchange": { "type": "string" }, "price": { "type": "number" }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "stock", "name", "symbol", "exchange", "price", "price_movement" ] } }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "from_currency": { "type": "string" }, "to_currency": { "type": "string" }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "stock", "name", "price", "from_currency", "to_currency", "price_movement" ] } }, "crypto": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "from_currency": { "type": "string" }, "to_currency": { "type": "string" }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "stock", "name", "price", "from_currency", "to_currency", "price_movement" ] } }, "futures": { "type": "array", "items": { "type": "object", "properties": { "stock": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "exchange": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "price_movement": { "type": "object", "properties": { "direction": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "direction", "value", "percentage" ] } }, "required": [ "stock", "name", "symbol", "exchange", "price", "currency", "price_movement" ] } }, "top_news": {} }, "required": [ "us", "europe", "asia", "currencies", "crypto", "futures", "top_news" ] }, "market_trends": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "results": { "type": "array", "items": { "type": "array", "items": {} } } }, "required": [ "title", "results" ] } }, "news_results": { "type": "array", "items": { "type": "array", "items": {} } } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "404": { "summary": "No markets data found", "value": { "message": "No markets data found" } } } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch markets data" }, "code": { "type": "string", "const": "SERVICE_ERROR" }, "status": { "type": "integer", "const": 502 }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "429": { "summary": "Rate limited", "value": { "message": "Rate limited" } } } } } }, "422": { "description": "Validation error - Invalid parameters provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "code", "status", "errors" ] } } } }, "400": { "description": "Invalid characters in request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "error", "code", "status" ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/flights/airlines": { "get": { "operationId": "google-flights.airlines.free", "description": "Returns a list of supported airlines with their IATA codes and names.\nThis is a free endpoint that doesn't require authentication.", "summary": "Get Airlines List", "tags": [ "GoogleFlights" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "airlines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } } }, "required": [ "airlines" ] } } } } } } }, "/flights/airports": { "get": { "operationId": "google-flights.airports.free", "description": "Returns a list of major airports with their IATA codes, names, and locations.\nThis is a free endpoint that doesn't require authentication.", "summary": "Get Airports List", "tags": [ "GoogleFlights" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "airports": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "code", "name", "city", "country" ] } } }, "required": [ "airports" ] } } } } } } }, "/flights/one-way": { "get": { "operationId": "google-flights.one-way", "description": "Search for one-way flight options between two airports.", "summary": "Search One-Way Flights", "tags": [ "GoogleFlights" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Origin airport IATA code (e.g., JFK, LAX, ORD)", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "description": "Destination airport IATA code (e.g., LHR, CDG, SFO)", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "adults", "in": "query", "description": "Number of adult passengers (1-9, default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Number of child passengers (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "description": "Number of infants in seat (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "description": "Number of infants on lap (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "description": "Cabin class: economy, premium_economy, business, or first", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "exclude_basic", "in": "query", "description": "Exclude basic economy fares when searching in economy class (default: false)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "max_stops", "in": "query", "description": "Maximum stops: any, nonstop, one_or_fewer, or two_or_fewer", "schema": { "type": [ "string", "null" ], "enum": [ "any", "nonstop", "one_or_fewer", "two_or_fewer" ] } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en, de, en-US)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code (e.g., us, de, gb)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "currency", "in": "query", "description": "Currency code for prices (e.g., USD, EUR, GBP)", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "outbound_times", "in": "query", "description": "Outbound time window as comma-separated hours, e.g. \"6,18\" for departures between 06:00 and 18:00. Two further values narrow the arrival window.", "schema": { "type": [ "string", "null" ], "pattern": "^\\s*(?:[01]?\\d|2[0-3])\\s*,\\s*(?:[01]?\\d|2[0-3])\\s*(?:,\\s*(?:[01]?\\d|2[0-3])\\s*,\\s*(?:[01]?\\d|2[0-3])\\s*)?$" } }, { "name": "bags", "in": "query", "description": "Carry-on bag count. Only 0 is currently supported.", "schema": { "type": [ "integer", "null" ], "enum": [ "0" ] } }, { "name": "departure_date", "in": "query", "required": true, "description": "Departure date in Y-m-d format (e.g., 2026-09-15)", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Sort by: top_flights, cheapest, departure_time, arrival_time, or duration", "schema": { "type": [ "string", "null" ], "enum": [ "top_flights", "cheapest", "departure_time", "arrival_time", "duration", "emissions" ] } }, { "name": "airlines[]", "in": "query", "description": "Filter by airline IATA codes (e.g., [\"AA\", \"UA\", \"DL\"] or \"AA,UA,DL\")", "schema": { "type": "array", "pattern": "^[A-Z0-9]{2}$", "items": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2 } } }, { "name": "include_baggage", "in": "query", "description": "Include baggage fee information for the cheapest flight (1 = yes, 0 = no, default: 0)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "departure_time_min", "in": "query", "description": "Minimum departure hour (0-23). Use with departure_time_max to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "departure_time_max", "in": "query", "description": "Maximum departure hour (0-23). Use with departure_time_min to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_min", "in": "query", "description": "Minimum arrival hour (0-23). Use with arrival_time_max to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_max", "in": "query", "description": "Maximum arrival hour (0-23). Use with arrival_time_min to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "max_duration_minutes", "in": "query", "description": "Maximum flight duration in minutes. Filters out flights longer than this.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "max_price", "in": "query", "description": "Maximum price in the search currency. Filters out flights more expensive than this.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "flights": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "currency": { "type": "string" }, "total_duration_minutes": { "type": "integer" }, "legs": { "type": "array", "items": { "type": "object", "properties": { "departure_airport": { "type": [ "string", "null" ] }, "arrival_airport": { "type": [ "string", "null" ] }, "departure_time": { "type": [ "string", "null" ] }, "arrival_time": { "type": [ "string", "null" ] }, "duration_minutes": { "type": "integer" }, "airline": { "type": [ "string", "null" ] }, "airline_name": { "type": [ "string", "null" ] }, "flight_number": { "type": [ "string", "null" ] }, "stops": { "type": "integer" }, "aircraft": { "type": [ "string", "null" ] } }, "required": [ "departure_airport", "arrival_airport", "departure_time", "arrival_time", "duration_minutes", "airline", "airline_name", "flight_number", "stops", "aircraft" ] } } }, "required": [ "price", "currency", "total_duration_minutes", "legs" ] } }, "search_metadata": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "departure_date": { "type": "string" }, "return_date": { "type": [ "string", "null" ] }, "passengers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants_in_seat": { "type": "integer" }, "infants_on_lap": { "type": "integer" } }, "required": [ "adults", "children", "infants_in_seat", "infants_on_lap" ] }, "cabin_class": { "type": "string" }, "max_stops": { "type": "string" }, "sort_by": { "type": "string" }, "airlines": { "type": [ "array", "null" ], "items": {} }, "response_time_ms": { "type": "integer" } }, "required": [ "origin", "destination", "departure_date", "return_date", "passengers", "cabin_class", "max_stops", "sort_by", "airlines", "response_time_ms" ] } }, "required": [ "flights", "search_metadata" ] } } } }, "422": { "description": "origin, destination, and departure_date are required; passenger counts, cabin_class, max_stops, sort_by, airline filters, locale, time, duration, and price filters must be valid when provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "origin, destination, and departure_date are required; passenger counts, cabin_class, max_stops, sort_by, airline filters, locale, time, duration, and price filters must be valid when provided.", "value": { "errors": { "origin": [ "The origin field is required." ], "departure_date": [ "Departure date must be in Y-m-d format (e.g., 2026-09-15)." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "429": { "description": "The request was rejected by Scrappa API rate limiting or a temporary upstream retry-after condition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "RATE_LIMITED": { "summary": "Too many requests. Please slow down and try again later.", "description": "The request was rejected by Scrappa API rate limiting or a temporary upstream retry-after condition.", "value": { "message": "Too many requests. Please slow down and try again later.", "retry_after": 60 } } } } } }, "503": { "description": "Google Flights search could not run because the approved mobile proxy or upstream session path was temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_flights_one_way_temporarily_unavailable": { "summary": "Service temporarily unavailable. Please retry.", "description": "Google Flights search could not run because the approved mobile proxy or upstream session path was temporarily unavailable.", "value": { "code": "RATE_LIMITED", "error": "Too Many Requests", "status": 503, "message": "Service temporarily unavailable. Please retry.", "retry_after": 30 } } } } } }, "500": { "description": "Scrappa could not complete the Google Flights search after validation passed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_flights_one_way_service_error": { "summary": "The Google Flights search request failed unexpectedly.", "description": "Scrappa could not complete the Google Flights search after validation passed.", "value": { "error": "The Google Flights search request failed unexpectedly.", "service": "google_flights_one_way" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/flights/round-trip": { "get": { "operationId": "google-flights.round-trip", "description": "Search for round-trip flight options between two airports.", "summary": "Search Round-Trip Flights", "tags": [ "GoogleFlights" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Origin airport IATA code", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "description": "Destination airport IATA code", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "adults", "in": "query", "description": "Number of adult passengers (1-9)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Number of child passengers (0-9)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "description": "Number of infants in seat (0-9)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "description": "Number of infants on lap (0-9)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "description": "Cabin class: economy, premium_economy, business, or first", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "exclude_basic", "in": "query", "description": "Exclude basic economy fares when searching in economy class (default: false)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "max_stops", "in": "query", "description": "Maximum stops: any, nonstop, one_or_fewer, two_or_fewer", "schema": { "type": [ "string", "null" ], "enum": [ "any", "nonstop", "one_or_fewer", "two_or_fewer" ] } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en, de, en-US)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code (e.g., us, de, gb)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "currency", "in": "query", "description": "Currency code for prices (e.g., USD, EUR, GBP)", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "bags", "in": "query", "description": "Carry-on bag count. Only 0 is currently supported.", "schema": { "type": [ "integer", "null" ], "enum": [ "0" ] } }, { "name": "departure_date", "in": "query", "required": true, "description": "Departure date in Y-m-d format", "schema": { "type": "string", "format": "date" } }, { "name": "return_date", "in": "query", "required": true, "description": "Return date in Y-m-d format", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Sort results by: top_flights, cheapest, departure_time, arrival_time, duration", "schema": { "type": [ "string", "null" ], "enum": [ "top_flights", "cheapest", "departure_time", "arrival_time", "duration", "emissions" ] } }, { "name": "airlines[]", "in": "query", "description": "Filter by airline IATA codes (e.g., [\"AA\", \"UA\", \"DL\"] or \"AA,UA,DL\")", "schema": { "type": "array", "pattern": "^[A-Z0-9]{2}$", "items": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2 } } }, { "name": "include_baggage", "in": "query", "description": "Include baggage fee information for the cheapest flight (1 = yes, 0 = no, default: 0)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "departure_time_min", "in": "query", "description": "Minimum departure hour (0-23). Use with departure_time_max to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "departure_time_max", "in": "query", "description": "Maximum departure hour (0-23). Use with departure_time_min to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_min", "in": "query", "description": "Minimum arrival hour (0-23). Use with arrival_time_max to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_max", "in": "query", "description": "Maximum arrival hour (0-23). Use with arrival_time_min to filter by time range.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "max_duration_minutes", "in": "query", "description": "Maximum flight duration in minutes. Filters out flights longer than this.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "max_price", "in": "query", "description": "Maximum price in the search currency. Filters out flights more expensive than this.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "flights": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "currency": { "type": "string" }, "total_duration_minutes": { "type": "integer" }, "legs": { "type": "array", "items": { "type": "object", "properties": { "departure_airport": { "type": [ "string", "null" ] }, "arrival_airport": { "type": [ "string", "null" ] }, "departure_time": { "type": [ "string", "null" ] }, "arrival_time": { "type": [ "string", "null" ] }, "duration_minutes": { "type": "integer" }, "airline": { "type": [ "string", "null" ] }, "airline_name": { "type": [ "string", "null" ] }, "flight_number": { "type": [ "string", "null" ] }, "stops": { "type": "integer" }, "aircraft": { "type": [ "string", "null" ] } }, "required": [ "departure_airport", "arrival_airport", "departure_time", "arrival_time", "duration_minutes", "airline", "airline_name", "flight_number", "stops", "aircraft" ] } } }, "required": [ "price", "currency", "total_duration_minutes", "legs" ] } }, "search_metadata": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "departure_date": { "type": "string" }, "return_date": { "type": "string" }, "passengers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants_in_seat": { "type": "integer" }, "infants_on_lap": { "type": "integer" } }, "required": [ "adults", "children", "infants_in_seat", "infants_on_lap" ] }, "cabin_class": { "type": "string" }, "max_stops": { "type": "string" }, "sort_by": { "type": "string" }, "airlines": { "type": [ "array", "null" ], "items": {} }, "response_time_ms": { "type": "integer" } }, "required": [ "origin", "destination", "departure_date", "return_date", "passengers", "cabin_class", "max_stops", "sort_by", "airlines", "response_time_ms" ] } }, "required": [ "flights", "search_metadata" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/flights/date-range": { "get": { "operationId": "google-flights.date-range", "description": "Search across a date range to find the cheapest flight dates.\nReturns price data for each date combination in the range.", "summary": "Search Date Range for Best Prices", "tags": [ "GoogleFlights" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Origin airport IATA code", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "description": "Destination airport IATA code", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "adults", "in": "query", "description": "Number of adult passengers (1-9, default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Number of child passengers (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "description": "Number of infants in seat (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "description": "Number of infants on lap (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "description": "Cabin class: economy, premium_economy, business, or first (default: economy)", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "exclude_basic", "in": "query", "description": "Exclude basic economy fares when searching in economy class (default: false)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "max_stops", "in": "query", "description": "Maximum stops: any, nonstop, one_or_fewer, or two_or_fewer (default: any)", "schema": { "type": [ "string", "null" ], "enum": [ "any", "nonstop", "one_or_fewer", "two_or_fewer" ] } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en, de, en-US)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code (e.g., us, de, gb)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "currency", "in": "query", "description": "Currency code for prices (e.g., USD, EUR, GBP)", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "outbound_times", "in": "query", "description": "Outbound time window as comma-separated hours, e.g. \"6,18\" for departures between 06:00 and 18:00. Two further values narrow the arrival window.", "schema": { "type": [ "string", "null" ], "pattern": "^\\s*(?:[01]?\\d|2[0-3])\\s*,\\s*(?:[01]?\\d|2[0-3])\\s*(?:,\\s*(?:[01]?\\d|2[0-3])\\s*,\\s*(?:[01]?\\d|2[0-3])\\s*)?$" } }, { "name": "bags", "in": "query", "description": "Carry-on bag count. Only 0 is currently supported.", "schema": { "type": [ "integer", "null" ], "enum": [ "0" ] } }, { "name": "from_date", "in": "query", "required": true, "description": "Start of date range in Y-m-d format", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": true, "description": "End of date range in Y-m-d format", "schema": { "type": "string", "format": "date" } }, { "name": "trip_duration", "in": "query", "description": "Duration of trip in days (1-30, default: 7)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "date_price_combinations": { "type": "array", "items": { "type": "object", "properties": { "departure_date": { "type": "string" }, "return_date": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "total_duration_minutes": { "type": "integer" } }, "required": [ "departure_date", "return_date", "price", "currency", "total_duration_minutes" ] } }, "search_metadata": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "from_date": { "type": "string" }, "to_date": { "type": "string" }, "trip_duration_days": { "type": "integer" }, "passengers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants_in_seat": { "type": "integer" }, "infants_on_lap": { "type": "integer" } }, "required": [ "adults", "children", "infants_in_seat", "infants_on_lap" ] }, "cabin_class": { "type": "string" }, "max_stops": { "type": "string" }, "response_time_ms": { "type": "integer" } }, "required": [ "origin", "destination", "from_date", "to_date", "trip_duration_days", "passengers", "cabin_class", "max_stops", "response_time_ms" ] } }, "required": [ "date_price_combinations", "search_metadata" ] } } } }, "422": { "description": "origin, destination, from_date, and to_date are required; the date range, trip_duration, passenger counts, cabin_class, max_stops, locale, and currency must be valid when provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "origin, destination, from_date, and to_date are required; the date range, trip_duration, passenger counts, cabin_class, max_stops, locale, and currency must be valid when provided.", "value": { "errors": { "to_date": [ "End date must be after the start date." ], "from_date": [ "A start date for the date range is required." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "429": { "description": "The request was rejected by Scrappa API rate limiting or a temporary upstream retry-after condition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "RATE_LIMITED": { "summary": "Too many requests. Please slow down and try again later.", "description": "The request was rejected by Scrappa API rate limiting or a temporary upstream retry-after condition.", "value": { "message": "Too many requests. Please slow down and try again later.", "retry_after": 60 } } } } } }, "503": { "description": "Google Flights search could not run because the approved mobile proxy or upstream session path was temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_flights_date_range_temporarily_unavailable": { "summary": "Service temporarily unavailable. Please retry.", "description": "Google Flights search could not run because the approved mobile proxy or upstream session path was temporarily unavailable.", "value": { "code": "RATE_LIMITED", "error": "Too Many Requests", "status": 503, "message": "Service temporarily unavailable. Please retry.", "retry_after": 30 } } } } } }, "500": { "description": "Scrappa could not complete the Google Flights search after validation passed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_flights_date_range_service_error": { "summary": "The Google Flights search request failed unexpectedly.", "description": "Scrappa could not complete the Google Flights search after validation passed.", "value": { "error": "The Google Flights search request failed unexpectedly.", "service": "google_flights_date_range" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/flights/booking-details": { "get": { "operationId": "google-flights.booking-details", "description": "Get detailed booking information for a specific flight including price insights,\nprice history, fare options, and baggage information.", "summary": "Get Booking Details with Price Insights", "tags": [ "GoogleFlights" ], "parameters": [ { "name": "booking_token", "in": "query", "required": true, "description": "Booking token returned by the Google Flights search endpoint.", "schema": { "type": "string", "maxLength": 4096 } }, { "name": "origin", "in": "query", "required": true, "description": "Origin airport IATA code", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "description": "Destination airport IATA code", "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "departure_date", "in": "query", "required": true, "description": "Departure date in Y-m-d format", "schema": { "type": "string", "format": "date" } }, { "name": "airline", "in": "query", "required": true, "description": "Airline IATA code", "schema": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2 } }, { "name": "flight_number", "in": "query", "required": true, "description": "Flight number", "schema": { "type": "string" } }, { "name": "adults", "in": "query", "description": "Number of adult passengers (1-9).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Number of child passengers (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "description": "Number of infants in seat (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "description": "Number of infants on lap (0-9, default: 0)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "description": "Cabin class: economy, premium_economy, business or first.", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en, de, en-US)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "description": "Country/region code (e.g., us, de, gb)", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "currency", "in": "query", "description": "Currency code for prices and fare options (e.g., USD, EUR, GBP)", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "flight_details": { "type": "object", "properties": { "airline_code": { "type": "string" }, "airline_name": { "type": "string" }, "total_duration_minutes": { "type": "integer" }, "leg": { "type": "object", "properties": { "departure_airport": { "type": "string" }, "arrival_airport": { "type": "string" }, "duration_minutes": { "type": "integer" }, "aircraft": { "type": [ "string", "null" ] }, "flight_number": { "type": "string" } }, "required": [ "departure_airport", "arrival_airport", "duration_minutes", "aircraft", "flight_number" ] } }, "required": [ "airline_code", "airline_name", "total_duration_minutes", "leg" ] }, "price_insights": { "type": "object", "properties": { "price_assessment": { "type": "string" }, "current_price": { "type": "integer" }, "price_range": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "min", "max" ] }, "price_history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "timestamp": { "type": "integer" }, "price": { "type": "integer" } }, "required": [ "date", "timestamp", "price" ] } } }, "required": [ "price_assessment", "current_price", "price_range", "price_history" ] }, "fare_options": { "type": "array", "items": {} }, "baggage_info": { "type": "object", "properties": { "airline_code": { "type": "string" }, "airline_name": { "type": "string" }, "baggage_policy_url": { "type": "string" } }, "required": [ "airline_code", "airline_name", "baggage_policy_url" ] }, "booking_metadata": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "departure_date": { "type": "string" }, "airline": { "type": "string" }, "flight_number": { "type": "string" }, "response_time_ms": { "type": "integer" } }, "required": [ "origin", "destination", "departure_date", "airline", "flight_number", "response_time_ms" ] } }, "required": [ "flight_details", "price_insights", "fare_options", "baggage_info", "booking_metadata" ] } } } }, "422": { "description": "booking_token, origin, destination, departure_date, airline, and flight_number are required; passenger counts, cabin_class, hl, and gl must be valid when provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "booking_token, origin, destination, departure_date, airline, and flight_number are required; passenger counts, cabin_class, hl, and gl must be valid when provided.", "value": { "errors": { "booking_token": [ "The booking token field is required." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "502": { "description": "The booking details lookup could not be completed through the mobile proxy-backed Google Flights upstream path.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_flights_booking_upstream_unavailable": { "summary": "Google Flights booking details upstream is temporarily unavailable.", "description": "The booking details lookup could not be completed through the mobile proxy-backed Google Flights upstream path.", "value": { "error": "Google Flights booking details upstream is temporarily unavailable.", "service": "google_flights_booking_details" } } } } } }, "500": { "description": "Scrappa could not complete the booking details request after validation passed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_flights_booking_service_error": { "summary": "The booking details request failed unexpectedly.", "description": "Scrappa could not complete the booking details request after validation passed.", "value": { "error": "The booking details request failed unexpectedly.", "service": "google_flights_booking_details" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/details": { "get": { "operationId": "google.play.details", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Google Play could not be fetched through the configured server-status cookie session and curl_cffi sidecar path.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Google Play could not be fetched through the configured server-status cookie session and curl_cffi sidecar path.", "value": { "error": "Google Play upstream is temporarily unavailable.", "retryable": true, "error_code": "google_play_upstream_unavailable" } } } } } }, "422": { "description": "The id or url parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The id or url parameter failed validation.", "value": { "errors": { "id": [ "The id field is required when url is not provided." ] }, "message": "The request validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/product": { "get": { "operationId": "google.play.product", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/apps/product": { "get": { "operationId": "google.play.apps.product", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/audiobooks/product": { "get": { "operationId": "google.play.audiobooks.product", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/books/product": { "get": { "operationId": "google.play.books.product", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/movies/product": { "get": { "operationId": "google.play.movies.product", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/product/reviews": { "get": { "operationId": "google.play.product.reviews", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/play/tv/product": { "get": { "operationId": "google.play.tv.product", "tags": [ "GooglePlay" ], "parameters": [ { "name": "id", "in": "query", "description": "Legacy alias for product_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "product_id", "in": "query", "description": "Google Play product id. For apps this is the package name.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 255 } }, { "name": "url", "in": "query", "description": "Google Play URL of the item. Alternative to supplying the product identifier.", "schema": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 } }, { "name": "hl", "in": "query", "description": "Interface language code (e.g. en, de).", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "description": "Country code for the storefront (2 letters, e.g. us, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "store", "in": "query", "description": "Google Play store vertical: apps, movies, tv, books, or audiobooks.", "schema": { "type": [ "string", "null" ], "enum": [ "apps", "movies", "tv", "books", "audiobooks" ] } }, { "name": "season_id", "in": "query", "description": "TV season id for Google Play TV products.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "all_reviews", "in": "query", "description": "Request Google Play review-expanded product pages when available.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "platform", "in": "query", "description": "Review platform filter, such as phone, tablet, tv, chromebook, watch, or car.", "schema": { "type": [ "string", "null" ], "enum": [ "phone", "tablet", "tv", "chromebook", "watch", "car" ] } }, { "name": "rating", "in": "query", "description": "Review rating filter from 1 to 5.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "4", "5" ] } }, { "name": "sort_by", "in": "query", "description": "Review sort mode, such as 1, 2, 3, most_relevant, newest, or rating.", "schema": { "type": [ "string", "null" ], "enum": [ "1", "2", "3", "most_relevant", "newest", "rating" ] } }, { "name": "num", "in": "query", "description": "Requested review result count for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "next_page_token", "in": "query", "description": "Review pagination token for clients that need SerpApi-compatible parameters.", "schema": { "type": [ "string", "null" ], "maxLength": 1000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Google Play upstream is temporarily unavailable." }, "error_code": { "type": "string", "const": "google_play_upstream_unavailable" }, "retryable": { "type": "boolean" } }, "required": [ "error", "error_code", "retryable" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/internal/google-replay-sessions": { "post": { "operationId": "google-replay-sessions.store", "tags": [ "GoogleReplaySession" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Unauthorized" } }, "required": [ "error" ] } } } } } } }, "/internal/google-replay-sessions/expired-sample": { "get": { "operationId": "google-replay-sessions.expired-sample", "tags": [ "GoogleReplaySession" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sampled": { "type": "integer", "minimum": 0 }, "valid": { "type": "integer", "minimum": 0 }, "invalid": { "type": "integer", "minimum": 0 }, "by_bucket": { "type": "string" }, "results": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "bucket": {}, "expired_minutes": { "type": "string" }, "used_count": { "type": "integer" }, "replay_budget": { "type": "integer" }, "valid": { "type": "boolean" }, "exception": { "type": "string" }, "message": { "type": "string" }, "elapsed_ms": { "type": "integer" } }, "required": [ "id", "bucket", "expired_minutes", "used_count", "replay_budget", "valid", "exception", "message", "elapsed_ms" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "bucket": {}, "expired_minutes": { "type": "string" }, "used_count": { "type": "integer" }, "replay_budget": { "type": "integer" }, "valid": { "type": "boolean" }, "http_status": { "type": "integer" }, "final_url_host": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "integer" }, { "type": "object" } ] }, "final_url_is_sorry": { "type": "boolean" }, "captcha_or_429": { "type": "string" }, "google_shell": { "type": "boolean" }, "response_bytes": { "type": "integer" }, "response_time_ms": { "type": "integer" }, "fetcher_total_ms": { "type": "integer" }, "h3_count": { "type": "integer" }, "data_ved_count": { "type": "integer" }, "search_id_count": { "type": "integer" }, "result_stats_count": { "type": "integer" }, "classification": { "type": "string", "enum": [ "invalid", "consent", "captcha", "success", "tiny", "hard_block", "no_html" ] }, "elapsed_ms": { "type": "integer" } }, "required": [ "id", "bucket", "expired_minutes", "used_count", "replay_budget", "valid", "http_status", "final_url_host", "final_url_is_sorry", "captcha_or_429", "google_shell", "response_bytes", "response_time_ms", "fetcher_total_ms", "h3_count", "data_ved_count", "search_id_count", "result_stats_count", "classification", "elapsed_ms" ] } ] } } }, "required": [ "sampled", "valid", "invalid", "by_bucket", "results" ] } }, "required": [ "data" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Unauthorized" } }, "required": [ "error" ] } } } } } } }, "/google/shopping": { "get": { "operationId": "google.shopping.search", "description": "Returns normalized product cards from Google Shopping.\n\n`next_start` is the next offset to try and does not guarantee that another page has results.", "summary": "Search Google Shopping", "tags": [ "GoogleShopping" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Product search query.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "gl", "in": "query", "description": "Two-letter country code. Default: us.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "description": "Two-letter interface language. Default: en.", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "location", "in": "query", "description": "Location name encoded as a best-effort canonical UULE. Cannot be used with uule; provide uule directly for exact targeting.", "schema": { "type": [ "string", "null" ], "maxLength": 63 } }, { "name": "uule", "in": "query", "description": "Encoded Google location. Cannot be used with location.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "start", "in": "query", "description": "Zero-based pagination offset. Default: 0.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 990 } }, { "name": "device", "in": "query", "description": "desktop, mobile, or tablet. Default: desktop.", "schema": { "type": [ "string", "null" ], "enum": [ "desktop", "mobile", "tablet" ] } }, { "name": "small_business", "in": "query", "description": "Only return small-business results. Cannot be used with shoprs.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "shoprs", "in": "query", "description": "Opaque Google Shopping filter token. Cannot be used with small_business.", "schema": { "type": [ "string", "null" ], "maxLength": 2000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "gl": { "type": "string" }, "hl": { "type": "string" }, "start": { "type": "integer" }, "device": { "type": "string" }, "small_business": { "type": "boolean" }, "location": { "type": "string" }, "uule": { "type": "string" }, "shoprs": { "type": "string" } }, "required": [ "q", "gl", "hl", "start", "device" ] }, "shopping_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "product_id": { "type": "string" }, "link": { "type": "string" }, "price": { "type": "string" }, "extracted_price": { "type": "number" }, "source": { "type": "string" }, "delivery": { "type": "string" }, "thumbnail": { "type": "string" }, "badges": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "number" }, "reviews": { "type": "integer" } }, "required": [ "position", "title" ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "start": { "type": "integer" }, "previous_start": { "type": "integer" }, "next_start": { "type": "integer" } }, "required": [ "current_page", "start" ] } }, "required": [ "search_parameters", "shopping_results", "pagination" ] } } } }, "422": { "description": "The query, locale, location, device, pagination, or Shopping filters are invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The query, locale, location, device, pagination, or Shopping filters are invalid.", "value": { "errors": { "q": [ "The q field is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Approved proxy attempts did not return usable Shopping HTML. Failed requests are not billable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "google_shopping_upstream_unavailable": { "summary": "Google Shopping results are temporarily unavailable.", "description": "Approved proxy attempts did not return usable Shopping HTML. Failed requests are not billable.", "value": { "error": "Google Shopping results are temporarily unavailable." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/google/videos": { "get": { "operationId": "google.search.videos", "description": "Search and scrape video results from Google.", "summary": "Search Google Videos", "tags": [ "GoogleVideo" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Required", "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Location string (cannot be used with \"uule\").", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uule", "in": "query", "description": "Encoded location (cannot be used with \"location\").", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "google_domain", "in": "query", "description": "Google domain to query (e.g. google.com, google.de).", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "gl", "in": "query", "description": "Country code for geographic targeting (2 letters, e.g. de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "description": "Interface language code (2 letters, e.g. en, de).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "description": "Language restriction (e.g., lang_en for English-only results).", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "tbs", "in": "query", "description": "Advanced Google filter string (e.g. dur:l to restrict to long videos).", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "safe", "in": "query", "description": "SafeSearch: active or off.", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "nfpr", "in": "query", "description": "Set to 1 to disable automatic spelling correction, 0 to allow it.", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "filter", "in": "query", "description": "Set to 1 to omit near-duplicate results (default), 0 to keep them.", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "start", "in": "query", "description": "Pagination", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "description": "Page number (starts at 1).", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "search_information": { "type": "object", "properties": { "video_results_state": { "type": "string" }, "query_displayed": { "type": "string" }, "spelling_fix": { "type": "string" }, "showing_results_for": { "type": "string" }, "total_results": { "type": "integer" }, "time_taken_displayed": { "type": "number" } }, "required": [ "video_results_state", "query_displayed" ] }, "video_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "displayed_link": { "type": "string" }, "thumbnail": { "type": "string" }, "snippet": { "type": "string" }, "duration": { "type": "string" }, "date": { "type": "string" }, "video_link": { "type": "string" }, "rich_snippet": { "type": "array", "items": {} }, "key_moments": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "title": { "type": "string" }, "link": { "type": "string" } }, "required": [ "time", "title", "link" ] } } }, "required": [ "position", "title", "link" ] } }, "found_in_videos": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "thumbnail": { "type": "string" }, "key_moment": { "type": "object", "properties": { "time": { "type": "string" }, "title": { "type": "string" } } }, "channel": { "type": "string" } }, "required": [ "position", "link" ] } }, "short_videos": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "source": { "type": "string" }, "thumbnail": { "type": "string" }, "clip": { "type": "string" }, "link": { "type": "string" }, "extensions": { "type": "array", "items": { "type": "string" } }, "profile_name": { "type": "string" } }, "required": [ "position", "source" ] } }, "related_searches": { "type": "array", "items": { "type": "object", "properties": { "block_position": { "type": "integer" }, "query": { "type": "string" }, "link": { "type": "string" }, "scrappa_link": { "type": "string" } }, "required": [ "block_position", "query", "link", "scrappa_link" ] } }, "pagination": { "type": [ "object", "null" ], "properties": { "current": { "type": "integer" }, "next": { "type": "string" }, "previous": { "type": "string" }, "other_pages": { "type": "array", "items": {} } }, "required": [ "current" ] }, "search_parameters": { "type": "object", "properties": { "engine": { "type": "string" }, "q": { "type": "string" }, "google_domain": { "type": "string" }, "hl": { "type": "string" }, "gl": { "type": "string" }, "safe": { "type": "string" }, "start": { "type": "integer" }, "tbs": { "type": "string" }, "filter": { "type": "integer" }, "nfpr": { "type": "integer" }, "lr": { "type": "string" } }, "required": [ "engine", "q", "google_domain", "hl", "gl", "safe" ] }, "scrappa_pagination": { "type": [ "object", "null" ], "properties": { "current": { "type": "integer" }, "previous_link": { "type": "string" }, "previous": { "type": "string" }, "next_link": { "type": "string" }, "next": { "type": "string" }, "other_pages": { "type": "array", "items": {} } }, "required": [ "current" ] } }, "required": [ "search_information", "video_results", "related_searches", "pagination", "search_parameters", "scrappa_pagination" ] } } } }, "422": { "description": "The query, locale, filter, or pagination parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The query, locale, filter, or pagination parameters failed validation.", "value": { "errors": { "q": [ "The q field is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Google Videos could not be fetched after the cookie fallback path was exhausted. This is a temporary upstream availability error and the request can be retried with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Google Videos could not be fetched after the cookie fallback path was exhausted. This is a temporary upstream availability error and the request can be retried with backoff.", "value": { "error": "Google Videos upstream is temporarily unavailable.", "retryable": true, "error_code": "google_videos_upstream_unavailable", "proxy_type": "server_status", "failed_stage": "google_videos_fallback_exhausted", "server_status_id": 987 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/search": { "get": { "operationId": "idealista.search", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Market: es, it, pt, or fr. Default es.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "operation", "in": "query", "required": true, "description": "sale or rent. Room stock uses bedrooms + rent.", "schema": { "type": "string", "enum": [ "sale", "rent" ] } }, { "name": "property_type", "in": "query", "required": true, "description": "homes, newDevelopments, bedrooms, offices, premises, transfers, buildings, storageRooms, garages, vacationRentals, luxury, or lands.", "schema": { "type": "string", "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] } }, { "name": "location_id", "in": "query", "description": "Idealista location id such as 0-EU-ES-28.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "center", "in": "query", "description": "lat,lon for near-me search.", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "maxLength": 40 } }, { "name": "distance", "in": "query", "description": "Radius in meters when using center.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50000 } }, { "name": "max_items", "in": "query", "description": "Page size honored by origin, 1-5.", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "num_page", "in": "query", "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "gallery", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "microsite_short_name", "in": "query", "description": "Anonymous agency stock filter, for example clikalia.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "chalet", "in": "query", "description": "Apply-filter key. Send true on homes.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "current_occupation_type", "in": "query", "description": "free, bareOwnership, tenanted, illegallyOccupied, or viager.", "schema": { "type": [ "string", "null" ], "enum": [ "free", "bareOwnership", "tenanted", "illegallyOccupied", "viager" ] } }, { "name": "auction", "in": "query", "description": "IT only: onlyAuctions or excludeAuctions.", "schema": { "type": [ "string", "null" ], "enum": [ "onlyAuctions", "excludeAuctions" ] } }, { "name": "home_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "bank_offer", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "advertiser_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "min_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "shape", "in": "query", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/locations": { "get": { "operationId": "idealista.locations", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "mode", "in": "query", "required": true, "description": "suggest, reverse, vacational, picker, or smart.", "schema": { "type": "string", "enum": [ "suggest", "reverse", "vacational", "picker", "smart" ] } }, { "name": "prefix", "in": "query", "description": "Text for suggest, vacational, and smart.", "schema": { "type": [ "string", "null" ], "maxLength": 80 } }, { "name": "coordinates", "in": "query", "description": "lat,lon for reverse.", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "maxLength": 40 } }, { "name": "property_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] } }, { "name": "operation", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "sale", "rent" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "filter", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 80 } }, { "name": "location_id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/location": { "get": { "operationId": "idealista.location", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "location_id", "in": "query", "required": true, "description": "Idealista location id.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/shorturis": { "post": { "operationId": "idealista.shorturis", "tags": [ "Idealista" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdealistaShorturisRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/filters": { "get": { "operationId": "idealista.filters", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "operation", "in": "query", "required": true, "description": "sale or rent.", "schema": { "type": "string", "enum": [ "sale", "rent" ] } }, { "name": "property_type", "in": "query", "required": true, "description": "Live typology enum.", "schema": { "type": "string", "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] } }, { "name": "location_id", "in": "query", "required": true, "description": "Idealista location id.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "gallery", "in": "query", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/listing": { "get": { "operationId": "idealista.listing", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "ad_id", "in": "query", "required": true, "description": "Listing identifier from search.", "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "include[]", "in": "query", "description": "Optional multimedia,comment,stats,recommendation.", "schema": { "type": "array", "enum": [ "multimedia", "comment", "stats", "recommendation" ], "items": { "type": "string", "enum": [ "multimedia", "comment", "stats", "recommendation" ] } } }, { "name": "typology", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "vacationRentals" ] } }, { "name": "from_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "guests", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "max_items", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/listing/multimedia": { "get": { "operationId": "idealista.listing.multimedia", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "ad_id", "in": "query", "required": true, "description": "Listing identifier.", "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/listing/stats": { "get": { "operationId": "idealista.listing.stats", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "ad_id", "in": "query", "required": true, "description": "Listing identifier.", "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/search": { "get": { "operationId": "idealista.map.search", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "operation", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sale", "rent" ] } }, { "name": "property_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] } }, { "name": "location_id", "in": "query", "description": "Idealista location id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "center", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "maxLength": 40 } }, { "name": "distance", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50000 } }, { "name": "max_items", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "num_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "gallery", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "microsite_short_name", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "chalet", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "current_occupation_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "free", "bareOwnership", "tenanted", "illegallyOccupied", "viager" ] } }, { "name": "auction", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "onlyAuctions", "excludeAuctions" ] } }, { "name": "home_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "bank_offer", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "advertiser_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "min_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "shape", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "mode", "in": "query", "required": true, "description": "listings or pins.", "schema": { "type": "string", "enum": [ "listings", "pins" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/tiles": { "get": { "operationId": "idealista.map.tiles", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "operation", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sale", "rent" ] } }, { "name": "property_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] } }, { "name": "location_id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "center", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "maxLength": 40 } }, { "name": "distance", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50000 } }, { "name": "max_items", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "num_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "gallery", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "microsite_short_name", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "chalet", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "current_occupation_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "free", "bareOwnership", "tenanted", "illegallyOccupied", "viager" ] } }, { "name": "auction", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "onlyAuctions", "excludeAuctions" ] } }, { "name": "home_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "bank_offer", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "advertiser_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "min_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "shape", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "z", "in": "query", "required": true, "description": "Tile zoom.", "schema": { "type": "integer", "minimum": 0, "maximum": 20 } }, { "name": "x", "in": "query", "required": true, "description": "Tile X.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "y", "in": "query", "required": true, "description": "Tile Y.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/zoi": { "get": { "operationId": "idealista.map.zoi", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "slug", "in": "query", "required": true, "description": "Zone slug such as plaza-chamberi-madrid-madrid.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 120 } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/static": { "get": { "operationId": "idealista.map.static", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "location_id", "in": "query", "required": true, "description": "Idealista location id.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "aspect_ratio", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 16 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/georeach": { "get": { "operationId": "idealista.map.georeach", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "operation", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sale", "rent" ] } }, { "name": "property_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] } }, { "name": "location_id", "in": "query", "description": "Idealista location id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "center", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "maxLength": 40 } }, { "name": "distance", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50000 } }, { "name": "max_items", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "num_page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } }, { "name": "gallery", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "microsite_short_name", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } }, { "name": "chalet", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "current_occupation_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "free", "bareOwnership", "tenanted", "illegallyOccupied", "viager" ] } }, { "name": "auction", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "onlyAuctions", "excludeAuctions" ] } }, { "name": "home_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "bank_offer", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "advertiser_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "min_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_rooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "shape", "in": "query", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/multizone": { "get": { "operationId": "idealista.map.multizone", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/map/simplify": { "post": { "operationId": "idealista.map.simplify", "tags": [ "Idealista" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdealistaMapSimplifyRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/agency": { "get": { "operationId": "idealista.agency", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "microsite_short_name", "in": "query", "required": true, "description": "Agency short name, for example clikalia.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/deeplink/parse": { "get": { "operationId": "idealista.deeplink.parse", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "url", "in": "query", "required": true, "description": "Idealista search URL.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/deeplink/build": { "post": { "operationId": "idealista.deeplink.build", "tags": [ "Idealista" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdealistaDeeplinkBuildRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/vacation/calendar": { "get": { "operationId": "idealista.vacation.calendar", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "ad_id", "in": "query", "required": true, "description": "Vacation listing id.", "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "include[]", "in": "query", "description": "verify_dates and/or rent_breakdown.", "schema": { "type": "array", "enum": [ "verify_dates", "rent_breakdown" ], "items": { "type": "string", "enum": [ "verify_dates", "rent_breakdown" ] } } }, { "name": "from_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "guests", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/phones/prefixes": { "get": { "operationId": "idealista.phones.prefixes", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "language", "in": "query", "required": true, "description": "Language for labels, for example es.", "schema": { "type": "string", "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/home": { "get": { "operationId": "idealista.home", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "quality", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "high", "low" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/idealista/news": { "get": { "operationId": "idealista.news", "tags": [ "Idealista" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "es, it, pt, or fr.", "schema": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immobilienscout24/search": { "get": { "operationId": "immobilienscout24.search", "description": "Search for real estate listings on Immobilienscout24.", "summary": "Search Properties", "tags": [ "ImmobilienScout24" ], "parameters": [ { "name": "location", "in": "query", "required": true, "description": "City name, postal code, or geocode (e.g., \"Berlin\", \"10115\", \"1276003001\")", "schema": { "type": "string", "maxLength": 255 } }, { "name": "type", "in": "query", "description": "Property type: apartment-rent, apartment-buy, house-rent, house-buy (default: apartment-rent)", "schema": { "type": "string", "enum": [ "apartment-rent", "apartment-buy", "house-rent", "house-buy" ] } }, { "name": "price_min", "in": "query", "description": "Minimum price in EUR", "schema": { "type": "integer", "minimum": 0 } }, { "name": "price_max", "in": "query", "description": "Maximum price in EUR", "schema": { "type": "integer", "minimum": 0 } }, { "name": "rooms_min", "in": "query", "description": "Minimum number of rooms", "schema": { "type": "number", "minimum": 0 } }, { "name": "rooms_max", "in": "query", "description": "Maximum number of rooms", "schema": { "type": "number", "minimum": 0 } }, { "name": "size_min", "in": "query", "description": "Minimum size in m\u00b2", "schema": { "type": "integer", "minimum": 0 } }, { "name": "size_max", "in": "query", "description": "Maximum size in m\u00b2", "schema": { "type": "integer", "minimum": 0 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page (max: 50, default: 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "total_results": { "type": "integer" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "price": { "type": [ "integer", "null" ] }, "price_formatted": { "type": [ "string", "null" ] }, "rooms": { "type": [ "number", "null" ] }, "size_m2": { "type": [ "number", "null" ] }, "address": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "is_private": { "type": "boolean" }, "published": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "price", "price_formatted", "rooms", "size_m2", "address", "lat", "lon", "image_url", "url", "is_private", "published" ] } } }, "required": [ "success", "total_results", "page", "total_pages", "results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immobilienscout24/property/{id}": { "get": { "operationId": "immobilienscout24.property", "description": "Get detailed information about a specific property listing.", "summary": "Get Property Details", "tags": [ "ImmobilienScout24" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ImmobilienScout24 property ID (digits only).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "price": { "type": "object", "properties": { "cold_rent": { "type": [ "number", "null" ] }, "warm_rent": { "type": [ "number", "null" ] }, "deposit": { "type": [ "number", "null" ] }, "currency": { "type": "string" } }, "required": [ "cold_rent", "warm_rent", "deposit", "currency" ] }, "details": { "type": "object", "properties": { "rooms": { "type": [ "number", "null" ] }, "size_m2": { "type": [ "number", "null" ] }, "floor": { "type": [ "integer", "null" ] }, "available_from": { "type": [ "string", "null" ] }, "year_built": { "type": [ "integer", "null" ] } }, "required": [ "rooms", "size_m2", "floor", "available_from", "year_built" ] }, "address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] } }, "required": [ "street", "postal_code", "city", "district", "lat", "lon" ] }, "features": { "type": "array", "items": { "type": "string" } }, "energy_class": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] } }, "required": [ "url", "caption" ] } }, "agent": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] } }, "required": [ "name", "logo_url" ] }, "url": { "type": "string" }, "published_at": { "type": [ "string", "null" ] } }, "required": [ "success", "id", "title", "description", "type", "price", "details", "address", "features", "energy_class", "images", "agent", "url", "published_at" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immobilienscout24/locations": { "get": { "operationId": "immobilienscout24.locations", "description": "Search for locations to get geocodes for property search.", "summary": "Location Autocomplete", "tags": [ "ImmobilienScout24" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search term (city, district, or postal code)", "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "limit", "in": "query", "description": "Maximum results to return (default: 10)", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "geocode": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "geocode", "name", "type" ] } } }, "required": [ "success", "locations" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immobilienscout24/price-insights": { "get": { "operationId": "immobilienscout24.price-insights", "description": "Get average price per m\u00b2 for a location.", "summary": "Price Insights", "tags": [ "ImmobilienScout24" ], "parameters": [ { "name": "location", "in": "query", "required": true, "description": "City name, district name, or geocode (e.g., \"Berlin\", \"Lichtenrade\", \"1276003001\")", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "location": { "type": "string" }, "geocode": { "type": "string" }, "prices": { "type": "object", "properties": { "apartment_rent_per_m2": { "type": [ "number", "null" ] }, "apartment_buy_per_m2": { "type": [ "number", "null" ] }, "house_rent_per_m2": { "type": [ "number", "null" ] }, "house_buy_per_m2": { "type": [ "number", "null" ] } }, "required": [ "apartment_rent_per_m2", "apartment_buy_per_m2", "house_rent_per_m2", "house_buy_per_m2" ] }, "currency": { "type": "string" } }, "required": [ "success", "location", "geocode", "prices", "currency" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immowelt/search": { "get": { "operationId": "immowelt.search", "description": "Search for real estate listings on Immowelt.", "summary": "Search Properties", "tags": [ "Immowelt" ], "parameters": [ { "name": "location", "in": "query", "required": true, "description": "City name, postal code, or location ID (e.g., \"Berlin\", \"10115\", \"1\")", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "type", "in": "query", "description": "Property type: apartment-rent, apartment-buy, house-rent, house-buy (default: apartment-rent)", "schema": { "type": [ "string", "null" ], "enum": [ "apartment-rent", "apartment-buy", "house-rent", "house-buy" ] } }, { "name": "price_min", "in": "query", "description": "Minimum price in EUR", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "price_max", "in": "query", "description": "Maximum price in EUR", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "rooms_min", "in": "query", "description": "Minimum number of rooms", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "rooms_max", "in": "query", "description": "Maximum number of rooms", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "size_min", "in": "query", "description": "Minimum size in m^2", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "size_max", "in": "query", "description": "Maximum size in m^2", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page (max: 50, default: 20)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_ERROR" }, "message": { "type": "string", "const": "Search request failed" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "total_results": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "page": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "total_pages": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "online_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "price": { "type": [ "string", "null" ] }, "price_formatted": { "type": "string" }, "rooms": { "type": [ "string", "null" ] }, "rooms_max": { "type": [ "string", "null" ] }, "size_m2": { "type": [ "string", "null" ] }, "size_m2_max": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "lat": { "type": [ "string", "null" ] }, "lon": { "type": [ "string", "null" ] }, "image_url": { "type": "string" }, "url": { "type": "string" }, "is_private": { "type": "boolean" }, "published": { "type": [ "string", "null" ] } }, "required": [ "id", "online_id", "title", "price", "price_formatted", "rooms", "rooms_max", "size_m2", "size_m2_max", "address", "lat", "lon", "image_url", "url", "is_private", "published" ] } } }, "required": [ "success", "total_results", "page", "total_pages", "results" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_ERROR" }, "message": { "type": "string", "const": "Failed to fetch search results" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "RATE_LIMITED" }, "message": { "type": "string", "const": "Upstream rate limit exceeded" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_LOCATION" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immowelt/locations": { "get": { "operationId": "immowelt.locations", "description": "Search for locations to get location IDs for property search.", "summary": "Location Autocomplete", "tags": [ "Immowelt" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search term (city, district, or postal code)", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Maximum results to return (default: 10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_ERROR" }, "message": { "type": "string", "const": "Location request failed" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "geocode" ] } ] }, "postal_code": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "radius_km": { "type": "integer", "const": 10 }, "source": { "type": "string", "const": "nominatim" } }, "required": [ "id", "name", "type", "postal_code", "full_name", "lat", "lon", "radius_km", "source" ] } } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": {} } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "const": "coordinates" }, "postal_code": { "type": "null" }, "full_name": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_km": { "type": "integer", "const": 10 }, "source": { "type": "string", "const": "input" } }, "required": [ "id", "name", "type", "postal_code", "full_name", "lat", "lon", "radius_km", "source" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "locations" ] } ] } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_ERROR" }, "message": { "type": "string", "const": "Location request failed" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "geocode" ] } ] }, "postal_code": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "radius_km": { "type": "integer", "const": 10 }, "source": { "type": "string", "const": "nominatim" } }, "required": [ "id", "name", "type", "postal_code", "full_name", "lat", "lon", "radius_km", "source" ] } } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": {} } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "const": "coordinates" }, "postal_code": { "type": "null" }, "full_name": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_km": { "type": "integer", "const": 10 }, "source": { "type": "string", "const": "input" } }, "required": [ "id", "name", "type", "postal_code", "full_name", "lat", "lon", "radius_km", "source" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "success", "locations" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "locations" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immowelt/property": { "get": { "operationId": "immowelt.property", "description": "Returns cached estate payload from the last search (browser-free details flow).", "summary": "Property Details (Cached)", "tags": [ "Immowelt" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Estate id (e.g. \"estate_\") or onlineId (e.g. \"2kub55g\")", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 120 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "property": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "online_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } }, "required": [ "id", "online_id", "title" ] }, "raw": { "type": [ "array", "null" ], "items": {} } }, "required": [ "success", "property", "raw" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "NOT_FOUND" }, "message": { "type": "string", "const": "Property not found in cache. Call /api/immowelt/search first, then request details by id." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immowelt/count": { "get": { "operationId": "immowelt.count", "description": "Get the total listing count for a placeId.", "summary": "Search Count", "tags": [ "Immowelt" ], "parameters": [ { "name": "place_id", "in": "query", "required": true, "description": "Immowelt placeId (e.g. \"AD08DE8634\" for Berlin)", "schema": { "type": "string", "pattern": "^AD[0-9]{2}[A-Z]{2}[0-9]{1,6}$" } }, { "name": "distribution", "in": "query", "description": "Rent or Buy (default: Rent)", "schema": { "type": [ "string", "null" ], "enum": [ "Rent", "Buy" ] } }, { "name": "estate_type", "in": "query", "description": "Apartment or House (default: Apartment)", "schema": { "type": [ "string", "null" ], "enum": [ "Apartment", "House" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": {} }, { "type": "string" } ] } } } }, "422": { "description": "One or more query parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more query parameters failed validation.", "value": { "errors": { "place_id": [ "The place id field format is invalid." ] }, "message": "The place id field format is invalid." } } } } } }, "400": { "description": "The supplied Immowelt place_id is validly formatted but could not be resolved to a place with coordinates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The supplied Immowelt place_id is validly formatted but could not be resolved to a place with coordinates.", "value": { "error": { "code": "INVALID_LOCATION", "message": "Place ID 'AD99XX9999' not found" }, "success": false } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "429": { "description": "Immowelt or the proxy path returned a rate limit response while resolving count data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Immowelt or the proxy path returned a rate limit response while resolving count data.", "value": { "source": "immowelt", "success": false, "place_id": "AD08DE8634", "error_code": "RATE_LIMITED", "proxy_type": "vpn", "estate_type": "Apartment", "last_status": 429, "distribution": "Rent", "failed_stage": "places_data", "attempt_count": 4 } } } } } }, "502": { "description": "Immowelt returned a non-success response while resolving place data or the search count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Immowelt returned a non-success response while resolving place data or the search count.", "value": { "source": "immowelt", "success": false, "place_id": "AD08DE8634", "error_code": "UPSTREAM_ERROR", "proxy_type": "vpn", "estate_type": "Apartment", "last_status": 502, "distribution": "Rent", "failed_stage": "search_count", "attempt_count": 4 } } } } } }, "503": { "description": "The count request exhausted its endpoint-local proxy/timeout budget before a successful Immowelt response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The count request exhausted its endpoint-local proxy/timeout budget before a successful Immowelt response.", "value": { "source": "immowelt", "success": false, "place_id": "AD08DE8634", "error_code": "UPSTREAM_TIMEOUT", "proxy_type": "vpn", "estate_type": "Apartment", "distribution": "Rent", "failed_stage": "places_data", "attempt_count": 4, "last_exception": "cURL error 28: Operation timed out" } } } } } } } } }, "/immowelt/places/data": { "get": { "operationId": "immowelt.placesData", "description": "Fetch place metadata for one or more placeIds.", "summary": "Places Data", "tags": [ "Immowelt" ], "parameters": [ { "name": "place_ids[]", "in": "query", "required": true, "description": "Comma-separated placeIds (e.g. \"AD08DE8634\")", "schema": { "type": "array", "pattern": "^AD[0-9]{2}[A-Z]{2}[0-9]{1,6}$", "items": { "type": "string", "pattern": "^AD[0-9]{2}[A-Z]{2}[0-9]{1,6}$" } } }, { "name": "parent_types[]", "in": "query", "required": true, "description": "Optional comma-separated parent type keys (e.g. \"AD08,AD06\")", "schema": { "type": "array", "pattern": "^[A-Za-z0-9]+$", "items": { "type": "string", "pattern": "^[A-Za-z0-9]+$", "minLength": 2, "maxLength": 10 } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_TIMEOUT", "UPSTREAM_ERROR", "PROXY_EXHAUSTION", "RATE_LIMITED" ] }, "message": { "type": "string", "const": "Places data request failed" }, "last_exception": { "type": "string" }, "": { "type": "array", "items": {} } }, "required": [ "code", "message", "last_exception", null ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "places": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "postal_codes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "lat": { "type": [ "string", "null" ] }, "lon": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "immowelt_bff" } }, "required": [ "id", "name", "type", "postal_codes", "lat", "lon", "full_name", "source" ] } }, "raw": {} }, "required": [ "success", "places", "raw" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED", "UPSTREAM_ERROR" ] }, "message": { "type": "string", "const": "Immowelt places data failed" }, "http_status": { "type": "integer" } }, "required": [ "code", "message", "http_status" ] } }, "required": [ "success", "error" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/immowelt/places/hierarchy": { "get": { "operationId": "immowelt.placesHierarchy", "description": "Fetch parent hierarchy for a placeId.", "summary": "Places Hierarchy", "tags": [ "Immowelt" ], "parameters": [ { "name": "place_id", "in": "query", "required": true, "description": "Immowelt placeId", "schema": { "type": "string", "pattern": "^AD[0-9]{2}[A-Z]{2}[0-9]{1,6}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "UPSTREAM_ERROR" }, "message": { "type": "string", "const": "Hierarchy request failed" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "hierarchy": {} }, "required": [ "success", "hierarchy" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED", "UPSTREAM_ERROR" ] }, "message": { "type": "string", "const": "Immowelt places hierarchy failed" }, "http_status": { "type": "integer" } }, "required": [ "code", "message", "http_status" ] } }, "required": [ "success", "error" ] } ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/web-scraper/impressum": { "get": { "operationId": "web-scraper.impressum-extract", "summary": "Extract fields from an impressum page", "tags": [ "ImpressumExtraction" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "The domain to search for impressum (e.g., example.com)", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?(\\.[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?)*$", "minLength": 1, "maxLength": 253 } }, { "name": "fields", "in": "query", "required": true, "description": "Comma-separated list of field names to extract (e.g., company_name,address,email,vat_id)", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_]+(,[a-zA-Z0-9_]+)*$", "minLength": 1, "maxLength": 1000 } }, { "name": "language", "in": "query", "description": "Language code for extracted values (e.g., de, en, fr). Country names and other localizable values will be returned in this language.", "schema": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "minLength": 2, "maxLength": 5 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "additionalProperties": {} }, "error": { "type": [ "string", "null" ] }, "impressum_url": { "type": [ "string", "null" ] } }, "required": [ "success", "data", "error", "impressum_url" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/indeed/jobs": { "get": { "operationId": "indeed.jobs.search", "description": "Search for job listings on Indeed with various filters.", "summary": "Search Indeed Jobs", "tags": [ "Indeed" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Job search query", "schema": { "type": "string", "maxLength": 500 } }, { "name": "location", "in": "query", "description": "Location for job search", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "country", "in": "query", "description": "2-letter country code (e.g., US, UK, DE)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "radius", "in": "query", "description": "Search radius (0-100)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "radius_unit", "in": "query", "description": "Radius unit (MILES or KILOMETERS)", "schema": { "type": [ "string", "null" ], "enum": [ "MILES", "KILOMETERS" ] } }, { "name": "job_type", "in": "query", "description": "Job type (full_time, part_time, contract, internship, remote)", "schema": { "type": [ "string", "null" ], "enum": [ "full_time", "part_time", "contract", "internship", "remote" ] } }, { "name": "sort", "in": "query", "description": "Sort order (relevance or date)", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "date" ] } }, { "name": "limit", "in": "query", "description": "Results per page (1-100)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "description": "Interface language for results. 2-letter language code (e.g., en, de, fr, es). Default: en", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Geolocation/country for localized results. 2-letter country code (e.g., US, DE, GB, FR). Default: US", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "profile_url": { "type": [ "string", "null" ] } }, "required": [ "name", "logo", "website", "industry", "size", "description", "profile_url" ] }, "location": { "type": "object", "properties": { "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_name": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "formatted": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "is_remote": { "type": "boolean" } }, "required": [ "city", "state", "country", "country_name", "postal_code", "formatted", "latitude", "longitude", "is_remote" ] }, "salary": { "type": [ "object", "null" ], "properties": { "min": { "type": [ "integer", "null" ] }, "max": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "unit": { "type": "string" }, "is_estimated": { "type": "boolean" } }, "required": [ "min", "max", "currency", "unit", "is_estimated" ] }, "description_html": { "type": [ "string", "null" ] }, "attributes": { "type": "array", "items": { "type": "string" } }, "date_published": { "type": [ "string", "null" ] }, "apply_url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "company", "location", "salary", "description_html", "attributes", "date_published", "apply_url" ] } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "metadata": { "type": "object", "properties": { "total_results": { "type": "integer" }, "timestamp": { "type": "string" } }, "required": [ "total_results", "timestamp" ] } }, "required": [ "jobs", "pagination", "metadata" ] } }, "required": [ "success", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/user": { "get": { "operationId": "instagram.user", "description": "Retrieve an Instagram user profile including biography, bio links, and follower counts.", "summary": "Get Instagram User Profile", "tags": [ "Instagram" ], "parameters": [ { "name": "username", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^@?[a-zA-Z0-9._-]+$", "minLength": 1, "maxLength": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "username": { "type": "string" }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "username": { "type": "string" }, "full_name": { "type": [ "string", "null" ] }, "biography": { "type": [ "string", "null" ] }, "bio_links": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "link_type": { "type": "string" } }, "required": [ "title", "url", "link_type" ] } }, "external_url": { "type": [ "string", "null" ] }, "profile_pic_url": { "type": [ "string", "null" ] }, "profile_pic_url_hd": { "type": [ "string", "null" ] }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean" }, "is_business_account": { "type": "boolean" }, "is_professional_account": { "type": "boolean" }, "category_name": { "type": [ "string", "null" ] }, "follower_count": { "type": [ "integer", "null" ] }, "following_count": { "type": [ "integer", "null" ] }, "media_count": { "type": [ "integer", "null" ] }, "pronouns": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "username", "full_name", "biography", "bio_links", "external_url", "profile_pic_url", "profile_pic_url_hd", "is_verified", "is_private", "is_business_account", "is_professional_account", "category_name", "follower_count", "following_count", "media_count", "pronouns" ] } }, "required": [ "success", "found", "user" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/user/posts": { "get": { "operationId": "instagram.user.posts", "description": "Retrieve an Instagram user's posts with pagination support.", "summary": "Get Instagram User Posts", "tags": [ "Instagram" ], "parameters": [ { "name": "username", "in": "query", "required": true, "description": "Instagram username (without @)", "schema": { "type": "string", "pattern": "^@?[a-zA-Z0-9._-]+$", "minLength": 1, "maxLength": 30 } }, { "name": "max_id", "in": "query", "description": "Pagination cursor from previous response (next_max_id)", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "username": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "shortcode": { "type": [ "string", "null" ] }, "media_type": { "type": "string" }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "taken_at": { "type": [ "string", "null" ] }, "taken_at_timestamp": { "type": [ "integer", "null" ] }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "play_count": { "type": [ "integer", "null" ] }, "view_count": { "type": [ "integer", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "thumbnail_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "images": { "type": [ "array", "null" ], "items": {} }, "video_versions": { "type": [ "array", "null" ], "items": {} } }, "required": [ "type", "thumbnail_url", "video_url", "images", "video_versions" ] } }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "address", "city", "lat", "lng" ] }, "author": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "profile_pic_url": { "type": [ "string", "null" ] }, "is_verified": { "type": "boolean" } }, "required": [ "id", "username", "full_name", "profile_pic_url", "is_verified" ] }, "collaborators": { "type": "array", "items": {} }, "tagged_users": { "type": "array", "items": {} }, "is_paid_partnership": { "type": "boolean" }, "product_type": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] } }, "required": [ "id", "shortcode", "media_type", "caption", "hashtags", "taken_at", "taken_at_timestamp", "like_count", "comment_count", "play_count", "view_count", "media", "location", "author", "collaborators", "tagged_users", "is_paid_partnership", "product_type", "permalink" ] } }, "posts_count": { "type": "integer" }, "more_available": { "type": "boolean" }, "next_max_id": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "posts", "posts_count", "more_available", "next_max_id" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later.", "value": { "error": "Instagram rate limited all approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_user_posts_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/user/tagged-posts": { "get": { "operationId": "instagram.user.tagged-posts", "description": "Retrieve the public Instagram posts a user is tagged in, with pagination support.\nProvide either the username or the numeric user_id.", "summary": "Get Instagram User Tagged Posts", "tags": [ "Instagram" ], "parameters": [ { "name": "username", "in": "query", "description": "Instagram username (without @). Required when user_id is not provided.", "schema": { "type": "string", "pattern": "^@?[a-zA-Z0-9._]+$", "minLength": 1, "maxLength": 30 } }, { "name": "user_id", "in": "query", "description": "Numeric Instagram user ID. Required when username is not provided.", "schema": { "type": "string", "pattern": "^\\d+$", "maxLength": 30 } }, { "name": "max_id", "in": "query", "description": "Pagination cursor from previous response (next_max_id)", "schema": { "type": [ "string", "null" ], "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "user_id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "posts": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "posts_count": { "type": "integer" }, "more_available": { "type": "boolean" }, "next_max_id": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "posts", "posts_count", "more_available", "next_max_id" ] } } } }, "422": { "description": "Neither username nor user_id was provided, or a value has an invalid format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Neither username nor user_id was provided, or a value has an invalid format.", "value": { "errors": { "username": [ "An Instagram username or user_id is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram tagged posts upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_tagged_posts_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/user/reels": { "get": { "operationId": "instagram.user.reels", "description": "Retrieve the public Instagram reels of a user with pagination support.\nProvide either the username or the numeric user_id.", "summary": "Get Instagram User Reels", "tags": [ "Instagram" ], "parameters": [ { "name": "username", "in": "query", "description": "Instagram username (without @). Required when user_id is not provided.", "schema": { "type": "string", "pattern": "^@?[a-zA-Z0-9._]+$", "minLength": 1, "maxLength": 30 } }, { "name": "user_id", "in": "query", "description": "Numeric Instagram user ID. Required when username is not provided.", "schema": { "type": "string", "pattern": "^\\d+$", "maxLength": 30 } }, { "name": "max_id", "in": "query", "description": "Pagination cursor from previous response (next_max_id)", "schema": { "type": [ "string", "null" ], "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "user_id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "reels": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "reels_count": { "type": "integer" }, "more_available": { "type": "boolean" }, "next_max_id": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "reels", "reels_count", "more_available", "next_max_id" ] } } } }, "422": { "description": "Neither username nor user_id was provided, or a value has an invalid format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Neither username nor user_id was provided, or a value has an invalid format.", "value": { "errors": { "username": [ "An Instagram username or user_id is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram reels upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_user_reels_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/user/basic": { "get": { "operationId": "instagram.user.basic", "description": "Retrieve the basic public Instagram profile for a numeric user ID.", "summary": "Get Instagram Basic Profile", "tags": [ "Instagram" ], "parameters": [ { "name": "user_id", "in": "query", "required": true, "description": "Numeric Instagram user ID", "schema": { "type": "string", "pattern": "^\\d+$", "maxLength": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "user_id": { "type": "string" }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "profile_pic_url": { "type": [ "string", "null" ] }, "profile_pic_url_hd": { "type": [ "string", "null" ] }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean" }, "follower_count": { "type": [ "integer", "null" ] }, "following_count": { "type": [ "integer", "null" ] }, "media_count": { "type": [ "integer", "null" ] } }, "required": [ "id", "username", "full_name", "profile_pic_url", "profile_pic_url_hd", "is_verified", "is_private", "follower_count", "following_count", "media_count" ] } }, "required": [ "success", "found", "user" ] } } } }, "422": { "description": "The user_id parameter is missing or not numeric.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The user_id parameter is missing or not numeric.", "value": { "errors": { "user_id": [ "The numeric Instagram user ID is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram user info upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_user_basic_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/user/embed": { "get": { "operationId": "instagram.user.embed", "description": "Retrieve the official embeddable HTML page Instagram serves for a public profile.", "summary": "Get Instagram Profile Embed", "tags": [ "Instagram" ], "parameters": [ { "name": "username", "in": "query", "required": true, "description": "Instagram username (without @)", "schema": { "type": "string", "pattern": "^@?[a-zA-Z0-9._-]+$", "minLength": 1, "maxLength": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "username": { "type": "string" }, "embed_url": { "type": [ "string", "null" ] }, "embed_html": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "embed_url", "embed_html" ] } } } }, "422": { "description": "The username parameter is missing or not a valid Instagram username.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The username parameter is missing or not a valid Instagram username.", "value": { "errors": { "username": [ "The Instagram username is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram embed page upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_user_embed_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/hashtags/search": { "get": { "operationId": "instagram.hashtags.search", "description": "Search Instagram hashtags by keyword and get matching hashtags with their post counts.", "summary": "Search Instagram Hashtags", "tags": [ "Instagram" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keyword (e.g. nature)", "schema": { "type": "string", "pattern": "\\S", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "string" }, "hashtags": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "hashtags_count": { "type": "integer" } }, "required": [ "success", "query", "hashtags", "hashtags_count" ] } } } }, "422": { "description": "The q parameter is missing or empty.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The q parameter is missing or empty.", "value": { "errors": { "q": [ "A search keyword (q) is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram hashtag search upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_hashtag_search_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/audio/reels": { "get": { "operationId": "instagram.audio.reels", "description": "Retrieve the public Instagram reels that use a given audio track, with pagination support.", "summary": "Get Instagram Audio Reels", "tags": [ "Instagram" ], "parameters": [ { "name": "audio_id", "in": "query", "required": true, "description": "Numeric Instagram audio ID (from instagram.com/reels/audio/{audio_id}/)", "schema": { "type": "string", "pattern": "^\\d+$", "maxLength": 40 } }, { "name": "max_id", "in": "query", "description": "Pagination cursor from previous response (next_max_id)", "schema": { "type": [ "string", "null" ], "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "audio_id": { "type": "string" }, "reels": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "reels_count": { "type": "integer" }, "more_available": { "type": "boolean" }, "next_max_id": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "audio_id", "reels", "reels_count", "more_available", "next_max_id" ] } } } }, "422": { "description": "The audio_id parameter is missing or not numeric.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The audio_id parameter is missing or not numeric.", "value": { "errors": { "audio_id": [ "The Instagram audio_id is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram audio reels upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_audio_reels_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/post": { "get": { "operationId": "instagram.post", "description": "Retrieve detailed information about a specific Instagram post.\nAccepts full URL or just the shortcode.", "summary": "Get Instagram Post Details", "tags": [ "Instagram" ], "parameters": [ { "name": "url", "in": "query", "description": "Instagram post URL. Recommended format: https://www.instagram.com/username/p/ABC123/ (URLs without username may have limited success)", "schema": { "type": "string", "pattern": "^https?:\\/\\/(www\\.)?instagram\\.com\\/(?:[^\\/]+\\/)?(?:p|reel|tv)\\/[A-Za-z0-9_-]+\\/?(?:\\?.*)?$" } }, { "name": "shortcode", "in": "query", "description": "Instagram post shortcode (e.g., DUBtwxGEqz2). Use when you do not have a full URL.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "shortcode": { "type": "string" }, "data": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "shortcode": { "type": "string" }, "media_type": { "type": "string" }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "taken_at": { "type": [ "string", "null" ] }, "taken_at_timestamp": { "type": [ "integer", "null" ] }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "play_count": { "type": [ "integer", "null" ] }, "view_count": { "type": [ "integer", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "thumbnail_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "images": { "type": [ "array", "null" ], "items": {} }, "video_versions": { "type": [ "array", "null" ], "items": {} } }, "required": [ "type", "thumbnail_url", "video_url", "images", "video_versions" ] } }, "location": { "type": [ "array", "null" ], "items": {} }, "author": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "profile_pic_url": { "type": [ "string", "null" ] }, "is_verified": { "type": "boolean" } }, "required": [ "id", "username", "full_name", "profile_pic_url", "is_verified" ] }, "collaborators": { "type": "array", "items": {} }, "tagged_users": { "type": "array", "items": {} }, "is_paid_partnership": { "type": "boolean" }, "product_type": { "type": [ "string", "null" ] }, "permalink": { "type": "string" } }, "required": [ "id", "shortcode", "media_type", "caption", "hashtags", "taken_at", "taken_at_timestamp", "like_count", "comment_count", "play_count", "view_count", "media", "location", "author", "collaborators", "tagged_users", "is_paid_partnership", "product_type", "permalink" ] } }, "required": [ "success", "found", "data" ] } } } }, "422": { "description": "Provide either a valid Instagram post URL or shortcode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Provide either a valid Instagram post URL or shortcode.", "value": { "errors": { "url": [ "The Instagram post URL or shortcode is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Every bounded Instagram post strategy was unavailable. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Every bounded Instagram post strategy was unavailable. The request is retryable and does not consume credits.", "value": { "error": "Instagram post data is temporarily unavailable after all strategies were attempted.", "success": false, "retryable": true, "error_code": "instagram_post_upstream_unavailable", "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/post/comments": { "get": { "operationId": "instagram.post.comments", "description": "Retrieve the public top-level comments of an Instagram post or reel by shortcode, with pagination support.", "summary": "Get Instagram Post Comments", "tags": [ "Instagram" ], "parameters": [ { "name": "shortcode", "in": "query", "required": true, "description": "Instagram post/reel shortcode (from the /p/ or /reel/ URL)", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "minLength": 5, "maxLength": 20 } }, { "name": "max_id", "in": "query", "description": "Pagination cursor from previous response (next_max_id)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "shortcode": { "type": "string" }, "comments": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "comments_count": { "type": "integer" }, "more_available": { "type": "boolean" }, "next_max_id": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "shortcode", "comments", "comments_count", "more_available", "next_max_id" ] } } } }, "422": { "description": "The shortcode parameter is missing or invalid. The max_id cursor was rejected by Instagram. Cursors expire and are tied to the shortcode they were issued for \u2014 start again from the first page. The request does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The shortcode parameter is missing or invalid.", "value": { "errors": { "shortcode": [ "The Instagram post shortcode is required (from the /p/ or /reel/ URL)." ] }, "message": "The request validation failed" } }, "error_1": { "description": "The max_id cursor was rejected by Instagram. Cursors expire and are tied to the shortcode they were issued for \u2014 start again from the first page. The request does not consume credits.", "value": { "error": "Invalid pagination cursor (max_id)", "success": false, "retryable": false, "error_code": "instagram_post_comments_invalid_cursor", "status_code": 422 } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram post comments upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_post_comments_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/reels/trending": { "get": { "operationId": "instagram.reels.trending", "description": "Retrieve the reels currently trending on Instagram (first page; this surface does not paginate).", "summary": "Get Instagram Trending Reels", "tags": [ "Instagram" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "reels": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "reels_count": { "type": "integer" }, "more_available": { "type": "boolean" }, "next_max_id": { "type": [ "string", "null" ] } }, "required": [ "success", "reels", "reels_count", "more_available", "next_max_id" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram trending reels upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_trending_reels_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/instagram/search/popular": { "get": { "operationId": "instagram.search.popular", "description": "Explore an Instagram topic by keyword: curated popular media, related keywords, and topic description.", "summary": "Instagram Popular Search", "tags": [ "Instagram" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Topic keyword (e.g. nature, green nature)", "schema": { "type": "string", "pattern": "\\S", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "query": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "media_count": { "type": "integer" }, "related_keywords": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] } }, "required": [ "success", "found", "query", "media", "media_count", "related_keywords", "description" ] } } } }, "422": { "description": "The q parameter is missing or empty.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The q parameter is missing or empty.", "value": { "errors": { "q": [ "A topic keyword (q) is required." ] }, "message": "The request validation failed" } } } } } }, "503": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rejected or failed all bounded attempts through approved proxies. Retry the request later. The request is retryable and does not consume credits.", "value": { "error": "Instagram popular search upstream unavailable after approved proxy attempts", "success": false, "retryable": true, "error_code": "instagram_popular_search_upstream_unavailable", "status_code": 503, "upstream_status_code": 429 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/v2/instagram/user": { "get": { "operationId": "instagram.v2.user", "summary": "Get an Instagram profile using the v2 completed-lookup contract", "tags": [ "Instagram" ], "parameters": [ { "name": "username", "in": "query", "required": true, "description": "Instagram username (without @)", "schema": { "type": "string", "pattern": "^@?[a-zA-Z0-9._-]+$", "minLength": 1, "maxLength": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "const": "The debug parameter is restricted to admin users only." } }, "required": [ "error", "message" ] } } } }, "422": { "description": "The username parameter is missing or not a valid Instagram username.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The username parameter is missing or not a valid Instagram username.", "value": { "errors": { "username": [ "The Instagram username is required." ] }, "message": "The request validation failed" } } } } } }, "429": { "description": "Instagram rate limited the upstream request. Retry after the response delay when present.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram rate limited the upstream request. Retry after the response delay when present.", "value": { "error": "Rate limited (HTTP 429)", "success": false, "retryable": true, "error_code": "instagram_rate_limited", "status_code": 429 } } } } } }, "502": { "description": "Instagram returned an unavailable upstream response through the proxy layer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Instagram returned an unavailable upstream response through the proxy layer.", "value": { "error": "Instagram upstream unavailable after profile returned HTTP 500", "success": false, "retryable": true, "error_code": "instagram_upstream_unavailable", "status_code": 502 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/jameda/search": { "get": { "operationId": "jameda.search", "summary": "Search for doctors on Jameda", "tags": [ "Jameda" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (specialty or doctor name). When building URLs manually, encode special characters (\u00e4=%C3%A4, \u00f6=%C3%B6, \u00fc=%C3%BC). Libraries like URLSearchParams and http_build_query handle this automatically.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "loc", "in": "query", "description": "City or location (optional). When building URLs manually, encode special characters (\u00e4=%C3%A4, \u00f6=%C3%B6, \u00fc=%C3%BC). Libraries like URLSearchParams and http_build_query handle this automatically.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "page", "in": "query", "description": "Page number (1-500)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 } }, { "name": "per_page", "in": "query", "description": "Results per page (1-28)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 28 } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while processing the request" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch data from Jameda" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "Successful response with doctor search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "specialty": { "type": "string" }, "url": { "type": "string" }, "rating": { "type": [ "string", "null" ] }, "review_count": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "jameda_rating": { "type": [ "object", "null" ], "properties": { "rating": { "type": "string" }, "count": { "type": "string" } }, "required": [ "rating", "count" ] } }, "required": [ "name", "specialty", "url", "rating", "review_count", "address", "image_url", "jameda_rating" ] } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_results": { "type": "integer" }, "per_page": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "current_page", "total_pages", "total_results", "per_page", "has_more" ] }, "duration_ms": { "type": "number" }, "location_info": { "type": [ "object", "null" ], "properties": { "city": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "city", "location" ] } }, "required": [ "page", "pagination", "duration_ms", "location_info" ] } }, "required": [ "success", "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Search results not found on Jameda" }, "message": { "type": "string", "const": "No search results found for the given query on Jameda." }, "http_code": { "type": "integer", "const": 404 } }, "required": [ "error", "message", "http_code" ] } } } }, "422": { "description": "Validation error - Invalid query, location, page, or per_page parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/jameda/doctor-details": { "get": { "operationId": "jameda.doctor-details", "summary": "Get doctor details, reviews, and profile information", "tags": [ "Jameda" ], "parameters": [ { "name": "doctor_url", "in": "query", "required": true, "description": "Doctor URL path or full URL. Accepts: /dr-name/specialty/city, https://www.jameda.de/dr-name/specialty/city, or dr-name/specialty/city", "schema": { "type": "string", "minLength": 3, "maxLength": 500 } } ], "responses": { "500": { "description": "Server error - Service temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "200": { "description": "Successful response with doctor details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "basic_info": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "profile_badge": { "type": [ "string", "null" ] }, "specializations": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "name", "profile_badge", "specializations", "image_url", "url" ] }, "rating": { "type": "object", "properties": { "overall_score": { "type": [ "string", "null" ] }, "review_count": { "type": [ "string", "null" ] } }, "required": [ "overall_score", "review_count" ] }, "clinic": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } }, "required": [ "name" ] }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } }, "required": [ "phone", "email", "website" ] }, "address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "street", "postal_code", "city", "country" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": [ "string", "null" ] }, "longitude": { "type": [ "string", "null" ] } }, "required": [ "latitude", "longitude" ] }, "opening_hours": { "type": "object", "additionalProperties": { "type": "string" } }, "services": { "type": "array", "items": { "type": "string" } }, "insurance": { "type": "array", "items": { "type": "string" } }, "booking_ids": { "type": [ "object", "null" ], "properties": { "doctor_id": { "type": [ "string", "null" ] }, "address_id": { "type": [ "string", "null" ] } }, "required": [ "doctor_id", "address_id" ] } }, "required": [ "basic_info", "rating", "clinic", "contact", "address", "coordinates", "opening_hours", "services", "insurance", "booking_ids" ] }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "doctor_url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "url", "doctor_url", "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "meta" ] } } } }, "404": { "description": "Doctor not found on Jameda", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "http_code": { "type": "integer" } }, "required": [ "error", "message", "http_code" ] } } } }, "422": { "description": "Validation error - Invalid doctor_url parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/jameda/reviews": { "get": { "operationId": "jameda.reviews", "summary": "Get reviews for a doctor", "tags": [ "Jameda" ], "parameters": [ { "name": "doctor_url", "in": "query", "required": true, "description": "Individual doctor URL path or full URL. Also accepts /gesundheitseinrichtungen facility/provider URLs; include filters[doctor_id] in the fragment to select a specific doctor from a facility page.", "schema": { "type": "string", "minLength": 3, "maxLength": 500 } }, { "name": "page", "in": "query", "description": "Page number (1-500)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "sort", "in": "query", "description": "Sort order applied locally to available reviews", "schema": { "type": [ "string", "null" ], "enum": [ "newest", "oldest", "highest", "lowest" ] } }, { "name": "rating", "in": "query", "description": "Filter by rating (1-5), comma-separated for multiple", "schema": { "type": [ "string", "null" ], "pattern": "^[1-5](,[1-5])*$" } }, { "name": "sentiment", "in": "query", "description": "Filter facility reviews by Jameda sentiment: positive or negative", "schema": { "type": [ "string", "null" ], "enum": [ "positive", "negative" ] } }, { "name": "per_page", "in": "query", "description": "Results per page (1-100) applied locally", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "500": { "description": "Scrappa hit an unexpected internal error while processing the Jameda reviews request or parsing the reviews feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "JAMEDA_REVIEWS_INTERNAL_ERROR": { "summary": "An error occurred while processing the reviews request", "description": "Scrappa hit an unexpected internal error while processing the Jameda reviews request or parsing the reviews feed.", "value": { "error": "An error occurred while processing the reviews request", "message": "Service temporarily unavailable. Please try again." } } } } } }, "200": { "description": "Successful response with doctor reviews", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "rating": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "date": { "type": "string" }, "date_formatted": { "type": "string" }, "author": { "type": "string" }, "verification_badge": { "type": "string" }, "service": { "type": "string" }, "clinic_name": { "type": "string" }, "doctor_reply": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "string" } }, "required": [ "name", "score" ] } } }, "required": [ "id", "text", "rating", "sentiment", "date", "date_formatted", "author", "verification_badge", "service", "clinic_name", "doctor_reply", "categories" ] } }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "doctor_url": { "type": "string" }, "filters": { "type": "object", "properties": { "sort": { "type": [ "string", "null" ] }, "rating": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] } }, "required": [ "sort", "rating", "sentiment" ] }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" }, "totalReviews": { "type": "integer" }, "resultsPerPage": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "currentPage", "totalPages", "totalReviews", "resultsPerPage", "hasNextPage", "hasPreviousPage", "note" ] }, "doctor": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "specializations": { "type": "string" }, "overall_rating": { "type": "string" } }, "required": [ "name", "specializations", "overall_rating" ] }, "duration_ms": { "type": "number" } }, "required": [ "url", "doctor_url", "filters", "pagination", "doctor", "duration_ms" ] } }, "required": [ "success", "data", "meta" ] } } } }, "422": { "description": "The doctor_url parameter is missing, references an unsupported facility URL, or pagination/filter parameters are outside the accepted ranges.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "JAMEDA_REVIEWS_VALIDATION_FAILED": { "summary": "The request validation failed", "description": "The doctor_url parameter is missing, references an unsupported facility URL, or pagination/filter parameters are outside the accepted ranges.", "value": { "errors": { "doctor_url": [ "The doctor URL path is required (e.g., /dr-max-mustermann/hausarzt/berlin)" ] }, "message": "The request validation failed" } } } } } }, "404": { "description": "Jameda confirmed that the requested doctor profile path or resolved reviews feed does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "JAMEDA_REVIEWS_DOCTOR_NOT_FOUND": { "summary": "Doctor not found on Jameda", "description": "Jameda confirmed that the requested doctor profile path or resolved reviews feed does not exist.", "value": { "error": "Doctor not found on Jameda", "message": "The provided doctor URL does not exist on Jameda.", "http_code": 404 } } } } } }, "429": { "description": "Jameda rate-limited the upstream reviews feed after Scrappa retried through the configured proxy pool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "JAMEDA_REVIEWS_UPSTREAM_RATE_LIMITED": { "summary": "Failed to fetch reviews from Jameda", "description": "Jameda rate-limited the upstream reviews feed after Scrappa retried through the configured proxy pool.", "value": { "error": "Failed to fetch reviews from Jameda", "message": "Service temporarily unavailable. Please try again.", "http_code": 429 } } } } } }, "502": { "description": "The doctor profile was reachable, but Scrappa could not resolve the Jameda doctor ID required by the reviews feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "JAMEDA_REVIEWS_PROFILE_PARSE_FAILED": { "summary": "Failed to parse Jameda doctor profile", "description": "The doctor profile was reachable, but Scrappa could not resolve the Jameda doctor ID required by the reviews feed.", "value": { "error": "Failed to parse Jameda doctor profile", "message": "The doctor profile was reachable, but Scrappa could not resolve its Jameda doctor ID. Please retry later while we refresh the parser.", "http_code": 502 } } } } } }, "503": { "description": "Scrappa could not reach or resolve the Jameda profile/reviews feed through the configured proxy retry path.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "JAMEDA_REVIEWS_UPSTREAM_UNAVAILABLE": { "summary": "Failed to resolve Jameda doctor profile", "description": "Scrappa could not reach or resolve the Jameda profile/reviews feed through the configured proxy retry path.", "value": { "error": "Failed to resolve Jameda doctor profile", "message": "Jameda could not be reached while resolving the doctor profile. Please try again.", "http_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/jameda/autocomplete-location": { "get": { "operationId": "jameda.autocomplete-location", "summary": "Get location autocomplete suggestions", "tags": [ "Jameda" ], "parameters": [ { "name": "q", "in": "query", "description": "Location search query (preferred parameter). When building URLs manually, encode special characters (\u00e4=%C3%A4, \u00f6=%C3%B6, \u00fc=%C3%BC). Libraries like URLSearchParams and http_build_query handle this automatically.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "query", "in": "query", "description": "Location text to autocomplete (1-100 characters). Required unless q is supplied.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while processing the request" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch location suggestions from Jameda" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "meta": { "type": "object", "properties": { "query": { "type": "string" }, "duration_ms": { "type": "number" }, "source": { "type": "string", "enum": [ "homepage_cache", "homepage_fallback", "jameda_elements" ] } }, "required": [ "query", "duration_ms", "source" ] } }, "required": [ "success", "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/jameda/autocomplete-service": { "get": { "operationId": "jameda.autocomplete-service", "summary": "Get service autocomplete suggestions", "tags": [ "Jameda" ], "parameters": [ { "name": "q", "in": "query", "description": "Service or specialty search query (max 100 characters, preferred parameter). When building URLs manually, encode special characters (\u00e4=%C3%A4, \u00f6=%C3%B6, \u00fc=%C3%BC). Libraries like URLSearchParams and http_build_query handle this automatically.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "query", "in": "query", "description": "Service text to autocomplete (1-100 characters). Required unless q is supplied.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while processing the request" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch service suggestions from Jameda" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." }, "debug": { "type": "object", "properties": { "url": { "type": "string" }, "query_params": { "type": "object", "properties": { "query": { "type": "string" }, "echo": { "type": "string" } }, "required": [ "query", "echo" ] }, "request_headers": { "type": "object", "properties": { "Accept": { "type": "string", "const": "application/json" }, "Accept-Language": { "type": "string", "const": "de-DE,de;q=0.9,en;q=0.7" }, "User-Agent": { "type": "string", "const": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36" }, "Origin": { "type": "string", "const": "https://www.jameda.de" }, "Referer": { "type": "string", "const": "https://www.jameda.de/" } }, "required": [ "Accept", "Accept-Language", "User-Agent", "Origin", "Referer" ] }, "response_headers": { "type": "array", "items": {} }, "response_body": { "type": "string", "description": "Log::debug(\"Successful request to {$url} via proxy {$proxy}. Status: \" . $response->status());" }, "http_status": { "type": "integer" }, "timing": { "type": "object", "properties": { "start_time": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "end_time": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "duration_ms": { "type": "integer" } }, "required": [ "start_time", "end_time", "duration_ms" ] }, "source_used": { "type": "string", "const": "none" } }, "required": [ "url", "query_params", "request_headers", "response_headers", "response_body", "http_status", "timing", "source_used" ] } }, "required": [ "error", "message", "debug" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "meta": { "type": "object", "properties": { "query": { "type": "string" }, "duration_ms": { "type": "number" }, "source": { "type": "string", "enum": [ "algolia", "homepage_cache", "homepage_fallback", "jameda_elements" ] } }, "required": [ "query", "duration_ms", "source" ] }, "debug": { "type": "object", "properties": { "url": { "type": "string" }, "query_params": { "type": "object", "properties": { "query": { "type": "string" }, "echo": { "type": "string" } }, "required": [ "query", "echo" ] }, "request_headers": { "type": "object", "properties": { "Accept": { "type": "string", "const": "application/json" }, "Accept-Language": { "type": "string", "const": "de-DE,de;q=0.9,en;q=0.7" }, "User-Agent": { "type": "string", "const": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36" }, "Origin": { "type": "string", "const": "https://www.jameda.de" }, "Referer": { "type": "string", "const": "https://www.jameda.de/" } }, "required": [ "Accept", "Accept-Language", "User-Agent", "Origin", "Referer" ] }, "response_headers": { "type": "array", "items": {} }, "response_body": { "type": "string", "description": "Log::debug(\"Successful request to {$url} via proxy {$proxy}. Status: \" . $response->status());" }, "http_status": { "type": "integer" }, "timing": { "type": "object", "properties": { "start_time": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "end_time": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "duration_ms": { "type": "number" } }, "required": [ "start_time", "end_time", "duration_ms" ] }, "source_used": { "type": "string", "enum": [ "algolia", "homepage_cache", "homepage_fallback", "jameda_elements" ] } }, "required": [ "url", "query_params", "request_headers", "response_headers", "response_body", "http_status", "timing", "source_used" ] } }, "required": [ "success", "data", "meta", "debug" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/flights/one-way": { "get": { "operationId": "kayak-flights.one-way", "tags": [ "KayakFlights" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "3-letter IATA airport or metro code.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "destination", "in": "query", "required": true, "description": "3-letter IATA airport or metro code.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "departure_date", "in": "query", "required": true, "description": "Departure date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "description": "Adult passengers, 1-9.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Child passengers, 0-8.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 } }, { "name": "infants_in_seat", "in": "query", "description": "Infants with a seat, 0-8.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 } }, { "name": "infants_on_lap", "in": "query", "description": "Lap infants, 0-8.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 } }, { "name": "cabin", "in": "query", "description": "economy, premium_economy, business, or first.", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "sort", "in": "query", "description": "best, price, or duration.", "schema": { "type": [ "string", "null" ], "enum": [ "best", "price", "duration" ] } }, { "name": "page", "in": "query", "description": "Results page, 1-20.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "currency", "in": "query", "description": "3-letter ISO currency code.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "locale", "in": "query", "description": "Language locale such as en-US.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(?:-[a-z]{2})?$" } }, { "name": "include_price_prediction", "in": "query", "description": "Include available price insight data.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "include_display_metadata", "in": "query", "description": "Include available display and offer metadata.", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "Kayak Flights is temporarily unavailable. Please retry.", "value": { "meta": { "attempts": 2, "billable": false, "retryable": true, "duration_ms": 19840 }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "Kayak Flights is temporarily unavailable. Please retry.", "http_status": 502, "failure_type": "browser_poll_unavailable" }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "No approved upstream path is currently available.", "value": { "meta": { "attempts": 0, "billable": false, "retryable": true, "duration_ms": 1 }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "Kayak Flights is temporarily unavailable. Please retry.", "http_status": 503, "failure_type": "proxy_pool_empty" }, "success": false } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/flights/round-trip": { "get": { "operationId": "kayak-flights.round-trip", "tags": [ "KayakFlights" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "3-letter IATA airport or metro code.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "destination", "in": "query", "required": true, "description": "3-letter IATA airport or metro code.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "departure_date", "in": "query", "required": true, "description": "Departure date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "description": "Adult passengers, 1-9.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Child passengers, 0-8.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 } }, { "name": "infants_in_seat", "in": "query", "description": "Infants with a seat, 0-8.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 } }, { "name": "infants_on_lap", "in": "query", "description": "Lap infants, 0-8.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 } }, { "name": "cabin", "in": "query", "description": "economy, premium_economy, business, or first.", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "sort", "in": "query", "description": "best, price, or duration.", "schema": { "type": [ "string", "null" ], "enum": [ "best", "price", "duration" ] } }, { "name": "page", "in": "query", "description": "Results page, 1-20.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "currency", "in": "query", "description": "3-letter ISO currency code.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "locale", "in": "query", "description": "Language locale such as en-US.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(?:-[a-z]{2})?$" } }, { "name": "include_price_prediction", "in": "query", "description": "Include available price insight data.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "include_display_metadata", "in": "query", "description": "Include available display and offer metadata.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "return_date", "in": "query", "required": true, "description": "Return date after departure in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "Kayak Flights is temporarily unavailable. Please retry.", "value": { "meta": { "attempts": 2, "billable": false, "retryable": true, "duration_ms": 19840 }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "Kayak Flights is temporarily unavailable. Please retry.", "http_status": 502, "failure_type": "browser_poll_unavailable" }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "No approved upstream path is currently available.", "value": { "meta": { "attempts": 0, "billable": false, "retryable": true, "duration_ms": 1 }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "Kayak Flights is temporarily unavailable. Please retry.", "http_status": 503, "failure_type": "proxy_pool_empty" }, "success": false } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/flights/airports": { "get": { "operationId": "kayak-flights.airports", "tags": [ "KayakFlights" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Airport, city, or IATA search text.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "locale", "in": "query", "description": "Language locale such as en-US.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(?:-[a-z]{2})?$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "Kayak Flights is temporarily unavailable. Please retry.", "value": { "meta": { "attempts": 2, "billable": false, "retryable": true, "duration_ms": 19840 }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "Kayak Flights is temporarily unavailable. Please retry.", "http_status": 502, "failure_type": "browser_poll_unavailable" }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "No approved upstream path is currently available.", "value": { "meta": { "attempts": 0, "billable": false, "retryable": true, "duration_ms": 1 }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "Kayak Flights is temporarily unavailable. Please retry.", "http_status": 503, "failure_type": "proxy_pool_empty" }, "success": false } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/stays/search": { "get": { "operationId": "kayak.stays.search", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "location_id", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "example": "15830" }, { "name": "location_type", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "city", "airport", "hotel" ] } }, { "name": "checkin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "checkout", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be after checkin.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-02" }, { "name": "adults", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } }, { "name": "rooms", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 8 } }, { "name": "child_ages[]", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 }, "maxItems": 8 } }, { "name": "sort", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "rank_a", "price_a", "review_a" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/stays/property": { "get": { "operationId": "kayak.stays.property", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^\\/[A-Za-z0-9,._\\/-]+$", "maxLength": 300 }, "example": "/Las-Vegas-Hotels-Park-MGM-Las-Vegas.15297.ksp" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/stays/rates": { "get": { "operationId": "kayak.stays.rates", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "hotel_id", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1 }, "example": 15297 }, { "name": "checkin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "checkout", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be after checkin.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-02" }, { "name": "adults", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } }, { "name": "rooms", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 8 } }, { "name": "child_ages[]", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 }, "maxItems": 8 } }, { "name": "price_mode", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "total", "nightly" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/stays/reviews": { "get": { "operationId": "kayak.stays.reviews", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "hotel_id", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1 }, "example": 15297 }, { "name": "sort", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "recent", "highest", "lowest" ] } }, { "name": "amount", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 10 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/stays/media": { "get": { "operationId": "kayak.stays.media", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "hotel_ids[]", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 20 }, "example": [ 15297 ] }, { "name": "width", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 50, "maximum": 2000 } }, { "name": "height", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 50, "maximum": 2000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/stays/vacation-rentals": { "get": { "operationId": "kayak.stays.vacation-rentals", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^\\/[A-Za-z0-9,._\\/-]+$", "maxLength": 300 }, "example": "/Seattle-Vacation-Rentals.7054.rental.ksp" }, { "name": "location_id", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "example": "7054" }, { "name": "location_type", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "city" ] } }, { "name": "checkin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "checkout", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be after checkin.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-02" }, { "name": "adults", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } }, { "name": "rooms", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 8 } }, { "name": "child_ages[]", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 }, "maxItems": 8 } }, { "name": "sort", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "rank_a", "price_a", "review_a" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/cars/search": { "get": { "operationId": "kayak.cars.search", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "pickup", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "example": "LAS" }, { "name": "pickup_date", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "dropoff_date", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be after pickup date.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-04" }, { "name": "pickup_hour", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 0, "maximum": 23 } }, { "name": "dropoff_hour", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 0, "maximum": 23 } }, { "name": "sort", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "rank_a", "price_a" ] } }, { "name": "price_mode", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "total", "daily" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/cars/insights": { "get": { "operationId": "kayak.cars.insights", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^\\/[A-Za-z0-9,._\\/-]+$", "maxLength": 300 }, "example": "/Los-Angeles-Car-Rentals.16078.cars.ksp" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/packages/search": { "get": { "operationId": "kayak.packages.search", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "destination", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^Z\\d+$" }, "example": "Z35107" }, { "name": "origin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "example": "ICT" }, { "name": "departure_date", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" }, { "name": "return_date", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be after departure date.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-04" }, { "name": "adults", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } }, { "name": "child_ages[]", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 17 }, "maxItems": 8 } }, { "name": "duration", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^(?:\\d+|(?:-1|\\d+),(?:-1|\\d+))$" } }, { "name": "price_mode", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "perperson", "total" ] } }, { "name": "sort", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "rank_a", "price_a" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/cruises/sailings": { "get": { "operationId": "kayak.cruises.sailings", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "min_nights", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } }, { "name": "adults", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 0, "maximum": 8 } }, { "name": "page", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "sort", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "recommended", "price", "duration", "departuredate" ] } }, { "name": "sort_order", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "product_type", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "enum": [ "ocean", "river" ] } }, { "name": "include_deals", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "boolean" } }, { "name": "include_unavailable", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/explore/destinations": { "get": { "operationId": "kayak.explore.destinations", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "example": "ICT" }, { "name": "departure_from", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after today.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-15" }, { "name": "departure_to", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after departure from.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-15" }, { "name": "return_from", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after departure from.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-16" }, { "name": "return_to", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be on or after return from.", "schema": { "type": "string", "format": "date" }, "example": "2026-11-14" }, { "name": "min_days", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } }, { "name": "max_days", "in": "query", "description": "Qualified KAYAK request parameter. Must be greater than or equal to min days.", "schema": { "type": "integer", "minimum": 1, "maximum": 180 } }, { "name": "stops", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "integer", "minimum": 0, "maximum": 3 } }, { "name": "north_east_lat", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must be greater than south west lat.", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 43.12 }, { "name": "north_east_lng", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -81.81 }, { "name": "south_west_lat", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 31.75 }, { "name": "south_west_lng", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -113.06 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/flight-tracker/airport": { "get": { "operationId": "kayak.flight-tracker.airport", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "example": "SFO" }, { "name": "date_time", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "example": "2026-08-17T09:00:00" }, { "name": "arrivals", "in": "query", "description": "Qualified KAYAK request parameter.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/direct/routes": { "get": { "operationId": "kayak.direct.routes", "tags": [ "KayakPlatform" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/best-time/flight-price-predictions": { "get": { "operationId": "kayak.best-time.flight-price-predictions", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "origin", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "example": "ICT" }, { "name": "destination", "in": "query", "required": true, "description": "Qualified KAYAK request parameter. Must differ from origin.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "example": "LAS" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/reference/airlines": { "get": { "operationId": "kayak.reference.airlines", "tags": [ "KayakPlatform" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/reference/fees": { "get": { "operationId": "kayak.reference.fees", "tags": [ "KayakPlatform" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/reference/currencies": { "get": { "operationId": "kayak.reference.currencies", "tags": [ "KayakPlatform" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/reference/countries": { "get": { "operationId": "kayak.reference.countries", "tags": [ "KayakPlatform" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/flights/route-intelligence": { "get": { "operationId": "kayak.flights.route-intelligence", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^\\/[A-Za-z0-9,._\\/-]+$", "maxLength": 300 }, "example": "/flight-routes/New-York-NYC/Las-Vegas-LAS" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kayak/guides/city": { "get": { "operationId": "kayak.guides.city", "tags": [ "KayakPlatform" ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Qualified KAYAK request parameter.", "schema": { "type": "string", "pattern": "^\\/[A-Za-z0-9,._\\/-]+$", "maxLength": 300 }, "example": "/Las-Vegas.35107.guide" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "One or more query parameters are invalid.", "value": { "message": "One or more query parameters are invalid." } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "meta": { "billable": false, "retryable": true }, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "KAYAK data is temporarily unavailable. Please retry.", "http_status": 502 }, "success": false } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "UPSTREAM_UNAVAILABLE": { "summary": "KAYAK data is temporarily unavailable. Please retry.", "value": { "message": "KAYAK data is temporarily unavailable. Please retry." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kleinanzeigen/search": { "get": { "operationId": "kleinanzeigen.search", "tags": [ "Kleinanzeigen" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-100)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "location", "in": "query", "description": "Location filter (e.g., Berlin)", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "category", "in": "query", "description": "Category filter (e.g., elektronik, auto)", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "price_min", "in": "query", "description": "Minimum price filter in EUR", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "price_max", "in": "query", "description": "Maximum price filter in EUR", "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while processing the search request" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch data from Kleinanzeigen" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "meta": { "type": "object", "properties": { "query": {}, "page": { "type": "integer" }, "location": {}, "category": {}, "results_count": { "type": "integer" }, "duration_ms": { "type": "number" } }, "required": [ "query", "page", "location", "category", "results_count", "duration_ms" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kleinanzeigen/details": { "get": { "operationId": "kleinanzeigen.details", "tags": [ "Kleinanzeigen" ], "parameters": [ { "name": "ad_id", "in": "query", "required": true, "description": "The unique identifier of the Kleinanzeigen ad", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while fetching ad details" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch ad details from Kleinanzeigen" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": {}, "title": { "type": "string" }, "price": { "type": "string" }, "price_numeric": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "location": { "type": "string" }, "view_count": { "type": "integer" }, "images": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] }, "attributes": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "shipping": { "type": "string" }, "posted_at": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "id", "title", "price", "price_numeric", "description", "location", "view_count", "images", "seller", "attributes", "shipping", "posted_at", "categories" ] }, "meta": { "type": "object", "properties": { "ad_id": {}, "duration_ms": { "type": "number" } }, "required": [ "ad_id", "duration_ms" ] } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Ad not found" }, "message": { "type": "string", "const": "The requested ad does not exist or has been removed." } }, "required": [ "error", "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kleinanzeigen/shipping-options": { "get": { "operationId": "kleinanzeigen.shipping", "tags": [ "Kleinanzeigen" ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while fetching shipping options" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to parse shipping options response" }, "message": { "type": "string", "const": "Invalid JSON response." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch shipping options from Kleinanzeigen" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "array", "null" ], "items": {} }, "meta": { "type": "array", "items": {} } }, "required": [ "success", "data", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "meta": { "type": "array", "items": {} } }, "required": [ "success", "data", "meta" ] }, { "type": "string" } ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kununu/industries": { "get": { "operationId": "kununu.industries.free", "summary": "Get all available industries with their IDs", "tags": [ "Kununu" ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "An error occurred while fetching industries" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." }, "_debug": { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } }, "required": [ "error", "message", "_debug" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "id": { "type": "integer", "const": 1 }, "name": { "type": "string", "const": "Banken / Finanzdienstleistungen" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 2 }, "name": { "type": "string", "const": "Baugewerbe / Bau" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 3 }, "name": { "type": "string", "const": "Beratung / Consulting" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 4 }, "name": { "type": "string", "const": "Bildung / Forschung / Wissenschaft" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 5 }, "name": { "type": "string", "const": "Chemie" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 6 }, "name": { "type": "string", "const": "Dienstleistung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 7 }, "name": { "type": "string", "const": "Druck / Papier / Verpackung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 8 }, "name": { "type": "string", "const": "EDV / IT" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 9 }, "name": { "type": "string", "const": "Einzelhandel / Handel" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 10 }, "name": { "type": "string", "const": "Elektro" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 11 }, "name": { "type": "string", "const": "Energie / Rohstoffe / Umwelt" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 12 }, "name": { "type": "string", "const": "Fahrzeugbau / -zulieferer" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 13 }, "name": { "type": "string", "const": "Freizeit / Touristik / Gastronomie / Sport" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 14 }, "name": { "type": "string", "const": "Gesundheit / Soziales / Pflege" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 15 }, "name": { "type": "string", "const": "Gro\u00dfhandel" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 16 }, "name": { "type": "string", "const": "Immobilien" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 17 }, "name": { "type": "string", "const": "Industrie" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 18 }, "name": { "type": "string", "const": "Internet / Multimedia" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 19 }, "name": { "type": "string", "const": "Kunst / Kultur / Unterhaltung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 20 }, "name": { "type": "string", "const": "Land- / Forstwirtschaft / Fischerei" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 21 }, "name": { "type": "string", "const": "Lebensmittel" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 22 }, "name": { "type": "string", "const": "Marketing / PR / Werbung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 23 }, "name": { "type": "string", "const": "Maschinenbau / Anlagenbau" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 24 }, "name": { "type": "string", "const": "Medien / Verlage" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 25 }, "name": { "type": "string", "const": "Medizintechnik" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 26 }, "name": { "type": "string", "const": "Metall" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 27 }, "name": { "type": "string", "const": "\u00d6ffentlicher Dienst / Verb\u00e4nde / Einrichtungen" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 28 }, "name": { "type": "string", "const": "Personaldienstleistung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 29 }, "name": { "type": "string", "const": "Pharma / Biotech" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 30 }, "name": { "type": "string", "const": "Rechtsberatung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 31 }, "name": { "type": "string", "const": "Sonstige Branchen" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 32 }, "name": { "type": "string", "const": "Steuerberatung / Wirtschaftspr\u00fcfung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 33 }, "name": { "type": "string", "const": "Telekommunikation" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 34 }, "name": { "type": "string", "const": "Textil / Leder / Bekleidung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 35 }, "name": { "type": "string", "const": "Transport / Verkehr / Logistik" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 36 }, "name": { "type": "string", "const": "Versicherung" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 37 }, "name": { "type": "string", "const": "Konsumg\u00fcter / Gebrauchsg\u00fcter" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 38 }, "name": { "type": "string", "const": "Elektronik / Elektrotechnik" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 39 }, "name": { "type": "string", "const": "Feinmechanik / Optik" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 40 }, "name": { "type": "string", "const": "Erd\u00f6l / Erdgas" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 41 }, "name": { "type": "string", "const": "Baustoff" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 42 }, "name": { "type": "string", "const": "Bergbau" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 43 }, "name": { "type": "string", "const": "Luft- / Raumfahrt" } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "const": 44 }, "name": { "type": "string", "const": "Luftfahrt" } }, "required": [ "id", "name" ] } ], "minItems": 44, "maxItems": 44, "additionalItems": false }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "description": { "type": "string", "const": "All available Kununu industry categories with their IDs" } }, "required": [ "total", "description" ] }, "_debug": { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } }, "required": [ "success", "data", "meta", "_debug" ] } } } } } } }, "/kununu/search": { "get": { "operationId": "kununu.search", "summary": "Search for companies on Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "limit", "in": "query", "description": "Max results (1-100)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip (for pagination)", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "countries[]", "in": "query", "description": "Country codes filter", "schema": { "type": "array", "enum": [ "de", "at", "ch" ], "items": { "type": "string", "enum": [ "de", "at", "ch" ] } } }, { "name": "industry", "in": "query", "description": "Kununu-supported country codes (de, at, ch)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 44 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more parameters failed validation", "value": { "errors": { "query": [ "The search query is required." ], "offset": [ "The offset cannot be negative." ], "industry": [ "The industry ID cannot exceed 44." ], "countries.0": [ "Each country must be a supported Kununu country code." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Requested offset exceeds the available results", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Requested offset exceeds the available results", "value": { "meta": { "max_offset": 44, "total_pages": 5, "total_results": 45, "requested_offset": 1000 }, "error": "Page not found", "message": "Requested offset 1000 exceeds the available results. Total results available: 45" } } } } } }, "500": { "description": "Service temporarily unavailable or failed to fetch data from Kununu API", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to fetch data from Kununu API", "value": { "error": "Failed to fetch data from Kununu API", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/reviews": { "get": { "operationId": "kununu.reviews", "summary": "Get reviews for a company on Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country code of the company (e.g., \"de\", \"at\", \"ch\")", "schema": { "type": "string", "enum": [ "de", "at", "ch" ] } }, { "name": "company_slug", "in": "query", "required": true, "description": "Company slug from Kununu (e.g., \"bmw-group\", \"sap-se\")", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "company_id", "in": "query", "description": "Company ID from Kununu (UUID format). Optional; resolved from company_slug when omitted.", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "uuid", "in": "query", "description": "Alias for company_id, for chaining from the search endpoint.", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "slug", "in": "query", "description": "Alias for company_slug, for chaining from the search endpoint.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } }, { "name": "countryCode", "in": "query", "description": "Alias for country (de, at, ch).", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "review_type", "in": "query", "description": "Type of reviews: \"employees\" or \"candidates\" (default: \"employees\")", "schema": { "type": [ "string", "null" ], "enum": [ "employees", "candidates" ] } }, { "name": "sort", "in": "query", "description": "Sort order. \"newest\" and \"oldest\" order by last review activity, which is the creation date unless the review was edited later, in which case the edit date is used. \"best\" and \"worst\" order by score. Omit to use the default kununu relevance ordering. For incremental syncing, compare the updatedAt field rather than createdAt.", "schema": { "type": [ "string", "null" ], "enum": [ "worst", "best", "newest", "oldest" ] } }, { "name": "score_filters[]", "in": "query", "description": "Filter by ratings: [\"excellent\", \"good\", \"satisfactory\", \"subpar\"]", "schema": { "type": "array", "enum": [ "excellent", "good", "satisfactory", "subpar" ], "items": { "type": "string", "enum": [ "excellent", "good", "satisfactory", "subpar" ] } } }, { "name": "recommended_filters[]", "in": "query", "description": "Filter by recommendation status: [\"yes\", \"no\"]", "schema": { "type": "array", "enum": [ "yes", "no" ], "items": { "type": "string", "enum": [ "yes", "no" ] } } }, { "name": "jobstatus_filters[]", "in": "query", "description": "Filter by employment status: [\"current\", \"former\"]", "schema": { "type": "array", "enum": [ "current", "former" ], "items": { "type": "string", "enum": [ "current", "former" ] } } }, { "name": "position_filters[]", "in": "query", "description": "Filter by position: [\"employee\", \"manager\", \"apprentice\", \"student\", \"intern\", \"freelancer\", \"contractor\"]", "schema": { "type": "array", "enum": [ "employee", "manager", "apprentice", "student", "intern", "freelancer", "contractor" ], "items": { "type": "string", "enum": [ "employee", "manager", "apprentice", "student", "intern", "freelancer", "contractor" ] } } }, { "name": "department_filters[]", "in": "query", "description": "Filter by department: [\"administration\", \"sales\", \"legal\", \"operations\", \"recruiting\", \"communication\", \"product\", \"logistic\", \"it\", \"management\", \"research\", \"controlling\", \"design\", \"procurement\"]", "schema": { "type": "array", "enum": [ "administration", "sales", "legal", "operations", "recruiting", "communication", "product", "logistic", "it", "management", "research", "controlling", "design", "procurement" ], "items": { "type": "string", "enum": [ "administration", "sales", "legal", "operations", "recruiting", "communication", "product", "logistic", "it", "management", "research", "controlling", "design", "procurement" ] } } }, { "name": "response_filters[]", "in": "query", "description": "Filter by company response: [\"yes\", \"no\"]", "schema": { "type": "array", "enum": [ "yes", "no" ], "items": { "type": "string", "enum": [ "yes", "no" ] } } }, { "name": "result_filters[]", "in": "query", "description": "Filter candidate reviews by application outcome: [\"hired\", \"rejected\", \"offerDeclined\", \"deferred\"]", "schema": { "type": "array", "enum": [ "hired", "rejected", "offerDeclined", "deferred" ], "items": { "type": "string", "enum": [ "hired", "rejected", "offerDeclined", "deferred" ] } } }, { "name": "date_filters[]", "in": "query", "description": "Filter by date range: [\"24months\", \"12months\", \"6months\", \"30days\"]", "schema": { "type": "array", "enum": [ "24months", "12months", "6months", "30days" ], "items": { "type": "string", "enum": [ "24months", "12months", "6months", "30days" ] } } }, { "name": "fetch_factor_scores", "in": "query", "description": "Include detailed factor ratings in response (adds ratings array with items like {\"id\": \"workLifeBalance\", \"score\": 4.5, \"roundedScore\": 5.0, \"text\": \"Work-life balance\"})", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more parameters failed validation", "value": { "errors": { "sort": [ "The sort must be one of: worst, best, newest, oldest." ], "country": [ "The country field is required." ], "company_id": [ "The company ID must be a valid UUID." ], "review_type": [ "The review type must be either \"employees\" or \"candidates\"." ], "company_slug": [ "The company slug field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Company not found on Kununu", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Company not found on Kununu", "value": { "error": "Kununu API returned an error", "http_code": 404 } } } } } }, "500": { "description": "Service temporarily unavailable or failed to fetch reviews from Kununu API", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to fetch reviews from Kununu API", "value": { "error": "Failed to fetch reviews from Kununu API", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/review": { "get": { "operationId": "kununu.review", "summary": "Fetch one dedicated Kununu review page without paginating company reviews", "tags": [ "Kununu" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Dedicated Kununu review URL", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/(?:www\\.)?kununu\\.com\\/(?:de|at|ch)\\/[a-z0-9][a-z0-9-]*\\/bewertung\\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\/?$" } } ], "responses": { "503": { "description": "The browser service was blocked, timed out, or returned an unrecognized page. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The browser service was blocked, timed out, or returned an unrecognized page. This response is retryable and is not billed.", "value": { "meta": { "retryable": true }, "success": false } } } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "const": "active" }, "exists": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "additionalProperties": {} }, "meta": { "type": "object", "properties": { "upstream_status": { "type": "integer" }, "duration_ms": { "type": "integer" }, "checked_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "upstream_status", "duration_ms", "checked_at", "cached" ] } }, "required": [ "success", "status", "exists", "data", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "const": "deleted" }, "exists": { "type": "boolean" }, "data": { "type": "object", "properties": { "uuid": { "type": "string" }, "country": { "type": "string" }, "company_slug": { "type": "string" }, "url": { "type": "string" } }, "required": [ "uuid", "country", "company_slug", "url" ] }, "meta": { "type": "string" } }, "required": [ "success", "status", "exists", "data", "meta" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kununu/profiles": { "get": { "operationId": "kununu.profiles", "summary": "Get company profiles from Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "countries[]", "in": "query", "description": "Filter profiles by country code (de, at, ch).", "schema": { "type": "array", "enum": [ "de", "at", "ch" ], "items": { "type": "string", "enum": [ "de", "at", "ch" ] } } }, { "name": "industry", "in": "query", "description": "Industry ID filter (1-44). Use /api/kununu/industries for the list.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 44 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more parameters failed validation", "value": { "errors": { "page": [ "The page must be a positive integer." ], "industry": [ "The industry ID cannot exceed 44." ], "countries.0": [ "Each country must be a supported Kununu country code." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Requested page exceeds the available pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Requested page exceeds the available pages", "value": { "meta": { "max_page": 10, "total_pages": 10, "requested_page": 100 }, "error": "Page not found", "message": "Requested page 100 exceeds the available pages. Total pages available: 10" } } } } } }, "500": { "description": "Service temporarily unavailable or failed to fetch data from Kununu API", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to fetch data from Kununu API", "value": { "error": "Failed to fetch data from Kununu API", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/company-details": { "get": { "operationId": "kununu.company-details", "summary": "Get detailed information for a company on Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country code (de, at, ch). Required unless countryCode is supplied.", "schema": { "type": "string", "enum": [ "de", "at", "ch" ] } }, { "name": "company_slug", "in": "query", "required": true, "description": "Company slug (e.g., \"bmwgroup\", \"sap-se\")", "schema": { "type": "string", "pattern": "^[a-z0-9\\-]+$", "minLength": 1, "maxLength": 255 } }, { "name": "slug", "in": "query", "description": "Alias for company_slug, for chaining from the search endpoint.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } }, { "name": "countryCode", "in": "query", "description": "Alias for country (de, at, ch).", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more parameters failed validation", "value": { "errors": { "country": [ "The country field is required." ], "company_slug": [ "The company slug field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Company not found on Kununu", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Company not found on Kununu", "value": { "error": "Kununu returned an error", "http_code": 404 } } } } } }, "500": { "description": "Service temporarily unavailable, failed to fetch company details, or failed to parse company information", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable, failed to fetch company details, or failed to parse company information", "value": { "error": "Failed to fetch company details from Kununu", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/jobs": { "get": { "operationId": "kununu.jobs", "summary": "Search job listings on Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "query", "in": "query", "description": "Job title or keyword search (e.g., \"Software Engineer\")", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } }, { "name": "location", "in": "query", "description": "City or location name (e.g., \"Berlin\"). Plain city names are resolved automatically.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } }, { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1, ~30 results per page)", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "radius", "in": "query", "description": "Search radius in km around location. Values: 10, 20, 30, 50, 100, 200. Requires location.", "schema": { "type": [ "integer", "null" ], "enum": [ "10", "20", "30", "50", "100", "200" ] } }, { "name": "sort", "in": "query", "description": "Sort order: \"newest\" (newest first), \"kununuScore\" (by company score). Default: relevance", "schema": { "type": [ "string", "null" ], "enum": [ "newest", "kununuScore" ] } }, { "name": "is_top_company", "in": "query", "description": "Only show Top Company badge holders (true/false). Omitting or passing false shows all companies.", "schema": { "type": [ "boolean", "null" ] } }, { "name": "workplace[][]", "in": "query", "description": "Filter by workplace model: FULL_REMOTE (home office), PARTLY_REMOTE (hybrid), NON_REMOTE (on-site)", "schema": { "type": "array", "items": {} } }, { "name": "employment_types[][]", "in": "query", "description": "Filter by employment type: FULL_TIME, PART_TIME, INTERN, TEMPORARY, CONTRACTOR, SEASONAL, VOLUNTARY", "schema": { "type": "array", "items": {} } }, { "name": "career_level[][]", "in": "query", "description": "Filter by career level: 1 (student/intern), 2 (entry-level), 3 (experienced), 4 (manager), 5 (director), 6 (executive), 99 (apprentice)", "schema": { "type": "array", "items": {} } }, { "name": "kununu_score[][]", "in": "query", "description": "Filter by minimum company score range: \"4-5\", \"3-4\", \"2-3\", \"1-2\"", "schema": { "type": "array", "items": {} } }, { "name": "industry[][]", "in": "query", "description": "Filter by industry ID (1-44). See Kununu Industries endpoint for full list.", "schema": { "type": "array", "items": {} } }, { "name": "discipline[][]", "in": "query", "description": "Filter by discipline/field of activity ID (1001-1022)", "schema": { "type": "array", "items": {} } }, { "name": "benefits[][]", "in": "query", "description": "Filter by company benefits: flexWorkingHours, pensionPlan, coaching, mobilePhone, internet, healthProgram, reachability, events, discounts, parking, car, meals, dogs, daycare, cantine, stockOptions, doctor, accessibility, material, clothes, transportation", "schema": { "type": "array", "items": {} } } ], "responses": { "500": { "description": "Service temporarily unavailable or failed to fetch jobs from Kununu API", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to fetch jobs from Kununu API", "value": { "error": "Failed to fetch jobs from Kununu API", "message": "Service temporarily unavailable. Please try again." } } } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "lastPage": { "type": "integer" }, "totalJobs": { "type": "integer" } }, "required": [ "currentPage", "lastPage", "totalJobs" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "null" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "pagination", "duration_ms", "cached", "cached_at", "warnings" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "kununu/jobs" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "success", "data", "meta", "_debug" ] }, { "type": "string" }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "pagination": { "type": "string" }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "string" }, "warnings": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "pagination", "duration_ms", "cached", "cached_at", "warnings" ] }, "_debug": { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } }, "required": [ "success", "data", "meta", "_debug" ] } ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Kununu blocked the request (anti-bot protection). Try again later." }, "message": { "type": "string", "const": "Service temporarily unavailable due to bot protection. Please retry." }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "kununu/jobs" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Page not found" }, "message": { "type": "string" }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "kununu/jobs" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "One or more parameters failed validation", "value": { "errors": { "sort": [ "Sort must be one of: newest, kununuScore." ], "radius": [ "Radius must be one of: 10, 20, 30, 50, 100, 200." ], "country": [ "Country must be one of: de, at, ch." ], "location": [ "Location is required when radius is provided." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/kununu/job": { "get": { "operationId": "kununu.job", "summary": "Get a Kununu job detail page and extract the full job description", "tags": [ "Kununu" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Kununu job posting URL", "schema": { "type": "string", "format": "uri", "pattern": "^https?:\\/\\/(www\\.)?kununu\\.com\\/(job-postings\\/[^\\/]+\\/|[a-z]{2}\\/job\\/).+$" } } ], "responses": { "500": { "description": "Service temporarily unavailable or failed to process the job detail page", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or failed to process the job detail page", "value": { "error": "An error occurred while processing the request", "message": "Service temporarily unavailable. Please try again.", "success": false } } } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": {} }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "kununu/job" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "success", "data", "_debug" ] }, { "type": "string" } ] } } } }, "503": { "description": "Kununu returned anti-bot protection for the job detail page", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection for the job detail page", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "success": false } } } } } }, "422": { "description": "The url parameter must be a public Kununu job posting URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The url parameter must be a public Kununu job posting URL", "value": { "errors": { "url": [ "Please provide a valid Kununu job posting URL." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "The Kununu job posting was not found or is no longer available", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The Kununu job posting was not found or is no longer available", "value": { "error": "Kununu job detail request failed", "success": false, "http_code": 404 } } } } } } } } }, "/kununu/top-companies": { "get": { "operationId": "kununu.top-companies", "summary": "Get ranked top companies on Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "year", "in": "query", "description": "Top-company award year (e.g. 2026)", "schema": { "type": [ "integer", "null" ], "minimum": 2020, "maximum": 2100 } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "sort", "in": "query", "description": "Sort order: \"number-reviews-desc\"", "schema": { "type": [ "string", "null" ], "enum": [ "number-reviews-desc" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/salary": { "get": { "operationId": "kununu.salary", "summary": "Get salary statistics for a job title", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "job_title", "in": "query", "required": true, "description": "Job title to look up (resolved to the closest match)", "schema": { "type": "string", "minLength": 2, "maxLength": 120 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "No salary data found for the requested job title.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "No salary data found for the requested job title.", "value": { "error": "Not found", "message": "No salary data found for the requested job title." } } } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/salaries": { "get": { "operationId": "kununu.salaries", "summary": "Get the salary hub for a country", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/company-salary": { "get": { "operationId": "kununu.company-salary", "summary": "Get salary data reported for a specific company", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country code: de (Germany), at (Austria), ch (Switzerland)", "schema": { "type": "string", "enum": [ "de", "at", "ch" ] } }, { "name": "company_slug", "in": "query", "required": true, "description": "Company slug from Kununu (e.g., \"bmw-group\", \"sap-se\")", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "No salary data found for the requested company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "No salary data found for the requested company.", "value": { "error": "Not found", "message": "No salary data found for the requested company." } } } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/autocomplete": { "get": { "operationId": "kununu.autocomplete", "summary": "Get company autocomplete suggestions", "tags": [ "Kununu" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Company name search term (e.g., \"bmw\")", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Maximum number of suggestions (1-25, default: 10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 25 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/job-locations": { "get": { "operationId": "kununu.job-locations", "summary": "Resolve a free-text location to job-search location identifiers", "tags": [ "Kununu" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Location search term (e.g., \"Berlin\")", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/job-titles": { "get": { "operationId": "kununu.job-titles", "summary": "Get job title suggestions with matching companies", "tags": [ "Kununu" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Job title search term (min. 2 characters)", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/similar-jobs": { "get": { "operationId": "kununu.similar-jobs", "summary": "Get job postings similar to a given posting", "tags": [ "Kununu" ], "parameters": [ { "name": "job_id", "in": "query", "required": true, "description": "UUID of the job posting (from the jobs endpoint)", "schema": { "type": "string", "format": "uuid" } }, { "name": "country", "in": "query", "required": true, "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Must match the posting's own country.", "schema": { "type": "string", "enum": [ "de", "at", "ch" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/top-company-jobs": { "get": { "operationId": "kununu.top-company-jobs", "summary": "Get the newest job postings from kununu top companies", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "limit", "in": "query", "description": "Number of jobs to return (1-50, default: 7)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/related-job-searches": { "get": { "operationId": "kununu.related-job-searches", "summary": "Get curated related job-search links for a country", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/recommended-local": { "get": { "operationId": "kununu.recommended-local", "summary": "Get recommended employer profiles near geographic coordinates", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "latitude", "in": "query", "required": true, "description": "Latitude of the search center (e.g., 52.52)", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": true, "description": "Longitude of the search center (e.g., 13.405)", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/closest-cities": { "get": { "operationId": "kununu.closest-cities", "summary": "Get kununu city UUIDs ordered by distance from coordinates", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "latitude", "in": "query", "required": true, "description": "Latitude of the search center (e.g., 52.52)", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": true, "description": "Longitude of the search center (e.g., 13.405)", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/kununu/sitemap": { "get": { "operationId": "kununu.sitemap", "summary": "Enumerate the full kununu employer universe through the public sitemap", "tags": [ "Kununu" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "letter", "in": "query", "description": "Letter bucket: 123, a-z, ae, oe, ue. Omit for the bucket index.", "schema": { "type": [ "string", "null" ], "pattern": "^(123|[a-z]{1,2})$" } }, { "name": "page", "in": "query", "description": "Sub-page within the letter bucket (requires letter). Omit for the page count of the bucket.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "A required parameter is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A required parameter is missing or invalid", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "The requested sitemap bucket or page does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The requested sitemap bucket or page does not exist.", "value": { "error": "Not found", "message": "The requested sitemap bucket or page does not exist." } } } } } }, "503": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Kununu returned anti-bot protection. This response is retryable and is not billed.", "value": { "error": "Kununu blocked the request (anti-bot protection). Try again later.", "message": "Service temporarily unavailable due to bot protection. Please retry." } } } } } }, "500": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Service temporarily unavailable or unexpected error occurred. This response is not billed.", "value": { "error": "An error occurred while fetching data", "message": "Service temporarily unavailable. Please try again." } } } } } } } } }, "/linkedin/search": { "get": { "operationId": "linkedin.search", "description": "Search LinkedIn profiles and posts via Google.", "summary": "LinkedIn Search", "tags": [ "LinkedIn" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Required", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "num", "in": "query", "description": "Results per page (1-20, default 10).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "start", "in": "query", "description": "Starting index for pagination (0-170). Mutually exclusive with page.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 170 } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-10). Mutually exclusive with start.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "hl", "in": "query", "description": "Language", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "description": "Restrict results to a language (format: lang_xx).", "schema": { "type": [ "string", "null" ], "pattern": "^lang_[a-z]{2}$" } }, { "name": "gl", "in": "query", "description": "Geolocation", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "cr", "in": "query", "description": "Restrict results to a country (format: countryXX).", "schema": { "type": [ "string", "null" ], "pattern": "^country[A-Z]{2}$" } }, { "name": "safe", "in": "query", "description": "Safety", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "dateRestrict", "in": "query", "description": "Date filtering", "schema": { "type": [ "string", "null" ], "pattern": "^[dwmy]\\d*$" } }, { "name": "sort", "in": "query", "description": "Sort by date (date, date:r, date:d).", "schema": { "type": [ "string", "null" ], "enum": [ "date", "date:r", "date:d" ] } }, { "name": "filter", "in": "query", "description": "Duplicate-content filter: 1 to omit near-duplicate results (default), 0 to keep them.", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "rights", "in": "query", "description": "Usage rights filter (cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived).", "schema": { "type": [ "string", "null" ], "enum": [ "cc_publicdomain", "cc_attribute", "cc_sharealike", "cc_noncommercial", "cc_nonderived" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "organic_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "displayed_link": { "type": "string" }, "snippet": { "type": [ "string", "null" ] } }, "required": [ "position", "title", "link", "displayed_link", "snippet" ] } }, "search_information": { "type": "object", "properties": { "query_displayed": { "type": "string" }, "total_results": { "type": "integer" }, "time_taken": { "type": "number" } }, "required": [ "query_displayed", "total_results", "time_taken" ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "pages": { "type": "array", "items": {} } }, "required": [ "current_page", "pages" ] }, "total_results": { "type": "integer" } }, "required": [ "organic_results", "search_information", "pagination", "total_results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/linkedin/jobs/search": { "get": { "operationId": "linkedin.jobs.search", "description": "Search LinkedIn job listing pages via Google Advanced Search with an automatic LinkedIn jobs site filter.", "summary": "LinkedIn Jobs Search", "tags": [ "LinkedIn" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Required", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "num", "in": "query", "description": "Results per page (1-20, default 10).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "start", "in": "query", "description": "Starting index for pagination (0-170). Mutually exclusive with page.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 170 } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-10). Mutually exclusive with start.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "hl", "in": "query", "description": "Language", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "description": "Restrict results to a language (format: lang_xx).", "schema": { "type": [ "string", "null" ], "pattern": "^lang_[a-z]{2}$" } }, { "name": "gl", "in": "query", "description": "Geolocation", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "cr", "in": "query", "description": "Restrict results to a country (format: countryXX).", "schema": { "type": [ "string", "null" ], "pattern": "^country[A-Z]{2}$" } }, { "name": "safe", "in": "query", "description": "Safety", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "dateRestrict", "in": "query", "description": "Date filtering", "schema": { "type": [ "string", "null" ], "pattern": "^[dwmy]\\d*$" } }, { "name": "sort", "in": "query", "description": "Sort by date (date, date:r, date:d).", "schema": { "type": [ "string", "null" ], "enum": [ "date", "date:r", "date:d" ] } }, { "name": "filter", "in": "query", "description": "Duplicate-content filter: 1 to omit near-duplicate results (default), 0 to keep them.", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "rights", "in": "query", "description": "Usage rights filter (cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived).", "schema": { "type": [ "string", "null" ], "enum": [ "cc_publicdomain", "cc_attribute", "cc_sharealike", "cc_noncommercial", "cc_nonderived" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "organic_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "link": { "type": "string" }, "displayed_link": { "type": "string" }, "snippet": { "type": [ "string", "null" ] } }, "required": [ "position", "title", "link", "displayed_link", "snippet" ] } }, "search_information": { "type": "object", "properties": { "query_displayed": { "type": "string" }, "total_results": { "type": "integer" }, "time_taken": { "type": "number" } }, "required": [ "query_displayed", "total_results", "time_taken" ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "pages": { "type": "array", "items": {} } }, "required": [ "current_page", "pages" ] }, "total_results": { "type": "integer" } }, "required": [ "organic_results", "search_information", "pagination", "total_results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/linkedin/profile": { "get": { "operationId": "linkedin.profile", "description": "Scrape public LinkedIn profile data including experience, education, articles, and more.", "summary": "Get LinkedIn Profile", "tags": [ "LinkedIn" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "LinkedIn profile URL", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/(?:(?:[a-z]{2}|www)\\.)?linkedin\\.com\\/in\\/[a-zA-Z0-9_-]+\\/?(?:\\?.*)?$" } }, { "name": "use_cache", "in": "query", "description": "Whether to use cached results (default: false)", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "description": "Maximum age of cached results in seconds", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "followers": { "type": "integer" }, "connections": { "type": [ "string", "null" ] }, "about": { "type": [ "string", "null" ] }, "job_titles": { "type": "array", "items": { "type": "string" } }, "experience": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "start_date": { "type": [ "integer", "null" ] }, "end_date": { "type": [ "integer", "null" ] } }, "required": [ "company", "url", "start_date", "end_date" ] } }, "education": { "type": "array", "items": { "type": "object", "properties": { "school": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "start_date": { "type": [ "integer", "null" ] }, "end_date": { "type": [ "integer", "null" ] } }, "required": [ "school", "url", "start_date", "end_date" ] } }, "articles": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "date_published": { "type": [ "string", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "image": { "type": [ "string", "null" ] } }, "required": [ "title", "url", "date_published", "likes", "image" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "activityType": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] } }, "required": [ "title", "activityType", "link", "image" ] } }, "publications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "name", "url" ] } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "dateRange": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "contributors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] } }, "required": [ "name", "link", "image" ] } } }, "required": [ "name", "url", "dateRange", "description", "contributors" ] } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] } }, "required": [ "name", "link", "image", "text" ] } }, "similar_profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "name", "url", "location" ] } }, "skills": { "type": "array", "items": { "type": "string" } }, "cached": { "type": "boolean" }, "cached_at": { "type": [ "string", "null" ] } }, "required": [ "success", "name", "image", "location", "followers", "connections", "about", "job_titles", "experience", "education", "articles", "activity", "publications", "projects", "recommendations", "similar_profiles", "skills", "cached" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/linkedin/company": { "get": { "operationId": "linkedin.company", "description": "Scrape public LinkedIn company page data including about, employees, specialties, and posts.", "summary": "Get LinkedIn Company", "tags": [ "LinkedIn" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "LinkedIn company URL", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/(?:www\\.|[a-z]{2}\\.)?linkedin\\.com\\/company\\/(?:[\\p{L}\\p{N}._&+\\-]|%[0-9A-Fa-f]{2})+\\/?(?:\\?.*)?$" } }, { "name": "use_cache", "in": "query", "description": "Whether to use cached results (default: false)", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "description": "Maximum age of cached results in seconds", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "tagline": { "type": [ "string", "null" ] }, "about": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "company_size": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "founded": { "type": [ "string", "null" ] }, "headquarters": { "type": [ "string", "null" ] }, "followers": { "type": [ "integer", "null" ] }, "employees_on_linkedin": { "type": [ "integer", "null" ] }, "specialties": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "address", "city", "country" ] } }, "employees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] } }, "required": [ "name", "title", "url", "image" ] } }, "posts": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "date_published": { "type": [ "string", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "image": { "type": [ "string", "null" ] } }, "required": [ "title", "url", "date_published", "likes", "comments", "image" ] } }, "similar_pages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "followers": { "type": [ "string", "null" ] } }, "required": [ "name", "url", "industry", "followers" ] } }, "funding": { "type": [ "object", "null" ], "properties": { "total_raised": { "type": [ "string", "null" ] }, "rounds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "amount": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] } }, "required": [ "type", "amount", "date" ] } } }, "required": [ "total_raised", "rounds" ] }, "cached": { "type": "boolean" }, "cached_at": { "type": [ "string", "null" ] } }, "required": [ "success", "name", "logo", "tagline", "about", "website", "industry", "company_size", "company_type", "founded", "headquarters", "followers", "employees_on_linkedin", "specialties", "locations", "employees", "posts", "similar_pages", "funding", "cached" ] } } } }, "422": { "description": "The url parameter is missing or is not a valid LinkedIn company URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The url parameter is missing or is not a valid LinkedIn company URL.", "value": { "errors": { "url": [ "The URL must be a valid LinkedIn company URL." ] }, "message": "The request validation failed" } } } } } }, "404": { "description": "The company page was not found, private, or not publicly accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The company page was not found, private, or not publicly accessible.", "value": { "message": "Company page may be private or not publicly accessible", "success": false, "error_code": "company_data_not_found", "status_code": 404 } } } } } }, "503": { "description": "LinkedIn blocked access or the configured proxy/fallback workers were unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "LinkedIn blocked access or the configured proxy/fallback workers were unavailable.", "value": { "message": "Service temporarily unavailable. Please try again.", "success": false, "error_code": "service_unavailable", "status_code": 503 } } } } } }, "504": { "description": "LinkedIn did not respond within the endpoint time budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "LinkedIn did not respond within the endpoint time budget.", "value": { "message": "Request timeout - LinkedIn is responding slowly. Please try again.", "success": false, "error_code": "time_budget_exhausted", "status_code": 504 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/linkedin/post": { "get": { "operationId": "linkedin.post", "description": "Scrape public LinkedIn post/article data including content, author, engagement metrics, and comments.\nResponse format matches public documentation at https://scrappa.co/docs/linkedin-api/linkedin_post", "summary": "Get LinkedIn Post", "tags": [ "LinkedIn" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "LinkedIn post URL", "schema": { "type": "string", "format": "uri", "pattern": "^https?:\\/\\/(www\\.)?linkedin\\.com\\/(pulse\\/.+|posts\\/.*activity-.+|feed\\/update\\/urn:li:(?:activity|share):.+|activity\\/.+)$" } }, { "name": "use_cache", "in": "query", "description": "Whether to use cached results (default: false)", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "description": "Maximum age of cached results in seconds", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string" } }, "required": [ "url", "type" ] } }, "author": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "headline": { "type": [ "string", "null" ] }, "profileUrl": { "type": "string" } }, "required": [ "name", "headline", "profileUrl" ] }, "content": { "type": [ "string", "null" ] }, "postUrl": { "type": "string" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer" }, "comments": { "type": "integer" }, "reposts": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "likes", "comments", "reposts", "total" ] }, "publishedAt": { "type": [ "string", "null" ] }, "comments": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] } }, "required": [ "author", "text", "date" ] } } }, "required": [ "media", "author", "content", "postUrl", "hashtags", "engagement", "publishedAt", "comments" ] }, "cached": { "type": "boolean" }, "cached_at": { "type": "string" } }, "required": [ "post" ] }, "message": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "data", "message", "success" ] } } } }, "422": { "description": "The url parameter is missing or is not a valid LinkedIn post URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The url parameter is missing or is not a valid LinkedIn post URL.", "value": { "errors": { "url": [ "The URL must be a valid LinkedIn post URL." ] }, "message": "The request validation failed" } } } } } }, "404": { "description": "The post was not found, private, or not publicly accessible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The post was not found, private, or not publicly accessible.", "value": { "message": "Post not found or not publicly accessible", "success": false, "error_code": "linkedin_post_not_found", "status_code": 404 } } } } } }, "503": { "description": "LinkedIn blocked proxy access or the configured fallback worker was unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "LinkedIn blocked proxy access or the configured fallback worker was unavailable.", "value": { "message": "LinkedIn post scraping is temporarily unavailable. Please try again.", "success": false, "error_code": "linkedin_post_proxy_blocked", "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/linkedin/job": { "get": { "operationId": "linkedin.job", "description": "Scrape public LinkedIn job posting data including title, company, location, description, and application details.", "summary": "Get LinkedIn Job", "tags": [ "LinkedIn" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "LinkedIn job URL", "schema": { "type": "string", "format": "uri", "pattern": "^https?:\\/\\/(www\\.|[a-z]{2}\\.)?linkedin\\.com\\/jobs\\/view\\/[a-z0-9\\-]*(\\d+)\\/?$" } }, { "name": "use_cache", "in": "query", "description": "Whether to use cached results (default: false)", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "description": "Maximum age of cached results in seconds", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "job_id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "employment_type": { "type": [ "string", "null" ] }, "date_posted": { "type": [ "string", "null" ] }, "valid_through": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "apply_url": { "type": [ "string", "null" ] }, "cached": { "type": "boolean" }, "cached_at": { "type": [ "string", "null" ] } }, "required": [ "success", "job_id", "title", "company_name", "company_url", "location", "description", "employment_type", "date_posted", "valid_through", "url", "apply_url", "cached", "cached_at" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/mobile-de/v1/search": { "get": { "operationId": "mobile-de.v1.search", "tags": [ "MobileDe" ], "parameters": [ { "name": "vehicle_type", "in": "query", "description": "Vehicle type. v1 supports car.", "schema": { "type": "string", "enum": [ "car" ] } }, { "name": "offset", "in": "query", "description": "Zero-based result offset. Defaults to 0.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Listings to return, from 1 to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "name": "query", "in": "query", "description": "Optional free-text vehicle search.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, { "name": "price_min", "in": "query", "description": "Optional non-negative minimum price.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "price_max", "in": "query", "description": "Optional non-negative maximum price.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "registration_year_min", "in": "query", "description": "Optional minimum first-registration year.", "schema": { "type": [ "integer", "null" ], "minimum": 1886, "maximum": 2100 } }, { "name": "registration_year_max", "in": "query", "description": "Optional maximum first-registration year.", "schema": { "type": [ "integer", "null" ], "minimum": 1886, "maximum": 2100 } }, { "name": "mileage_min", "in": "query", "description": "Optional non-negative minimum mileage.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "mileage_max", "in": "query", "description": "Optional non-negative maximum mileage.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "fuel[]", "in": "query", "description": "Repeatable proved fuel value. Initially PETROL.", "schema": { "type": "array", "enum": [ "PETROL" ], "items": { "type": "string", "enum": [ "PETROL" ] } } }, { "name": "transmission[]", "in": "query", "description": "Repeatable proved transmission value. Initially AUTOMATIC_GEAR.", "schema": { "type": "array", "enum": [ "AUTOMATIC_GEAR" ], "items": { "type": "string", "enum": [ "AUTOMATIC_GEAR" ] } } }, { "name": "price_rating[]", "in": "query", "description": "VERY_GOOD_PRICE and/or GOOD_PRICE.", "schema": { "type": "array", "enum": [ "VERY_GOOD_PRICE", "GOOD_PRICE" ], "items": { "type": "string", "enum": [ "VERY_GOOD_PRICE", "GOOD_PRICE" ] } } }, { "name": "make_id", "in": "query", "description": "Validated marketplace make identifier.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 50 } }, { "name": "model_id", "in": "query", "description": "Validated marketplace model identifier. Requires make_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 50 } }, { "name": "sort", "in": "query", "description": "relevance, price_asc, or price_desc.", "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc" ] } }, { "name": "include[]", "in": "query", "description": "Optional facets and/or offer_cards enrichment.", "schema": { "type": "array", "enum": [ "facets", "offer_cards" ], "items": { "type": "string", "enum": [ "facets", "offer_cards" ] } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/mobile-de/v1/listing": { "get": { "operationId": "mobile-de.v1.listing", "tags": [ "MobileDe" ], "parameters": [ { "name": "listing_id", "in": "query", "required": true, "description": "Listing identifier returned by search.", "schema": { "type": "string", "pattern": "^[0-9]+$", "maxLength": 32 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/mobile-de/v1/dealer-inventory": { "get": { "operationId": "mobile-de.v1.dealer-inventory", "tags": [ "MobileDe" ], "parameters": [ { "name": "vehicle_type", "in": "query", "description": "Vehicle type. v1 supports car.", "schema": { "type": "string", "enum": [ "car" ] } }, { "name": "offset", "in": "query", "description": "Zero-based result offset.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Listings to return, from 1 to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "name": "query", "in": "query", "description": "Optional free-text vehicle search.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, { "name": "price_min", "in": "query", "description": "Optional non-negative minimum price.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "price_max", "in": "query", "description": "Optional non-negative maximum price.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "registration_year_min", "in": "query", "description": "Optional minimum first-registration year.", "schema": { "type": [ "integer", "null" ], "minimum": 1886, "maximum": 2100 } }, { "name": "registration_year_max", "in": "query", "description": "Optional maximum first-registration year.", "schema": { "type": [ "integer", "null" ], "minimum": 1886, "maximum": 2100 } }, { "name": "mileage_min", "in": "query", "description": "Optional non-negative minimum mileage.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "mileage_max", "in": "query", "description": "Optional non-negative maximum mileage.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "fuel[]", "in": "query", "description": "Repeatable proved fuel value. Initially PETROL.", "schema": { "type": "array", "enum": [ "PETROL" ], "items": { "type": "string", "enum": [ "PETROL" ] } } }, { "name": "transmission[]", "in": "query", "description": "Repeatable proved transmission value. Initially AUTOMATIC_GEAR.", "schema": { "type": "array", "enum": [ "AUTOMATIC_GEAR" ], "items": { "type": "string", "enum": [ "AUTOMATIC_GEAR" ] } } }, { "name": "price_rating[]", "in": "query", "description": "VERY_GOOD_PRICE and/or GOOD_PRICE.", "schema": { "type": "array", "enum": [ "VERY_GOOD_PRICE", "GOOD_PRICE" ], "items": { "type": "string", "enum": [ "VERY_GOOD_PRICE", "GOOD_PRICE" ] } } }, { "name": "make_id", "in": "query", "description": "Validated marketplace make identifier.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 50 } }, { "name": "model_id", "in": "query", "description": "Validated marketplace model identifier. Requires make_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 50 } }, { "name": "sort", "in": "query", "description": "relevance, price_asc, or price_desc.", "schema": { "type": "string", "enum": [ "relevance", "price_asc", "price_desc" ] } }, { "name": "dealer_id", "in": "query", "required": true, "description": "Dealer identifier returned by a listing.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 64 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/mobile-de/v1/dealer-rating": { "get": { "operationId": "mobile-de.v1.dealer-rating", "tags": [ "MobileDe" ], "parameters": [ { "name": "dealer_id", "in": "query", "required": true, "description": "Dealer identifier returned by a listing.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 64 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/mobile-de/v1/recommendations": { "get": { "operationId": "mobile-de.v1.recommendations", "tags": [ "MobileDe" ], "parameters": [ { "name": "listing_id", "in": "query", "required": true, "description": "Listing identifier returned by search.", "schema": { "type": "string", "pattern": "^[0-9]+$", "maxLength": 32 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/docs/openapi.json": { "get": { "operationId": "docs.openapi.json", "description": "Wraps the Scramble generator in error handling to gracefully handle\nfailures like database connection issues during documentation generation.", "summary": "Generate and return the OpenAPI specification", "tags": [ "OpenApi" ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Documentation generation failed" }, "message": { "type": "string", "const": "Unable to generate API documentation. Please try again later." } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/docs": { "get": { "operationId": "docs.openapi", "description": "Wraps the Scramble generator in error handling to gracefully handle\nfailures like database connection issues during documentation generation.", "summary": "Generate and return the OpenAPI specification", "tags": [ "OpenApi" ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Documentation generation failed" }, "message": { "type": "string", "const": "Unable to generate API documentation. Please try again later." } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/realestate-com-au/autocomplete": { "get": { "operationId": "realestate-com-au.autocomplete", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Autocomplete search term.", "schema": { "type": "string", "minLength": 2, "maxLength": 120 } }, { "name": "limit", "in": "query", "description": "Maximum suggestions to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "types", "in": "query", "description": "Comma-separated suggestion types, e.g. suburb,region,precinct,state,postcode,address.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z,]+$", "maxLength": 120 } }, { "name": "source", "in": "query", "description": "Client source sent to consumer-suggest, e.g. homepage-web, property-seeker, or reax-multi-intent-search-modal.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_-]+$", "maxLength": 40 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/locations": { "get": { "operationId": "realestate-com-au.locations", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Suburb, postcode, school, region, or project search term.", "schema": { "type": "string", "minLength": 2, "maxLength": 120 } }, { "name": "limit", "in": "query", "description": "Maximum suggestions to return.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/agents": { "get": { "operationId": "realestate-com-au.agents", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "url", "in": "query", "description": "Full realestate.com.au find-agent URL.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https:\\/\\/www\\.realestate\\.com\\.au\\/find-agent" } }, { "name": "location", "in": "query", "description": "Location slug or text such as sydney-nsw-2000. Required unless url is supplied.", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9,+ -]+$", "minLength": 2, "maxLength": 120 } }, { "name": "page", "in": "query", "description": "Page number for find-agent pagination.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/agent-profile": { "get": { "operationId": "realestate-com-au.agent-profile", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full realestate.com.au agent profile URL.", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/www\\.realestate\\.com\\.au\\/agent\\/" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/agency-profile": { "get": { "operationId": "realestate-com-au.agency-profile", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full realestate.com.au agency profile URL.", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/www\\.realestate\\.com\\.au\\/agency\\/" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/suburb-profile": { "get": { "operationId": "realestate-com-au.suburb-profile", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full realestate.com.au suburb or market profile URL.", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/www\\.realestate\\.com\\.au\\/(?!property-|find-agent|agent\\/|agency\\/)" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/sales-events": { "get": { "operationId": "realestate-com-au.sales-events", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "state", "in": "query", "description": "Australian state or territory code, e.g. nsw, vic, qld.", "schema": { "type": [ "string", "null" ], "enum": [ "act", "nsw", "nt", "qld", "sa", "tas", "vic", "wa" ] } }, { "name": "url", "in": "query", "description": "Full sales-events-api.realestate.com.au URL. Optional alternative to state.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https:\\/\\/sales-events-api\\.realestate\\.com\\.au\\/sales-events\\/" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/search": { "get": { "operationId": "realestate-com-au.search", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "location", "in": "query", "required": true, "description": "Location search text such as Sydney, NSW.", "schema": { "type": "string", "minLength": 2, "maxLength": 120 } }, { "name": "channel", "in": "query", "description": "Listing channel: buy, rent, or sold.", "schema": { "type": [ "string", "null" ], "enum": [ "buy", "rent", "sold" ] } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "sort", "in": "query", "description": "realestate.com.au sort type, such as new-desc or sold-date-desc.", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "min_price", "in": "query", "description": "Minimum price filter.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "description": "Maximum price filter.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "min_bedrooms", "in": "query", "description": "Minimum bedroom count.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "max_bedrooms", "in": "query", "description": "Maximum bedroom count.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "min_bathrooms", "in": "query", "description": "Minimum bathroom count.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "min_carspaces", "in": "query", "description": "Minimum parking spaces.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 } }, { "name": "property_types", "in": "query", "description": "Comma-separated realestate.com.au property type filters.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "keywords", "in": "query", "description": "Comma-separated keyword filters.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/realestate-com-au/property": { "get": { "operationId": "realestate-com-au.property", "tags": [ "RealestateComAu" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full realestate.com.au property URL.", "schema": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/www\\.realestate\\.com\\.au\\/(?:sold\\/)?property-[a-z0-9%+.-]+-\\d+(?:\\?.*)?$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/reddit/subreddit": { "get": { "operationId": "reddit.subreddit", "tags": [ "Reddit" ], "parameters": [ { "name": "subreddit", "in": "query", "required": true, "description": "Subreddit name without the r/ prefix.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]+$", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "description": "Sort order: hot, new, top or rising.", "schema": { "type": [ "string", "null" ], "enum": [ "hot", "new", "top", "rising" ] } }, { "name": "timeframe", "in": "query", "description": "Restrict to this period: hour, day, week, month, year or all.", "schema": { "type": [ "string", "null" ], "enum": [ "hour", "day", "week", "month", "year", "all" ] } }, { "name": "limit", "in": "query", "description": "Number of items to return (1-100).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "after", "in": "query", "description": "Pagination cursor from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "extraction_path", "in": "query", "description": "Which public Reddit source to read: public_json or old_reddit.", "schema": { "type": [ "string", "null" ], "enum": [ "public_json", "old_reddit" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "One or more query parameters are invalid.", "value": { "errors": { "subreddit": [ "The subreddit field is required." ] }, "message": "The subreddit field is required." } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_unavailable": { "summary": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "value": { "ok": false, "error": "reddit_unavailable", "message": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "upstream_status": 404 } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_error": { "summary": "Reddit returned an unexpected response or a response that could not be normalized.", "value": { "ok": false, "error": "reddit_upstream_error", "message": "Reddit returned an unexpected upstream response.", "retryable": true, "upstream_status": 500 } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_unavailable": { "summary": "Reddit did not return a successful response through the approved proxy pool.", "value": { "ok": false, "error": "reddit_upstream_unavailable", "message": "Reddit did not return a successful response through the approved proxy pool.", "retryable": true, "upstream_status": 403 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/reddit/post": { "get": { "operationId": "reddit.post", "tags": [ "Reddit" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Reddit post URL. Supply this or post_id.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https?:\\/\\/(www\\.)?reddit\\.com\\/r\\/[A-Za-z0-9_]+\\/comments\\/[A-Za-z0-9_]+(\\/|$)", "maxLength": 2000 } }, { "name": "post_id", "in": "query", "description": "Reddit post ID, e.g. 1a2b3c. Supply this or url.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_]+$", "minLength": 4, "maxLength": 20 } }, { "name": "subreddit", "in": "query", "description": "Subreddit the post belongs to, used together with post_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_]+$", "minLength": 2, "maxLength": 100 } }, { "name": "extraction_path", "in": "query", "description": "Which public Reddit source to read: public_json or old_reddit.", "schema": { "type": [ "string", "null" ], "enum": [ "public_json", "old_reddit" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "One or more query parameters are invalid.", "value": { "errors": { "subreddit": [ "The subreddit field is required." ] }, "message": "The subreddit field is required." } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_unavailable": { "summary": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "value": { "ok": false, "error": "reddit_unavailable", "message": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "upstream_status": 404 } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_error": { "summary": "Reddit returned an unexpected response or a response that could not be normalized.", "value": { "ok": false, "error": "reddit_upstream_error", "message": "Reddit returned an unexpected upstream response.", "retryable": true, "upstream_status": 500 } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_unavailable": { "summary": "Reddit did not return a successful response through the approved proxy pool.", "value": { "ok": false, "error": "reddit_upstream_unavailable", "message": "Reddit did not return a successful response through the approved proxy pool.", "retryable": true, "upstream_status": 403 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/reddit/comments": { "get": { "operationId": "reddit.comments", "tags": [ "Reddit" ], "parameters": [ { "name": "url", "in": "query", "description": "Full Reddit post URL. Supply this or post_id.", "schema": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https?:\\/\\/(www\\.)?reddit\\.com\\/r\\/[A-Za-z0-9_]+\\/comments\\/[A-Za-z0-9_]+(\\/|$)", "maxLength": 2000 } }, { "name": "post_id", "in": "query", "description": "Reddit post ID, e.g. 1a2b3c. Supply this or url.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_]+$", "minLength": 4, "maxLength": 20 } }, { "name": "subreddit", "in": "query", "description": "Subreddit the post belongs to, used together with post_id.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_]+$", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "description": "Comment sort order: confidence, top, new, controversial, old or qa.", "schema": { "type": [ "string", "null" ], "enum": [ "confidence", "top", "new", "controversial", "old", "qa" ] } }, { "name": "limit", "in": "query", "description": "Number of items to return (1-100).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "extraction_path", "in": "query", "description": "Which public Reddit source to read: public_json or old_reddit.", "schema": { "type": [ "string", "null" ], "enum": [ "public_json", "old_reddit" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "One or more query parameters are invalid.", "value": { "errors": { "subreddit": [ "The subreddit field is required." ] }, "message": "The subreddit field is required." } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_unavailable": { "summary": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "value": { "ok": false, "error": "reddit_unavailable", "message": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "upstream_status": 404 } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_error": { "summary": "Reddit returned an unexpected response or a response that could not be normalized.", "value": { "ok": false, "error": "reddit_upstream_error", "message": "Reddit returned an unexpected upstream response.", "retryable": true, "upstream_status": 500 } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_unavailable": { "summary": "Reddit did not return a successful response through the approved proxy pool.", "value": { "ok": false, "error": "reddit_upstream_unavailable", "message": "Reddit did not return a successful response through the approved proxy pool.", "retryable": true, "upstream_status": 403 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/reddit/search": { "get": { "operationId": "reddit.search", "tags": [ "Reddit" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query (1-500 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "subreddit", "in": "query", "description": "Restrict the search to this subreddit.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_]+$", "minLength": 2, "maxLength": 100 } }, { "name": "sort", "in": "query", "description": "Sort order: relevance, hot, top, new or comments.", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "hot", "top", "new", "comments" ] } }, { "name": "timeframe", "in": "query", "description": "Restrict to this period: hour, day, week, month, year or all.", "schema": { "type": [ "string", "null" ], "enum": [ "hour", "day", "week", "month", "year", "all" ] } }, { "name": "limit", "in": "query", "description": "Number of items to return (1-100).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "after", "in": "query", "description": "Pagination cursor from a previous response.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "extraction_path", "in": "query", "description": "Which public Reddit source to read: public_json or old_reddit.", "schema": { "type": [ "string", "null" ], "enum": [ "public_json", "old_reddit" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "One or more query parameters are invalid.", "value": { "errors": { "subreddit": [ "The subreddit field is required." ] }, "message": "The subreddit field is required." } } } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_unavailable": { "summary": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "value": { "ok": false, "error": "reddit_unavailable", "message": "Reddit returned unavailable content. The post or subreddit may be private, removed, quarantined, NSFW-gated, or blocked upstream.", "upstream_status": 404 } } } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_error": { "summary": "Reddit returned an unexpected response or a response that could not be normalized.", "value": { "ok": false, "error": "reddit_upstream_error", "message": "Reddit returned an unexpected upstream response.", "retryable": true, "upstream_status": 500 } } } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "reddit_upstream_unavailable": { "summary": "Reddit did not return a successful response through the approved proxy pool.", "value": { "ok": false, "error": "reddit_upstream_unavailable", "message": "Reddit did not return a successful response through the approved proxy pool.", "retryable": true, "upstream_status": 403 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/redfin/locations": { "get": { "operationId": "redfin.locations", "description": "Returns region IDs that can be used with the search endpoint.\nThis is the starting point for using the Redfin API.", "summary": "Search for locations (cities, ZIP codes, neighborhoods)", "tags": [ "Redfin" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "City, ZIP code, or neighborhood name", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "locations": { "type": "array", "items": {} }, "query": { "type": "string" } }, "required": [ "locations", "query" ] } }, "required": [ "data" ] } } } }, "422": { "description": "One or more Redfin request parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "The request validation failed", "description": "One or more Redfin request parameters failed validation.", "value": { "message": "The request validation failed" } } } } } }, "400": { "description": "The request contains null bytes or unsupported control characters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "INVALID_CHARACTERS": { "summary": "Invalid characters in parameter", "description": "The request contains null bytes or unsupported control characters.", "value": { "message": "Invalid characters in parameter" } } } } } }, "500": { "description": "Redfin upstream or proxy fetch attempts were exhausted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_UPSTREAM_UNAVAILABLE": { "summary": "Failed to fetch autocomplete results after multiple attempts.", "description": "Redfin upstream or proxy fetch attempts were exhausted.", "value": { "message": "Failed to fetch autocomplete results after multiple attempts." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/redfin/search": { "get": { "operationId": "redfin.search", "description": "Returns property listings for a specified region.", "summary": "Search Redfin properties by region", "tags": [ "Redfin" ], "parameters": [ { "name": "region_id", "in": "query", "required": true, "description": "Region identifier from /api/redfin/locations.", "schema": { "type": "integer" } }, { "name": "region_type", "in": "query", "required": true, "description": "Region type: 1=neighborhood, 2=ZIP, 5=county, 6=city.", "schema": { "type": "integer", "enum": [ "1", "2", "4", "5", "6" ] } }, { "name": "market", "in": "query", "required": true, "description": "Market identifier from /api/redfin/locations (e.g., seattle, socal, dc, nyc).", "schema": { "type": "string", "pattern": "^[a-z0-9]+$", "maxLength": 30 } }, { "name": "min_price", "in": "query", "description": "Minimum price filter", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "description": "Maximum price filter", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "num_beds", "in": "query", "description": "Minimum number of bedrooms", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10 } }, { "name": "num_baths", "in": "query", "description": "Minimum number of bathrooms", "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10 } }, { "name": "property_types", "in": "query", "description": "Comma-separated property types (1-8).", "schema": { "type": [ "string", "null" ], "pattern": "^([1-8](,[1-8])*)?$" } }, { "name": "status", "in": "query", "description": "Listing status: 1=active, 9=all, 130=pending, 131=active+pending.", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "9", "130", "131" ] } }, { "name": "sold_within_days", "in": "query", "description": "Include properties sold within this many days (1-365). Required for some regions like Seattle.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365 } }, { "name": "num_homes", "in": "query", "description": "Number of results per page (max 450).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 450 } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "properties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "count": { "type": "integer" }, "region_id": { "type": "integer" }, "region_type": { "type": "integer" } }, "required": [ "properties", "count", "region_id", "region_type" ] } }, "required": [ "data" ] } } } }, "422": { "description": "One or more Redfin request parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "The request validation failed", "description": "One or more Redfin request parameters failed validation.", "value": { "message": "The request validation failed" } } } } } }, "400": { "description": "The request contains null bytes or unsupported control characters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "INVALID_CHARACTERS": { "summary": "Invalid characters in parameter", "description": "The request contains null bytes or unsupported control characters.", "value": { "message": "Invalid characters in parameter" } } } } } }, "404": { "description": "Region not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_REGION_NOT_FOUND": { "summary": "Region not found", "description": "Region not found", "value": { "message": "Region not found" } } } } } }, "500": { "description": "Redfin upstream or proxy fetch attempts were exhausted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_UPSTREAM_UNAVAILABLE": { "summary": "Failed to fetch search results after multiple attempts.", "description": "Redfin upstream or proxy fetch attempts were exhausted.", "value": { "message": "Failed to fetch search results after multiple attempts." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/redfin/valuation": { "get": { "operationId": "redfin.valuation", "description": "Returns Redfin's automated valuation model (AVM) estimate for a property.", "summary": "Get home valuation estimate", "tags": [ "Redfin" ], "parameters": [ { "name": "property_id", "in": "query", "required": true, "description": "Redfin property ID (e.g., 194191988 from URL /home/194191988)", "schema": { "type": "integer" } }, { "name": "listing_id", "in": "query", "description": "Redfin listing ID (optional)", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "predictedValue": { "type": "number" }, "predictedValueLow": { "type": "number" }, "predictedValueHigh": { "type": "number" }, "lastSoldPrice": { "type": "number" }, "lastSoldDate": { "type": "string" }, "numBeds": { "type": "integer" }, "numBaths": { "type": "number" }, "sqFt": { "type": "object", "properties": { "value": { "type": "integer" } }, "required": [ "value" ] }, "lotSize": { "type": "object", "properties": { "value": { "type": "integer" } }, "required": [ "value" ] }, "yearBuilt": { "type": "integer" }, "comparables": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "price": { "type": "number" }, "beds": { "type": "integer" }, "baths": { "type": "number" }, "sqFt": { "type": "integer" } }, "required": [ "address", "price", "beds", "baths", "sqFt" ] } } }, "required": [ "predictedValue", "predictedValueLow", "predictedValueHigh", "lastSoldPrice", "lastSoldDate", "numBeds", "numBaths", "sqFt", "lotSize", "yearBuilt", "comparables" ] } }, "required": [ "data" ] } } } }, "422": { "description": "One or more Redfin request parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "The request validation failed", "description": "One or more Redfin request parameters failed validation.", "value": { "message": "The request validation failed" } } } } } }, "400": { "description": "The request contains null bytes or unsupported control characters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "INVALID_CHARACTERS": { "summary": "Invalid characters in parameter", "description": "The request contains null bytes or unsupported control characters.", "value": { "message": "Invalid characters in parameter" } } } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_PROPERTY_NOT_FOUND": { "summary": "Property not found", "description": "Property not found", "value": { "message": "Property not found" } } } } } }, "500": { "description": "Redfin upstream or proxy fetch attempts were exhausted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_UPSTREAM_UNAVAILABLE": { "summary": "Failed to fetch valuation for the property after multiple attempts.", "description": "Redfin upstream or proxy fetch attempts were exhausted.", "value": { "message": "Failed to fetch valuation for the property after multiple attempts." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/redfin/property": { "get": { "operationId": "redfin.property", "description": "Returns above-the-fold property details from Redfin.", "summary": "Get property details", "tags": [ "Redfin" ], "parameters": [ { "name": "property_id", "in": "query", "required": true, "description": "Redfin property ID (e.g., 60791456 from URL /home/60791456)", "schema": { "type": "integer" } }, { "name": "listing_id", "in": "query", "description": "Redfin listing ID from search results (optional)", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "property_id": { "type": [ "integer", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "price": { "type": [ "integer", "null" ] }, "price_label": { "type": [ "string", "null" ] }, "beds": { "type": [ "integer", "null" ] }, "baths": { "type": [ "number", "null" ] }, "sqft": { "type": [ "integer", "null" ] }, "lot_size": { "type": [ "integer", "null" ] }, "year_built": { "type": [ "integer", "null" ] }, "property_type": { "type": [ "integer", "null" ] }, "status": { "type": [ "integer", "null" ] }, "status_label": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "url": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": {} }, "description": { "type": [ "string", "null" ] } }, "required": [ "property_id", "address", "city", "state", "zip", "country", "price", "price_label", "beds", "baths", "sqft", "lot_size", "year_built", "property_type", "status", "status_label", "latitude", "longitude", "url", "photos", "description" ] } }, "required": [ "data" ] } } } }, "422": { "description": "One or more Redfin request parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "VALIDATION_ERROR": { "summary": "The request validation failed", "description": "One or more Redfin request parameters failed validation.", "value": { "message": "The request validation failed" } } } } } }, "400": { "description": "The request contains null bytes or unsupported control characters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "INVALID_CHARACTERS": { "summary": "Invalid characters in parameter", "description": "The request contains null bytes or unsupported control characters.", "value": { "message": "Invalid characters in parameter" } } } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_PROPERTY_NOT_FOUND": { "summary": "Property not found", "description": "Property not found", "value": { "message": "Property not found" } } } } } }, "500": { "description": "Redfin upstream or proxy fetch attempts were exhausted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "REDFIN_UPSTREAM_UNAVAILABLE": { "summary": "Failed to fetch property details after multiple attempts.", "description": "Redfin upstream or proxy fetch attempts were exhausted.", "value": { "message": "Failed to fetch property details after multiple attempts." } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/rentalia/search": { "get": { "operationId": "rentalia.search", "tags": [ "Rentalia" ], "parameters": [ { "name": "lang", "in": "query", "description": "Response language. Default es.", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "data", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 4000 } }, { "name": "gid", "in": "query", "description": "Rentalia region id from /api/rentalia/locations.", "schema": { "type": [ "string", "null" ] } }, { "name": "glevel", "in": "query", "description": "Region geolevel.", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "zid", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "page", "in": "query", "description": "1-based page.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "date_from", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "capmin", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "minrooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "ptype", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "lat", "in": "query", "schema": { "type": [ "number", "null" ] } }, { "name": "lon", "in": "query", "schema": { "type": [ "number", "null" ] } }, { "name": "radius", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "chars", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "beach", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "rural", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "ski", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "nb", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "nr", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "ns", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "at_flat", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "at_house", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "at_villa", "in": "query", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/rentalia/geo-search": { "get": { "operationId": "rentalia.geo-search", "tags": [ "Rentalia" ], "parameters": [ { "name": "lang", "in": "query", "description": "Response language, default es.", "schema": { "type": [ "string", "null" ], "maxLength": 8 } }, { "name": "data", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 4000 } }, { "name": "gid", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "glevel", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "zid", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "date_from", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "capmin", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "minrooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "ptype", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 40 } }, { "name": "lat", "in": "query", "description": "Search latitude.", "schema": { "type": [ "number", "null" ] } }, { "name": "lon", "in": "query", "description": "Search longitude.", "schema": { "type": [ "number", "null" ] } }, { "name": "radius", "in": "query", "description": "Radius in meters.", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "chars", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "beach", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "rural", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "ski", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "nb", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "nr", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "ns", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "at_flat", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "at_house", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "at_villa", "in": "query", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/rentalia/house": { "get": { "operationId": "rentalia.house", "tags": [ "Rentalia" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Rentalia house id, for example 978257.", "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "lang", "in": "query", "description": "Response language, default es.", "schema": { "type": [ "string", "null" ], "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/rentalia/locations": { "get": { "operationId": "rentalia.locations", "tags": [ "Rentalia" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Location text, for example Madrid.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "lang", "in": "query", "description": "Response language, default es.", "schema": { "type": [ "string", "null" ], "maxLength": 8 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/rentalia/price": { "get": { "operationId": "rentalia.price", "tags": [ "Rentalia" ], "parameters": [ { "name": "rental_unit_id", "in": "query", "required": true, "description": "Unit identifier from house detail.", "schema": { "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "check_in_date", "in": "query", "required": true, "description": "YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "check_out_date", "in": "query", "required": true, "description": "YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "capacity", "in": "query", "required": true, "description": "Guest count.", "schema": { "type": "integer", "minimum": 1, "maximum": 30 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/domain/overview": { "get": { "operationId": "semrush.domain.overview", "tags": [ "Semrush" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Root domain or subdomain to analyze", "schema": { "type": "string", "pattern": "^(?=.{1,253}$)[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$", "maxLength": 253 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/domain/competitors": { "get": { "operationId": "semrush.domain.competitors", "tags": [ "Semrush" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Root domain or subdomain to analyze", "schema": { "type": "string", "pattern": "^(?=.{1,253}$)[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$", "maxLength": 253 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/website/traffic": { "get": { "operationId": "semrush.website.traffic", "tags": [ "Semrush" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Root domain or subdomain to analyze", "schema": { "type": "string", "pattern": "^(?=.{1,253}$)[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$", "maxLength": 253 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/suggest": { "get": { "operationId": "semrush.suggest", "tags": [ "Semrush" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Partial keyword or domain to autocomplete", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/sensor/ranks": { "get": { "operationId": "semrush.sensor.ranks", "tags": [ "Semrush" ], "parameters": [ { "name": "db", "in": "query", "description": "Sensor database, e.g. US or MOBILE-US (see facets endpoint)", "schema": { "type": [ "string", "null" ], "enum": [ "AU", "CN", "DE", "ES", "FR", "IT", "JP", "UK", "US", "MOBILE-AU", "MOBILE-DE", "MOBILE-ES", "MOBILE-FR", "MOBILE-IT", "MOBILE-JP", "MOBILE-UK", "MOBILE-US" ] } }, { "name": "category", "in": "query", "description": "Sensor category id, 1-25 (see facets endpoint)", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25" ] } }, { "name": "date", "in": "query", "description": "Day in YYYY-MM-DD format (rolling 31-day window)", "schema": { "type": [ "string", "null" ], "format": "date" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/sensor/serp-features": { "get": { "operationId": "semrush.sensor.serp-features", "tags": [ "Semrush" ], "parameters": [ { "name": "db", "in": "query", "required": true, "description": "Sensor database, e.g. US or MOBILE-US (see facets endpoint)", "schema": { "type": "string", "enum": [ "AU", "CN", "DE", "ES", "FR", "IT", "JP", "UK", "US", "MOBILE-AU", "MOBILE-DE", "MOBILE-ES", "MOBILE-FR", "MOBILE-IT", "MOBILE-JP", "MOBILE-UK", "MOBILE-US" ] } }, { "name": "category", "in": "query", "required": true, "description": "Sensor category id, 1-25 (see facets endpoint)", "schema": { "type": "integer", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25" ] } }, { "name": "date", "in": "query", "required": true, "description": "Day in YYYY-MM-DD format (rolling 31-day window)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/sensor/movers": { "get": { "operationId": "semrush.sensor.movers", "tags": [ "Semrush" ], "parameters": [ { "name": "db", "in": "query", "required": true, "description": "Sensor database, e.g. US or MOBILE-US (see facets endpoint)", "schema": { "type": "string", "enum": [ "AU", "CN", "DE", "ES", "FR", "IT", "JP", "UK", "US", "MOBILE-AU", "MOBILE-DE", "MOBILE-ES", "MOBILE-FR", "MOBILE-IT", "MOBILE-JP", "MOBILE-UK", "MOBILE-US" ] } }, { "name": "category", "in": "query", "required": true, "description": "Sensor category id, 1-25 (see facets endpoint)", "schema": { "type": "integer", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25" ] } }, { "name": "date", "in": "query", "required": true, "description": "Day in YYYY-MM-DD format (rolling 31-day window)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/trending": { "get": { "operationId": "semrush.trending", "tags": [ "Semrush" ], "parameters": [ { "name": "country", "in": "query", "description": "Trending country code, e.g. us, de, global (default: us; see facets endpoint)", "schema": { "type": [ "string", "null" ], "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "aq", "ar", "as", "at", "au", "aw", "ax", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bl", "bm", "bn", "bo", "bq", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm", "cn", "co", "cr", "cv", "cw", "cx", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "eh", "er", "es", "et", "fi", "fj", "fk", "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gs", "gt", "gu", "gw", "gy", "hk", "hm", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in", "io", "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "ki", "km", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li", "lk", "lr", "ls", "lt", "lu", "lv", "ma", "mc", "md", "me", "mf", "mg", "mh", "mk", "ml", "mn", "mo", "mp", "mq", "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "nf", "ng", "ni", "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pm", "pr", "ps", "pt", "pw", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh", "si", "sj", "sk", "sl", "sm", "sn", "so", "sr", "ss", "st", "sv", "sx", "sz", "tc", "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr", "tt", "tv", "tw", "tz", "ua", "ug", "us", "uy", "uz", "va", "vc", "ve", "vg", "vi", "vn", "vu", "wf", "ws", "global", "ye", "yt", "za", "zm", "zw" ] } }, { "name": "category", "in": "query", "description": "Trending category slug, e.g. all, arts_and_entertainment (default: all; see facets endpoint)", "schema": { "type": [ "string", "null" ], "enum": [ "accounting-and-auditing", "adult", "advertising-and-marketing", "aerospace-and-defense", "agriculture", "airlines", "apparel-and-fashion", "architecture", "automotive", "banking", "beauty-and-cosmetics", "biotech", "ceramics-and-pottery", "chemicals", "civil-engineering", "comics-and-animation", "computer-and-video-games", "computer-hardware", "computers-and-electronics", "computer-software-and-development", "construction-and-maintenance", "consulting", "consumer-electronics", "crafts", "customer-services", "design", "distance-learning", "ecology-and-environment", "education", "entertainment", "equipment-and-supplies", "events-services", "facilities-services", "farms-and-ranches", "finance", "fishery", "food-and-beverages", "foreign-language", "furniture", "gambling", "government", "graphic-design", "healthcare", "hospitality", "human-resources", "import-and-export", "information-technology", "insurance", "investment", "jewelry-and-luxury-products", "legal", "libraries", "machinery", "mail-and-package-delivery", "manufacturing", "maritime", "market-research", "mass-media", "medical-devices-and-equipment", "mental-health", "metals-and-mining", "military", "museums", "music", "nanotechnology", "newspapers", "nonprofit-organizations", "oil-and-gas", "online-services", "outsourcing", "packaging-and-containers", "performing-arts", "pharmaceuticals", "photography", "plastics-and-polymers", "political-organizations", "printing", "public-policy", "public-relations", "public-safety", "public-utility", "publishing", "real-estate", "recreational-facilities", "recruitment-and-staffing", "reference", "religion-and-belief", "renewable-energy", "restaurants", "retail", "science", "security-products-and-services", "social-and-charitable-organizations", "sporting-goods", "sports", "telecom", "textiles-and-nonwovens", "tobacco", "training-and-certification", "transportation-and-logistics", "travel-and-tourism", "tv-and-movies", "venture-capital", "veterinary", "visual-art", "warehousing", "wellness", "wholesalers-and-liquidators", "wine-and-spirits", "writing-and-editing-services", "all" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/facets": { "get": { "operationId": "semrush.facets", "tags": [ "Semrush" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/content/titles": { "post": { "operationId": "semrush.content.titles", "tags": [ "Semrush" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemrushContentTitlesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/content/blogpost": { "post": { "operationId": "semrush.content.blogpost", "tags": [ "Semrush" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemrushContentBlogpostRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/content/rewrite": { "post": { "operationId": "semrush.content.rewrite", "tags": [ "Semrush" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemrushContentRewriteRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/content/summarize": { "post": { "operationId": "semrush.content.summarize", "tags": [ "Semrush" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemrushContentSummarizeRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/semrush/local/review-qr": { "post": { "operationId": "semrush.local.review-qr", "tags": [ "Semrush" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemrushReviewQrRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Semrush could not be fetched through the configured proxy pool after the full attempt budget. Never charged.", "value": { "error": "Semrush upstream is temporarily unavailable.", "retryable": true, "error_code": "semrush_upstream_unavailable" } } } } } }, "422": { "description": "A parameter failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "A parameter failed validation.", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/similarweb": { "get": { "operationId": "similarweb.data", "description": "Returns traffic data including global rank, country rank, engagement metrics,\ntraffic sources, top countries, and top keywords for a given domain.", "summary": "Get website traffic analytics from SimilarWeb", "tags": [ "SimilarWeb" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "The domain to analyze. Protocols and www prefixes are stripped automatically.", "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$", "minLength": 3, "maxLength": 253 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "site_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "global_rank": { "type": [ "object", "null" ], "properties": { "Rank": { "type": [ "integer", "null" ] } }, "required": [ "Rank" ] }, "country_rank": { "type": [ "object", "null" ], "properties": { "Country": { "type": [ "integer", "null" ] }, "CountryCode": { "type": [ "string", "null" ] }, "Rank": { "type": [ "integer", "null" ] } }, "required": [ "Country", "CountryCode", "Rank" ] }, "country_code": { "type": [ "string", "null" ] }, "category_rank": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "array", "items": {} }, { "type": "null" } ] }, "engagement": { "type": "object", "properties": { "visits": { "type": [ "string", "null" ] }, "time_on_site": { "type": [ "string", "null" ] }, "page_per_visit": { "type": [ "string", "null" ] }, "bounce_rate": { "type": [ "string", "null" ] }, "month": { "type": [ "string", "null" ] }, "year": { "type": [ "string", "null" ] } }, "required": [ "visits", "time_on_site", "page_per_visit", "bounce_rate", "month", "year" ] }, "traffic_sources": { "type": "object", "properties": { "direct": { "type": [ "number", "null" ] }, "search": { "type": [ "number", "null" ] }, "social": { "type": [ "number", "null" ] }, "referrals": { "type": [ "number", "null" ] }, "mail": { "type": [ "number", "null" ] }, "paid_referrals": { "type": [ "number", "null" ] } }, "required": [ "direct", "search", "social", "referrals", "mail", "paid_referrals" ] }, "top_countries": { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": [ "string", "null" ] }, "country_id": { "type": [ "integer", "null" ] }, "share": { "type": [ "number", "null" ] } }, "required": [ "country_code", "country_id", "share" ] } }, "estimated_monthly_visits": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "number" } ] } }, "top_keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": [ "string", "null" ] }, "share": { "type": [ "number", "null" ] }, "volume": { "type": [ "integer", "null" ] }, "cpc": { "type": [ "number", "null" ] } }, "required": [ "keyword", "share", "volume", "cpc" ] } }, "screenshot": { "type": [ "string", "null" ] } }, "required": [ "domain", "site_name", "title", "description", "category", "global_rank", "country_rank", "country_code", "category_rank", "engagement", "traffic_sources", "top_countries", "estimated_monthly_visits", "top_keywords", "screenshot" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/stepstone/jobs": { "get": { "operationId": "stepstone.jobs.search", "description": "Search for job listings on Stepstone with various filters.", "summary": "Search Stepstone Jobs", "tags": [ "Stepstone" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Job title, skill, or keyword (e.g. \"Software Engineer\", \"Python\")", "schema": { "type": "string", "maxLength": 500 } }, { "name": "location", "in": "query", "description": "City or region (e.g. \"Berlin\", \"M\u00fcnchen\")", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), nl (Netherlands), be (Belgium). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "nl", "be" ] } }, { "name": "radius", "in": "query", "description": "Search radius in kilometres (e.g. 30)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 200 } }, { "name": "sort", "in": "query", "description": "Sort order: relevance (default) or date", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "date" ] } }, { "name": "job_type", "in": "query", "description": "Filter by type: full_time, part_time, internship, freelance", "schema": { "type": [ "string", "null" ], "enum": [ "full_time", "part_time", "internship", "freelance" ] } }, { "name": "work_from_home", "in": "query", "description": "Filter for remote/work-from-home jobs (true/false)", "schema": { "type": [ "boolean", "null" ] } }, { "name": "date_posted", "in": "query", "description": "Maximum age of posting in days: 1, 3, 7, 30", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "3", "7", "30" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 } }, { "name": "limit", "in": "query", "description": "Max results to return (1\u2013100, default: 25)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "company": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "logo_url", "url" ] }, "location": { "type": "object", "properties": { "formatted": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "formatted", "city", "region", "country" ] }, "salary": { "type": [ "object", "null" ], "properties": { "formatted": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "period": { "type": [ "string", "null" ] } }, "required": [ "formatted", "min", "max", "currency", "period" ] }, "date_posted": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "contact_person": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "title", "email", "phone" ] }, "skills": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "string" } }, "work_from_home": { "type": "boolean" }, "is_highlighted": { "type": "boolean" }, "is_sponsored": { "type": "boolean" } }, "required": [ "id", "title", "url", "company", "location", "salary", "date_posted", "description", "contact_person", "skills", "labels", "work_from_home", "is_highlighted", "is_sponsored" ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_jobs": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_page": { "type": [ "integer", "null" ] } }, "required": [ "current_page", "total_pages", "total_jobs", "has_more", "next_page" ] }, "metadata": { "type": "object", "properties": { "query": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "query", "location", "country", "timestamp" ] } }, "required": [ "jobs", "pagination", "metadata" ] } }, "required": [ "success", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/stepstone/autosuggest": { "get": { "operationId": "stepstone.autosuggest", "description": "Get autocomplete suggestions for job search queries.", "summary": "Autosuggest Stepstone Job Sectors and Locations", "tags": [ "Stepstone" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search input to autocomplete (e.g. \"Soft\", \"Berl\")", "schema": { "type": "string", "maxLength": 500 } }, { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), nl (Netherlands), be (Belgium). Default: de", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "nl", "be" ] } }, { "name": "limit", "in": "query", "description": "Max suggestions per type (1\u201320, default: 10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "suggestions": { "type": "object", "properties": { "sectors": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "sectors", "locations" ] }, "metadata": { "type": "object", "properties": { "query": { "type": "string" }, "country": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "query", "country", "timestamp" ] } }, "required": [ "suggestions", "metadata" ] } }, "required": [ "success", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "503": { "description": "The approved proxy path or Stepstone upstream could not complete the request. This response is not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "stepstone_autosuggest_upstream_unavailable": { "description": "The approved proxy path or Stepstone upstream could not complete the request. This response is not billed.", "value": { "error": { "code": 503, "message": "Stepstone upstream is temporarily unavailable. Please retry shortly." }, "success": false } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustedshops/markets": { "get": { "operationId": "trustedshops.markets.free", "summary": "Get list of supported market codes", "tags": [ "TrustedShops" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "markets": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "code": { "type": "string", "const": "DEU" }, "name": { "type": "string", "const": "Germany" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "GBR" }, "name": { "type": "string", "const": "United Kingdom" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "AUT" }, "name": { "type": "string", "const": "Austria" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "CHE" }, "name": { "type": "string", "const": "Switzerland" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "NLD" }, "name": { "type": "string", "const": "Netherlands" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "ESP" }, "name": { "type": "string", "const": "Spain" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "ITA" }, "name": { "type": "string", "const": "Italy" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "FRA" }, "name": { "type": "string", "const": "France" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "BEL" }, "name": { "type": "string", "const": "Belgium" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "POL" }, "name": { "type": "string", "const": "Poland" } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "PRT" }, "name": { "type": "string", "const": "Portugal" } }, "required": [ "code", "name" ] } ], "minItems": 11, "maxItems": 11, "additionalItems": false }, "total_markets": { "type": "integer" } }, "required": [ "markets", "total_markets" ] }, "message": { "type": "string", "const": "TrustedShops markets retrieved successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/trustedshops/categories": { "get": { "operationId": "trustedshops.categories.free", "summary": "Get all shop categories on TrustedShops", "tags": [ "TrustedShops" ], "parameters": [ { "name": "market", "in": "query", "description": "Market code filter (DEU, GBR, AUT, CHE, NLD, ESP, ITA, FRA, BEL, POL, PRT). Default: DEU", "schema": { "type": [ "string", "null" ], "enum": [ "DEU", "GBR", "AUT", "CHE", "NLD", "ESP", "ITA", "FRA", "BEL", "POL", "PRT" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "urlPath": { "type": "string" }, "id": { "type": "integer" }, "totalCount": { "type": "integer" } }, "required": [ "name", "urlPath", "id", "totalCount" ] } } }, "required": [ "categories" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/trustedshops/search": { "get": { "operationId": "trustedshops.search", "summary": "Search for shops on TrustedShops", "tags": [ "TrustedShops" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Shop search query", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "page", "in": "query", "description": "Page number for pagination (0-100)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "market", "in": "query", "description": "Market code filter (DEU, GBR, AUT, CHE, NLD, ESP, ITA, FRA, BEL, POL, PRT)", "schema": { "type": [ "string", "null" ], "enum": [ "DEU", "GBR", "AUT", "CHE", "NLD", "ESP", "ITA", "FRA", "BEL", "POL", "PRT" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "metaData": { "type": "object", "properties": { "totalShopCount": { "type": "integer" }, "totalPageCount": { "type": "integer" } }, "required": [ "totalShopCount", "totalPageCount" ] }, "shops": { "type": "array", "items": { "type": "object", "properties": { "profileType": { "type": "string" }, "accountName": { "type": "string" }, "tsID": { "type": "string" }, "shopDescription": { "type": [ "string", "null" ] }, "shopName": { "type": "string" }, "shopUrl": { "type": "string" }, "shopCategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "integer" }, "urlPath": { "type": "string" } }, "required": [ "name", "id", "urlPath" ] } }, "shopLogoUrl": { "type": [ "string", "null" ] }, "descriptionAutoGenerated": { "type": "boolean" }, "averageRating": { "type": "number" }, "reviewCount": { "type": "integer" }, "certificationState": { "type": "boolean" }, "profileUrl": { "type": "string" }, "contractStartDate": { "type": "integer" } }, "required": [ "profileType", "accountName", "tsID", "shopDescription", "shopName", "shopUrl", "shopCategories", "shopLogoUrl", "descriptionAutoGenerated", "averageRating", "reviewCount", "certificationState", "profileUrl", "contractStartDate" ] } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "totalCount": { "type": "integer" }, "urlPath": { "type": "string" } }, "required": [ "id", "name", "totalCount", "urlPath" ] } } }, "required": [ "metaData", "shops", "categories" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustedshops/category-shops": { "get": { "operationId": "trustedshops.category-shops", "summary": "Get shops within a specific TrustedShops category", "tags": [ "TrustedShops" ], "parameters": [ { "name": "category", "in": "query", "required": true, "description": "Category URL path (e.g. bekleidung). Use the Categories endpoint to get available values.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "page", "in": "query", "description": "Page number for pagination (0-500). Default: 0", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 500 } }, { "name": "market", "in": "query", "description": "Market code filter (DEU, GBR, AUT, CHE, NLD, ESP, ITA, FRA, BEL, POL, PRT). Default: DEU", "schema": { "type": [ "string", "null" ], "enum": [ "DEU", "GBR", "AUT", "CHE", "NLD", "ESP", "ITA", "FRA", "BEL", "POL", "PRT" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "metaData": { "type": "object", "properties": { "totalShopCount": { "type": "integer" }, "totalPageCount": { "type": "integer" } }, "required": [ "totalShopCount", "totalPageCount" ] }, "shops": { "type": "array", "items": { "type": "object", "properties": { "profileType": { "type": "string" }, "accountName": { "type": "string" }, "tsID": { "type": "string" }, "shopDescription": { "type": [ "string", "null" ] }, "shopName": { "type": "string" }, "shopUrl": { "type": "string" }, "shopCategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "integer" }, "urlPath": { "type": "string" } }, "required": [ "name", "id", "urlPath" ] } }, "shopLogoUrl": { "type": [ "string", "null" ] }, "descriptionAutoGenerated": { "type": "boolean" }, "averageRating": { "type": "number" }, "reviewCount": { "type": "integer" }, "certificationState": { "type": "boolean" }, "profileUrl": { "type": "string" }, "contractStartDate": { "type": "integer" } }, "required": [ "profileType", "accountName", "tsID", "shopDescription", "shopName", "shopUrl", "shopCategories", "shopLogoUrl", "descriptionAutoGenerated", "averageRating", "reviewCount", "certificationState", "profileUrl", "contractStartDate" ] } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "totalCount": { "type": "integer" }, "urlPath": { "type": "string" } }, "required": [ "id", "name", "totalCount", "urlPath" ] } } }, "required": [ "metaData", "shops", "categories" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustedshops/reviews/{tsid}": { "get": { "operationId": "trustedshops.reviews", "summary": "Get reviews for a shop from TrustedShops", "tags": [ "TrustedShops" ], "parameters": [ { "name": "tsid", "in": "path", "required": true, "description": "Trusted Shops ID (33 uppercase alphanumeric characters).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (1-1000).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "size", "in": "query", "description": "Reviews per page (1-100).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "type": "object", "properties": { "shop": { "type": "object", "properties": { "tsId": { "type": "string" }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "creationDate": { "type": "string" }, "comment": { "type": "string" }, "rating": { "type": "integer" }, "customerName": { "type": "string" }, "orderDate": { "type": [ "string", "null" ] }, "verificationType": { "type": "string" }, "helpfulVotes": { "type": "integer" }, "unhelpfulVotes": { "type": "integer" }, "reply": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "comment": { "type": "string" } }, "required": [ "type", "createdAt", "updatedAt", "comment" ] } }, "required": [ "id", "creationDate", "comment", "rating", "customerName", "orderDate", "verificationType", "helpfulVotes", "unhelpfulVotes", "reply" ] } } }, "required": [ "tsId", "reviews" ] }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalReviews": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "currentPage", "pageSize", "totalReviews", "totalPages", "hasNextPage", "hasPreviousPage" ] } }, "required": [ "shop", "pagination" ] }, "message": { "type": "string" }, "responseInfo": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "apiSource": { "type": "string" } }, "required": [ "apiVersion", "apiSource" ] }, "status": { "type": "string" } }, "required": [ "code", "data", "message", "responseInfo", "status" ] } }, "required": [ "response" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustedshops/shop/{tsid}": { "get": { "operationId": "trustedshops.shop", "summary": "Get shop profile from TrustedShops", "tags": [ "TrustedShops" ], "parameters": [ { "name": "tsid", "in": "path", "required": true, "description": "Trusted Shops ID (33 uppercase alphanumeric characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "type": "object", "properties": { "shop": { "type": "object", "properties": { "tsId": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "languageISO2": { "type": "string" }, "targetMarketISO3": { "type": "string" }, "rating": { "type": "object", "properties": { "value": { "type": "number" }, "count": { "type": "integer" } }, "required": [ "value", "count" ] }, "certificate": { "type": "object", "properties": { "validFrom": { "type": "string" }, "validTo": { "type": "string" }, "status": { "type": "string" } }, "required": [ "validFrom", "validTo", "status" ] }, "qualityIndicators": { "type": "object", "properties": { "deliveryReliability": { "type": "number" }, "goodsQuality": { "type": "number" }, "customerService": { "type": "number" }, "returnsHandling": { "type": "number" } } } }, "required": [ "tsId", "url", "name", "languageISO2", "targetMarketISO3" ] } }, "required": [ "shop" ] }, "message": { "type": "string" }, "responseInfo": { "type": "object", "properties": { "apiVersion": { "type": "string" } }, "required": [ "apiVersion" ] }, "status": { "type": "string" } }, "required": [ "code", "data", "message", "responseInfo", "status" ] } }, "required": [ "response" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustpilot/categories": { "get": { "operationId": "trustpilot.categories.free", "summary": "Get all available Trustpilot categories with their subcategories", "tags": [ "Trustpilot" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } } }, "required": [ "id", "name", "slug", "subcategories" ] } }, "total_categories": { "type": "integer" }, "total_subcategories": { "type": "integer" } }, "required": [ "categories", "total_categories", "total_subcategories" ] }, "message": { "type": "string" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/trustpilot/countries": { "get": { "operationId": "trustpilot.countries.free", "summary": "Get all available Trustpilot countries", "tags": [ "Trustpilot" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "countryCode": { "type": "string" }, "countryName": { "type": "string" } }, "required": [ "countryCode", "countryName" ] } }, "total_countries": { "type": "integer" } }, "required": [ "countries", "total_countries" ] }, "message": { "type": "string" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/trustpilot/businesses": { "get": { "operationId": "trustpilot.businesses", "summary": "Get businesses from a Trustpilot category", "tags": [ "Trustpilot" ], "parameters": [ { "name": "category", "in": "query", "required": true, "description": "Category slug from the Categories endpoint (e.g. electronics_technology). Use the slug field from /api/trustpilot/categories response", "schema": { "type": "string", "pattern": "^[a-z0-9_-]+$", "minLength": 1, "maxLength": 100 } }, { "name": "page", "in": "query", "description": "Page number (1-999)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "sort", "in": "query", "description": "reviews_count or latest_review", "schema": { "type": [ "string", "null" ], "enum": [ "reviews_count", "latest_review" ] } }, { "name": "claimed", "in": "query", "description": "Filter claimed businesses", "schema": { "type": [ "boolean", "null" ] } }, { "name": "country", "in": "query", "description": "Country code (ISO-2)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "description": "Max results per page (1-50)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "trustscore", "in": "query", "description": "Minimum trustscore (3.0, 4.0, 4.5)", "schema": { "type": [ "number", "null" ], "enum": [ "3.0", "4.0", "4.5" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageProps": { "type": "object", "properties": { "businessUnits": { "type": "object", "properties": { "businesses": { "type": "array", "items": { "type": "object", "properties": { "businessUnitId": { "type": "string" }, "displayName": { "type": "string" }, "websiteUrl": { "type": "string" }, "trustScore": { "type": "number" }, "numberOfReviews": { "type": "integer" }, "stars": { "type": "number" }, "location": { "type": "object", "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "city", "country" ] } }, "required": [ "businessUnitId", "displayName", "websiteUrl", "trustScore", "numberOfReviews", "stars", "location" ] } } }, "required": [ "businesses" ] } }, "required": [ "businessUnits" ] } }, "required": [ "pageProps" ] } } } }, "422": { "description": "The category parameter is required and filters such as page, limit, country, sort, claimed, and trustscore must be valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The category parameter is required and filters such as page, limit, country, sort, claimed, and trustscore must be valid.", "value": { "errors": { "category": [ "The category field is required." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "500": { "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "SERVICE_ERROR": { "summary": "Service temporarily unavailable. Please try again.", "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "value": { "code": "SERVICE_ERROR", "error": "fallback_chain_exhausted", "message": "Service temporarily unavailable. Please try again.", "success": false, "status_code": 500 } } } } } }, "503": { "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "TRUSTPILOT_BLOCKED": { "summary": "Trustpilot businesses data is temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "value": { "code": "TRUSTPILOT_BLOCKED", "error": "fallback_chain_exhausted", "message": "Trustpilot businesses data is temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "success": false, "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustpilot/company-search": { "get": { "operationId": "trustpilot.company-search", "summary": "Search for companies on Trustpilot", "tags": [ "Trustpilot" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "description": "Page number (1-999)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "country", "in": "query", "description": "Country code (ISO-2)", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2 } }, { "name": "min_rating", "in": "query", "description": "Minimum rating (any, 3, 4, 4.5)", "schema": { "type": [ "string", "null" ], "enum": [ "any", "3", "4", "4.5" ] } }, { "name": "min_review_count", "in": "query", "description": "Minimum reviews (any, 25, 50, 100, 250, 500)", "schema": { "type": [ "string", "null" ], "enum": [ "any", "25", "50", "100", "250", "500" ] } }, { "name": "locale", "in": "query", "description": "Locale (e.g. en-US, de-DE)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 5 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "businessUnits": { "type": "array", "items": { "type": "object", "properties": { "businessUnitId": { "type": "string" }, "displayName": { "type": "string" }, "contact": { "type": "object", "properties": { "website": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "website", "email", "phone" ] }, "trustScore": { "type": "number" }, "numberOfReviews": { "type": "integer" }, "stars": { "type": "number" } }, "required": [ "businessUnitId", "displayName", "contact", "trustScore", "numberOfReviews", "stars" ] } } }, "required": [ "businessUnits" ] } } } }, "422": { "description": "The query parameter is required and filters such as page, country, min_rating, min_review_count, and locale must be valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The query parameter is required and filters such as page, country, min_rating, min_review_count, and locale must be valid.", "value": { "errors": { "query": [ "The query field is required." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "500": { "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "SERVICE_ERROR": { "summary": "Service temporarily unavailable. Please try again.", "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "value": { "code": "SERVICE_ERROR", "error": "fallback_chain_exhausted", "message": "Service temporarily unavailable. Please try again.", "success": false, "status_code": 500 } } } } } }, "503": { "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "TRUSTPILOT_BLOCKED": { "summary": "Trustpilot company search is temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "value": { "code": "TRUSTPILOT_BLOCKED", "error": "fallback_chain_exhausted", "message": "Trustpilot company search is temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "success": false, "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustpilot/company-details": { "get": { "operationId": "trustpilot.company-details", "summary": "Get company details from Trustpilot", "tags": [ "Trustpilot" ], "parameters": [ { "name": "company_domain", "in": "query", "required": true, "description": "Company domain", "schema": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "minLength": 3, "maxLength": 255 } }, { "name": "locale", "in": "query", "description": "Locale for Trustpilot page localization (e.g. en-US, de-DE). Review language defaults to languages=all unless the languages parameter is set.", "schema": { "type": [ "string", "null" ], "enum": [ "da-DK", "de-AT", "de-CH", "de-DE", "en-AU", "en-CA", "en-GB", "en-IE", "en-NZ", "en-US", "es-ES", "fi-FI", "fr-BE", "nl-BE", "fr-FR", "it-IT", "ja-JP", "nb-NO", "nl-NL", "pl-PL", "pt-BR", "pt-PT", "sv-SE" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "basic_info": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "claimed": { "type": "boolean" }, "verified": { "type": "boolean" }, "profileUrl": { "type": "string" } }, "required": [ "name", "domain", "logo", "website", "description", "claimed", "verified", "profileUrl" ] }, "ratings": { "type": "object", "properties": { "trustscore": { "type": [ "number", "null" ] }, "stars": { "type": [ "number", "null" ] }, "average": { "type": [ "number", "null" ] }, "count": { "type": "integer" } }, "required": [ "trustscore", "stars", "average", "count" ] }, "location": { "type": "object", "properties": { "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "country", "city", "address" ] }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "email", "phone" ] }, "social_media": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "og_title": { "type": [ "string", "null" ] }, "og_description": { "type": [ "string", "null" ] }, "og_image": { "type": [ "string", "null" ] }, "canonical_url": { "type": [ "string", "null" ] } }, "required": [ "title", "og_title", "og_description", "og_image", "canonical_url" ] } }, "required": [ "basic_info", "ratings", "location", "categories", "contact", "social_media", "metadata" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "description": "The company_domain parameter is required and locale must be valid when provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The company_domain parameter is required and locale must be valid when provided.", "value": { "errors": { "company_domain": [ "The company_domain field is required." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "500": { "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "SERVICE_ERROR": { "summary": "Service temporarily unavailable. Please try again.", "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "value": { "code": "SERVICE_ERROR", "error": "fallback_chain_exhausted", "message": "Service temporarily unavailable. Please try again.", "success": false, "status_code": 500 } } } } } }, "503": { "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "TRUSTPILOT_BLOCKED": { "summary": "Trustpilot company details are temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "value": { "code": "TRUSTPILOT_BLOCKED", "error": "fallback_chain_exhausted", "message": "Trustpilot company details are temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "success": false, "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/trustpilot/company-reviews": { "get": { "operationId": "trustpilot.company-reviews", "summary": "Get company reviews from Trustpilot", "tags": [ "Trustpilot" ], "parameters": [ { "name": "company_domain", "in": "query", "required": true, "description": "Company domain", "schema": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "minLength": 3, "maxLength": 255 } }, { "name": "page", "in": "query", "description": "Page number (1-999)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "description": "Reviews per page (1-100).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "verified", "in": "query", "description": "Filter verified reviews", "schema": { "type": [ "boolean", "null" ] } }, { "name": "with_replies", "in": "query", "description": "Only reviews with replies", "schema": { "type": [ "boolean", "null" ] } }, { "name": "query", "in": "query", "description": "Filter reviews by free-text search (1-200 characters). Omit to return all reviews.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "rating", "in": "query", "description": "Comma-separated ratings (e.g. 4,5)", "schema": { "type": [ "string", "null" ], "pattern": "^[1-5](,[1-5])*$" } }, { "name": "sort", "in": "query", "description": "Sort order. Valid values: \"relevance\" for Trustpilot relevance ranking or \"recency\" for newest reviews first. No other sort values are accepted.", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "recency" ] } }, { "name": "locale", "in": "query", "description": "Locale (e.g. en-US, de-DE)", "schema": { "type": [ "string", "null" ], "enum": [ "da-DK", "de-AT", "de-CH", "de-DE", "en-AU", "en-CA", "en-GB", "en-IE", "en-NZ", "en-US", "es-ES", "fi-FI", "fr-BE", "nl-BE", "fr-FR", "it-IT", "ja-JP", "nb-NO", "nl-NL", "pl-PL", "pt-BR", "pt-PT", "sv-SE" ] } }, { "name": "languages", "in": "query", "description": "Review language filter. Defaults to \"all\". Use \"all\" to fetch reviews in all languages, or a 2-letter code like en or de. Trustpilot expects language codes here, not locale codes: use de, not de-DE.", "schema": { "type": [ "string", "null" ], "pattern": "^(all|[a-z]{2})$" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to include (e.g., reviews,businessUnit.displayName). Use dot notation for nested fields. Omit to get all fields.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "date_posted", "in": "query", "description": "Only return reviews from this window: any, last_12_months, last_6_months, last_3_months or last_30_days.", "schema": { "type": [ "string", "null" ], "enum": [ "any", "last_12_months", "last_6_months", "last_3_months", "last_30_days" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageUrl": { "type": "string" }, "businessUnit": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "identifyingName": { "type": "string" }, "websiteUrl": { "type": "string" }, "websiteTitle": { "type": "string" }, "profileImageUrl": { "type": "string" }, "trustScore": { "type": "number" }, "stars": { "type": "number" }, "numberOfReviews": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "breadcrumb": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } }, "isClaimed": { "type": "boolean" }, "isClosed": { "type": "boolean" }, "isTemporarilyClosed": { "type": "boolean" }, "locationsCount": { "type": "integer" }, "isCollectingReviews": { "type": "boolean" }, "verification": { "type": "object", "properties": { "isVerified": { "type": "boolean" }, "verifiedDate": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } }, "required": [ "isVerified", "verifiedDate", "source" ] }, "hasCollectedIncentivisedReviews": { "type": "boolean" }, "consumerAlert": { "type": [ "array", "null" ], "items": {} }, "contactInfo": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "email", "phone", "address" ] }, "activity": { "type": "object", "properties": { "hasPaidForReviews": { "type": "boolean" } }, "required": [ "hasPaidForReviews" ] } }, "required": [ "id", "displayName", "identifyingName", "websiteUrl", "websiteTitle", "profileImageUrl", "trustScore", "stars", "numberOfReviews", "categories", "breadcrumb", "isClaimed", "isClosed", "isTemporarilyClosed", "locationsCount", "isCollectingReviews", "verification", "hasCollectedIncentivisedReviews", "consumerAlert", "contactInfo", "activity" ] }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "rating": { "type": "integer" }, "dates": { "type": "object", "properties": { "publishedDate": { "type": "string" }, "updatedDate": { "type": "string" }, "experiencedDate": { "type": [ "string", "null" ] }, "submittedDate": { "type": "string" } }, "required": [ "publishedDate", "updatedDate", "experiencedDate", "submittedDate" ] }, "isVerified": { "type": "boolean" }, "language": { "type": "string" }, "location": { "type": "object", "properties": { "country": { "type": "string" }, "city": { "type": [ "string", "null" ] } }, "required": [ "country", "city" ] }, "filtered": { "type": "boolean" }, "isPending": { "type": "boolean" }, "likes": { "type": "integer" }, "source": { "type": "string" }, "hasUnhandledReports": { "type": "boolean" }, "consumersReviewCountOnSameDomain": { "type": "integer" }, "productReviews": { "type": "array", "items": {} }, "labels": { "type": "object", "properties": { "merged": { "type": "boolean" }, "verification": { "type": "object", "properties": { "isVerified": { "type": "boolean" }, "verificationLevel": { "type": "string" }, "reviewSourceName": { "type": "string" }, "verificationSource": { "type": "string" } }, "required": [ "isVerified", "verificationLevel", "reviewSourceName", "verificationSource" ] } }, "required": [ "merged", "verification" ] }, "consumer": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "countryCode": { "type": "string" }, "numberOfReviews": { "type": "integer" }, "imageUrl": { "type": [ "string", "null" ] }, "hasImage": { "type": "boolean" }, "isVerified": { "type": "boolean" } }, "required": [ "id", "displayName", "countryCode", "numberOfReviews", "imageUrl", "hasImage", "isVerified" ] }, "reply": { "type": [ "object", "null" ], "properties": { "message": { "type": "string" }, "publishedDate": { "type": "string" }, "updatedDate": { "type": "string" } }, "required": [ "message", "publishedDate", "updatedDate" ] } }, "required": [ "id", "title", "text", "rating", "dates", "isVerified", "language", "location", "filtered", "isPending", "likes", "source", "hasUnhandledReports", "consumersReviewCountOnSameDomain", "productReviews", "labels", "consumer", "reply" ] } }, "filters": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" }, "totalResults": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "currentPage", "totalPages", "totalResults", "perPage" ] } }, "required": [ "pagination" ] }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" }, "per_page": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_previous_page": { "type": "boolean" } }, "required": [ "current_page", "total_pages", "total_count", "per_page", "has_next_page", "has_previous_page" ] }, "relevantReviews": { "type": "array", "items": { "type": "array", "items": {} } }, "aiSummary": { "type": [ "object", "null" ], "properties": { "summary": { "type": "string" }, "rating": { "type": "number" }, "totalReviews": { "type": "integer" } }, "required": [ "summary", "rating", "totalReviews" ] }, "aiSummaryReviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "rating": { "type": "integer" } }, "required": [ "id", "title", "rating" ] } }, "topicAiSummaries": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "summary": { "type": "string" }, "reviewCount": { "type": "integer" }, "rating": { "type": "number" } }, "required": [ "topic", "summary", "reviewCount", "rating" ] } }, "topicAiSummaryReviews": { "type": "array", "items": {} }, "similarBusinessUnits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "trustScore": { "type": "number" }, "numberOfReviews": { "type": "integer" }, "profileUrl": { "type": "string" } }, "required": [ "id", "displayName", "trustScore", "numberOfReviews", "profileUrl" ] } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "reviewCount": { "type": "integer" } }, "required": [ "id", "name", "reviewCount" ] } }, "sidebarData": { "type": "object", "properties": { "topRated": { "type": "boolean" }, "awards": { "type": "array", "items": {} } }, "required": [ "topRated", "awards" ] }, "seoData": { "type": [ "array", "null" ], "items": {} }, "showAdvertisement": { "type": "boolean" }, "surveyPromptEnabled": { "type": "boolean" }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" }, "cached_at": { "type": "string" } }, "required": [ "url", "duration_ms", "scraped_at", "cached" ] } }, "required": [ "pageUrl", "businessUnit", "reviews", "filters", "pagination", "relevantReviews", "aiSummary", "aiSummaryReviews", "topicAiSummaries", "topicAiSummaryReviews", "similarBusinessUnits", "products", "sidebarData", "seoData", "showAdvertisement", "surveyPromptEnabled", "meta" ] } } } }, "422": { "description": "The company_domain parameter is required and review filters such as page, rating, sort, verified, with_replies, languages, and date_posted must be valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "validation_error": { "summary": "The request validation failed.", "description": "The company_domain parameter is required and review filters such as page, rating, sort, verified, with_replies, languages, and date_posted must be valid.", "value": { "errors": { "company_domain": [ "The company_domain field is required." ] }, "message": "The request validation failed" } } } } } }, "402": { "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "insufficient_credits": { "summary": "You have run out of credits.", "description": "Your API key is valid, but the account has no free, subscription, or package credits available.", "value": { "error": "You've ran out of credits to use please purchase a subscription or a package." } } } } } }, "500": { "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "SERVICE_ERROR": { "summary": "Service temporarily unavailable. Please try again.", "description": "The Trustpilot endpoint could not complete the current scrape attempt.", "value": { "code": "SERVICE_ERROR", "error": "fallback_chain_exhausted", "message": "Service temporarily unavailable. Please try again.", "success": false, "status_code": 500 } } } } } }, "503": { "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "TRUSTPILOT_BLOCKED": { "summary": "Trustpilot company reviews are temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "description": "Trustpilot WAF protection or the bounded in-house/RapidAPI cascade exhausted the available fetch path for this endpoint.", "value": { "code": "TRUSTPILOT_BLOCKED", "error": "fallback_chain_exhausted", "message": "Trustpilot company reviews are temporarily unavailable after WAF-protected fetch and fallback tiers were exhausted.", "success": false, "status_code": 503 } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/countries": { "get": { "operationId": "vinted.countries.free", "description": "Returns a list of Vinted-supported countries with their TLDs.", "summary": "Get supported countries", "tags": [ "Vinted" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "countries": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "code": { "type": "string", "const": "FR" }, "name": { "type": "string", "const": "France" }, "tld": { "type": "string", "const": "fr" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "DE" }, "name": { "type": "string", "const": "Germany" }, "tld": { "type": "string", "const": "de" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "ES" }, "name": { "type": "string", "const": "Spain" }, "tld": { "type": "string", "const": "es" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "IT" }, "name": { "type": "string", "const": "Italy" }, "tld": { "type": "string", "const": "it" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "NL" }, "name": { "type": "string", "const": "Netherlands" }, "tld": { "type": "string", "const": "nl" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "BE" }, "name": { "type": "string", "const": "Belgium" }, "tld": { "type": "string", "const": "be" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "AT" }, "name": { "type": "string", "const": "Austria" }, "tld": { "type": "string", "const": "at" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "PL" }, "name": { "type": "string", "const": "Poland" }, "tld": { "type": "string", "const": "pl" }, "currency": { "type": "string", "const": "PLN" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "CZ" }, "name": { "type": "string", "const": "Czech Republic" }, "tld": { "type": "string", "const": "cz" }, "currency": { "type": "string", "const": "CZK" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "LT" }, "name": { "type": "string", "const": "Lithuania" }, "tld": { "type": "string", "const": "lt" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "LU" }, "name": { "type": "string", "const": "Luxembourg" }, "tld": { "type": "string", "const": "lu" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "SK" }, "name": { "type": "string", "const": "Slovakia" }, "tld": { "type": "string", "const": "sk" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "HU" }, "name": { "type": "string", "const": "Hungary" }, "tld": { "type": "string", "const": "hu" }, "currency": { "type": "string", "const": "HUF" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "RO" }, "name": { "type": "string", "const": "Romania" }, "tld": { "type": "string", "const": "ro" }, "currency": { "type": "string", "const": "RON" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "PT" }, "name": { "type": "string", "const": "Portugal" }, "tld": { "type": "string", "const": "pt" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "SE" }, "name": { "type": "string", "const": "Sweden" }, "tld": { "type": "string", "const": "se" }, "currency": { "type": "string", "const": "SEK" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "DK" }, "name": { "type": "string", "const": "Denmark" }, "tld": { "type": "string", "const": "dk" }, "currency": { "type": "string", "const": "DKK" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "FI" }, "name": { "type": "string", "const": "Finland" }, "tld": { "type": "string", "const": "fi" }, "currency": { "type": "string", "const": "EUR" } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "US" }, "name": { "type": "string", "const": "United States" }, "tld": { "type": "string", "const": "com" }, "currency": { "type": "string", "const": "USD" } }, "required": [ "code", "name", "tld", "currency" ] } ], "minItems": 19, "maxItems": 19, "additionalItems": false }, "total_countries": { "type": "integer" } }, "required": [ "countries", "total_countries" ] }, "message": { "type": "string", "const": "Vinted countries retrieved successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/vinted/search": { "get": { "operationId": "vinted.search", "description": "Search for clothing, accessories, and other items on Vinted marketplace.\nSupports filtering by brand, category, size, color, material, status, and price range.", "summary": "Search items in the Vinted catalog", "tags": [ "Vinted" ], "parameters": [ { "name": "q", "in": "query", "description": "Search term (1-500 characters). Alias for query.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "query", "in": "query", "description": "Search query text (e.g., \"nike shoes\")", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "page", "in": "query", "description": "Page number for pagination. Defaults to 1.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max 100). Defaults to 24.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "order", "in": "query", "description": "Sort order: relevance, newest_first, price_low_to_high, price_high_to_low", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "newest_first", "price_low_to_high", "price_high_to_low" ] } }, { "name": "brand_ids", "in": "query", "description": "Brand IDs to filter by (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "catalog_ids", "in": "query", "description": "Category IDs to filter by (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "color_ids", "in": "query", "description": "Color IDs to filter by (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "size_ids", "in": "query", "description": "Size IDs to filter by (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "material_ids", "in": "query", "description": "Material IDs to filter by (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "status_ids", "in": "query", "description": "Status IDs to filter by (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "price_from", "in": "query", "description": "Minimum price filter (inclusive). Items below this price will be filtered out from results.", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "price_to", "in": "query", "description": "Maximum price filter (inclusive). Items above this price will be filtered out from results.", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain (FR, DE, BE, IT, ES, NL, etc.). Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "photo": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "login": { "type": "string" } }, "required": [ "id", "login" ] }, "url": { "type": "string" } }, "required": [ "id", "title", "price", "photo", "user", "url" ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": [ "integer", "null" ] }, "total_entries": { "type": [ "integer", "null" ] }, "per_page": { "type": "integer" } }, "required": [ "current_page", "total_pages", "total_entries", "per_page" ] }, "search_tracking_params": { "type": [ "array", "null" ], "items": {} } }, "required": [ "items", "pagination", "search_tracking_params" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/filters": { "get": { "operationId": "vinted.filters", "description": "Retrieve available filter options for the Vinted catalog including brands, sizes, colors, etc.", "summary": "Get available catalog filters", "tags": [ "Vinted" ], "parameters": [ { "name": "q", "in": "query", "description": "Search term (1-500 characters). Alias for query.", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "query", "in": "query", "description": "Search term (1-500 characters).", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "page", "in": "query", "description": "Page number (1-999).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "description": "Items per page (1-100).", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "order", "in": "query", "description": "Sort order: relevance, newest_first, price_low_to_high or price_high_to_low.", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "newest_first", "price_low_to_high", "price_high_to_low" ] } }, { "name": "brand_ids", "in": "query", "description": "Comma-separated brand IDs to filter by.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "catalog_ids", "in": "query", "description": "Category IDs to get filters for (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "color_ids", "in": "query", "description": "Comma-separated colour IDs to filter by.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "size_ids", "in": "query", "description": "Comma-separated size IDs to filter by.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "material_ids", "in": "query", "description": "Comma-separated material IDs to filter by.", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "status_ids", "in": "query", "description": "Comma-separated item-condition IDs to filter by.", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "price_from", "in": "query", "description": "Minimum price.", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "price_to", "in": "query", "description": "Maximum price.", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "catalogs": { "type": [ "array", "null" ], "items": {} }, "brands": { "type": [ "array", "null" ], "items": {} }, "colors": { "type": [ "array", "null" ], "items": {} }, "sizes": { "type": [ "array", "null" ], "items": {} }, "materials": { "type": [ "array", "null" ], "items": {} }, "statuses": { "type": [ "array", "null" ], "items": {} } }, "required": [ "catalogs", "brands", "colors", "sizes", "materials", "statuses" ] } }, "required": [ "filters" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/suggestions": { "get": { "operationId": "vinted.suggestions", "description": "Get autocomplete suggestions for a search query.", "summary": "Get search suggestions", "tags": [ "Vinted" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Partial search query to get suggestions for", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US", "GB" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ] } } }, "required": [ "suggestions" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "description": "The query is missing, too long, or the country code is not one of the supported Vinted domains.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The query is missing, too long, or the country code is not one of the supported Vinted domains.", "value": { "errors": { "query": [ "The search query is required." ] }, "message": "The request validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "400": { "description": "The requested country is blocked for this Vinted endpoint due to upstream security restrictions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The requested country is blocked for this Vinted endpoint due to upstream security restrictions.", "value": { "error": "Country not supported", "message": "The United Kingdom (GB) is currently unsupported due to increased security measures by Vinted. Please use a different country code.", "success": false, "http_code": 400 } } } } } }, "502": { "description": "Vinted returned a non-successful upstream response through the mobile proxy path.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Vinted returned a non-successful upstream response through the mobile proxy path.", "value": { "error": "Vinted API returned an error", "message": "The Vinted API returned an error. Please try again.", "success": false, "http_code": 502 } } } } } }, "503": { "description": "No approved mobile proxy was available, or the retry budget was exhausted before Vinted returned a usable response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "No approved mobile proxy was available, or the retry budget was exhausted before Vinted returned a usable response.", "value": { "error": "Proxy unavailable", "message": "Service temporarily unavailable. Please try again.", "success": false, "http_code": 503 } } } } } }, "500": { "description": "Vinted returned a response that could not be parsed as JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Vinted returned a response that could not be parsed as JSON.", "value": { "error": "Failed to parse Vinted response", "message": "Invalid JSON response", "success": false, "http_code": 500 } } } } } } } } }, "/vinted/item-details": { "get": { "operationId": "vinted.item-details", "description": "Get full details for a specific item including photos, description, seller info, and price.\nThis endpoint scrapes the item page since the API is protected by Cloudflare.", "summary": "Get item details", "tags": [ "Vinted" ], "parameters": [ { "name": "item_id", "in": "query", "required": true, "description": "The Vinted item ID", "schema": { "type": "string", "maxLength": 50 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US", "GB" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "total_item_price": { "type": [ "number", "null" ] }, "shipping_price": { "type": [ "number", "null" ] }, "service_fee": { "type": [ "number", "null" ] }, "url": { "type": [ "string", "null" ] }, "availability": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ] }, "condition_title": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "seller": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "login": { "type": [ "string", "null" ] }, "feedback_count": { "type": "integer" }, "feedback_reputation": { "type": "number" } }, "required": [ "id", "login", "feedback_count", "feedback_reputation" ] }, "photos": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "favourite_count": { "type": [ "integer", "null" ] }, "view_count": { "type": [ "integer", "null" ] } }, "required": [ "id", "title", "description", "price", "total_item_price", "shipping_price", "service_fee", "url", "availability", "image_url", "condition", "condition_title", "brand", "category", "size", "color", "seller", "photos", "favourite_count", "view_count" ] } }, "required": [ "item" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "duration_ms", "scraped_at", "cached" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/item-shipping": { "get": { "operationId": "vinted.item-shipping", "description": "Get shipping options and costs for a specific item.", "summary": "Get item shipping details", "tags": [ "Vinted" ], "parameters": [ { "name": "item_id", "in": "query", "required": true, "description": "The Vinted item ID", "schema": { "type": "string", "maxLength": 50 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "shipping": { "type": "object", "properties": { "delivery_options": { "type": [ "array", "null" ], "items": {} }, "carrier": { "type": [ "string", "null" ] }, "cost": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "delivery_options", "carrier", "cost" ] } }, "required": [ "shipping" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/user-profile": { "get": { "operationId": "vinted.user-profile", "description": "Get public profile information for a Vinted user including ratings, review count, and items listed.", "summary": "Get user profile", "tags": [ "Vinted" ], "parameters": [ { "name": "user_id", "in": "query", "required": true, "description": "The Vinted user ID", "schema": { "type": "string", "maxLength": 50 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "type": "array", "items": {} } }, "required": [ "user" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/user-items": { "get": { "operationId": "vinted.user-items", "description": "Get items listed by a specific user in their wardrobe/closet.", "summary": "Get user items (wardrobe)", "tags": [ "Vinted" ], "parameters": [ { "name": "user_id", "in": "query", "required": true, "description": "The Vinted user ID", "schema": { "type": "string", "maxLength": 50 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max 100). Defaults to 24.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "order", "in": "query", "description": "Sort order: relevance, newest_first, price_low_to_high, price_high_to_low", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "newest_first", "price_low_to_high", "price_high_to_low" ] } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": {} }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": [ "integer", "null" ] }, "total_entries": { "type": [ "integer", "null" ] }, "per_page": { "type": "integer" } }, "required": [ "current_page", "total_pages", "total_entries", "per_page" ] } }, "required": [ "items", "pagination" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/similar-items": { "get": { "operationId": "vinted.similar-items", "description": "Get items similar to a specific item, typically from the same seller or category.", "summary": "Get similar items", "tags": [ "Vinted" ], "parameters": [ { "name": "item_id", "in": "query", "required": true, "description": "The Vinted item ID", "schema": { "type": "string", "pattern": "^[0-9]+$", "maxLength": 50 } }, { "name": "page", "in": "query", "description": "Page number for pagination. Defaults to 1.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US", "GB" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "type": "array", "items": {} }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": [ "integer", "null" ] }, "total_entries": { "type": [ "integer", "null" ] } }, "required": [ "current_page", "total_pages", "total_entries" ] } }, "required": [ "items", "pagination" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "description": "Validation failed - Check item_id (required, max 50 chars), page (min 1), and country (must be valid country code) parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Validation failed - Check item_id (required, max 50 chars), page (min 1), and country (must be valid country code) parameters", "value": { "message": "Error" } } } } } }, "404": { "description": "Item not found - The requested item ID does not exist on Vinted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Item not found - The requested item ID does not exist on Vinted", "value": { "message": "Error" } } } } } }, "500": { "description": "Vinted API error or service temporarily unavailable - Please try again later", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Vinted API error or service temporarily unavailable - Please try again later", "value": { "message": "Error" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/vinted/categories": { "get": { "operationId": "vinted.categories", "description": "Get all available catalog categories with their subcategories.\nUse the returned catalog IDs with the search endpoint's catalog_ids parameter to filter items.", "summary": "Get categories", "tags": [ "Vinted" ], "parameters": [ { "name": "country", "in": "query", "description": "Country code for Vinted domain. Defaults to FR.", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "enum": [ "FR", "DE", "ES", "IT", "NL", "BE", "AT", "PL", "CZ", "LT", "LU", "SK", "HU", "RO", "PT", "SE", "DK", "FI", "US" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "catalogs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" }, "is_visible": { "type": "boolean" }, "is_root": { "type": "boolean" }, "parent_id": { "type": [ "integer", "null" ] }, "children": { "type": "array", "items": {} } }, "required": [ "id", "title", "slug", "url", "is_visible", "is_root", "parent_id", "children" ] } } }, "required": [ "catalogs" ] }, "message": { "type": "string" }, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" }, "scraped_at": { "type": "string" }, "cached": { "type": "boolean" } }, "required": [ "duration_ms", "scraped_at" ] } }, "required": [ "success", "data", "message", "meta" ] } } } }, "422": { "description": "Invalid country code provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Invalid country code provided", "value": { "errors": { "country": [ "The selected country is invalid." ] }, "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Failed to fetch categories from Vinted or parse response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Failed to fetch categories from Vinted or parse response", "value": { "error": "An error occurred while fetching categories", "message": "Service temporarily unavailable. Please try again.", "success": false } } } } } } } } }, "/web-scraper": { "get": { "operationId": "web-scraper.scrape", "tags": [ "WebScraper" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The URL to scrape (must include protocol, e.g., https://example.com)", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "include_html", "in": "query", "description": "Set to true to include the raw HTML in the response. Default: false. Ignored when response_type=markdown", "schema": { "type": [ "boolean", "null" ] } }, { "name": "javascript", "in": "query", "description": "Set to true to execute page JavaScript before extracting content. This mode uses the Obscura browser engine through Scrappa's proxy layer. Default: false", "schema": { "type": [ "boolean", "null" ] } }, { "name": "response_type", "in": "query", "description": "Set to \"markdown\" to return only the page content as clean markdown text. When set to markdown, only the markdown content is returned (not JSON). Default: json", "schema": { "type": [ "string", "null" ], "enum": [ "json", "markdown" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "const": "An unexpected error occurred while scraping the URL." }, "error_code": { "type": "string", "const": "INTERNAL_ERROR" } }, "required": [ "success", "error", "error_code" ] }, { "type": "string", "const": "Error: An unexpected error occurred while scraping the URL." } ] } } } }, "400": { "description": "The url parameter is not a valid absolute URL or domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The url parameter is not a valid absolute URL or domain.", "value": { "error": "Invalid URL format.", "success": false, "error_code": "INVALID_URL" } } } } } }, "422": { "description": "Required parameters failed request validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "Required parameters failed request validation.", "value": { "errors": { "url": [ "The url parameter is required." ] }, "message": "The request validation failed" } } } } } }, "502": { "description": "The proxy pool was exhausted or the target SSL connection failed. This is separate from the target site HTTP status code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The proxy pool was exhausted or the target SSL connection failed. This is separate from the target site HTTP status code.", "value": { "error": "Proxy pool exhausted while scraping the URL.", "success": false, "error_code": "PROXY_EXHAUSTED", "diagnostics": { "proxy_attempts": 3, "max_proxy_attempts": 3 } } } } } } }, "503": { "description": "JavaScript rendering is temporarily unavailable or its bounded queue is full. Retry later; failed requests are not billed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "JavaScript rendering is temporarily unavailable or its bounded queue is full. Retry later; failed requests are not billed.", "value": { "error": "JavaScript rendering is temporarily unavailable", "success": false, "error_code": "JAVASCRIPT_RENDERER_UNAVAILABLE" } } } } } }, "504": { "description": "The target could not be fetched through the proxy layer before the scraper timeout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "error_0": { "description": "The target could not be fetched through the proxy layer before the scraper timeout.", "value": { "error": "Connection timed out while scraping the URL.", "success": false, "error_code": "CONNECTION_TIMEOUT" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/wlw/search": { "get": { "operationId": "wlw.search", "summary": "Search for B2B suppliers and products on WLW", "tags": [ "Wlw" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (e.g., \"agentur\", \"software\", \"logistik\")", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Results per page (1-50, default: 15)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "country", "in": "query", "description": "Country code: DE (Germany), AT (Austria), CH (Switzerland). Default: DE", "schema": { "type": [ "string", "null" ], "enum": [ "DE", "AT", "CH" ] } }, { "name": "countries", "in": "query", "description": "Filter by country codes (comma-separated, e.g., \"DE,AT\")", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}(,[A-Za-z]{2})*$" } }, { "name": "category", "in": "query", "description": "Filter by category ID", "schema": { "type": [ "string", "null" ], "pattern": "^\\d+$" } }, { "name": "supplier_type", "in": "query", "description": "Filter by supplier type (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "attributes", "in": "query", "description": "Filter by attribute codes (comma-separated)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "verified", "in": "query", "description": "Only show verified suppliers", "schema": { "type": [ "boolean", "null" ] } }, { "name": "top_responder", "in": "query", "description": "Only show top responders", "schema": { "type": [ "boolean", "null" ] } }, { "name": "latitude", "in": "query", "description": "Location filter: latitude", "schema": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "description": "Location filter: longitude", "schema": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 } }, { "name": "radius", "in": "query", "description": "Search radius in km (requires lat/lng)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 } }, { "name": "sort", "in": "query", "description": "Sort: relevance, recency, trending, distance", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "recency", "trending", "distance" ] } }, { "name": "language", "in": "query", "description": "Language code (default: de)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Internal service error" }, "message": { "type": "string", "const": "An unexpected error occurred." }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "wlw/search" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to fetch data from WLW API" }, "message": { "type": "string", "const": "Service temporarily unavailable. Please try again." }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "wlw/search" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "current_page": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "total_pages": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "per_page": { "type": "integer" }, "total_results": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] } }, "required": [ "current_page", "total_pages", "per_page", "total_results" ] }, "filters": { "type": "object", "properties": { "categories": { "type": "array", "items": {} }, "countries": { "type": "array", "items": {} }, "employee_counts": { "type": "array", "items": {} }, "supplier_types": { "type": "array", "items": {} }, "attributes": { "type": "array", "items": {} }, "price": { "type": "object", "properties": { "min": { "type": [ "string", "null" ] }, "max": { "type": [ "string", "null" ] }, "valid_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] } }, "required": [ "min", "max", "valid_count" ] } }, "required": [ "categories", "countries", "employee_counts", "supplier_types", "attributes", "price" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "null" } }, "required": [ "pagination", "filters", "duration_ms", "cached", "cached_at" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "wlw/search" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "success", "data", "meta", "_debug" ] }, { "type": "string" }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "array", "items": {} }, "_debug": { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } }, "required": [ "success", "data", "meta", "_debug" ] } ] } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Invalid response from WLW API" }, "message": { "type": "string", "const": "Unexpected response format." }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "const": "wlw/search" }, "method": { "type": "string", "const": "GET" }, "request_params": { "type": "array", "items": {} }, "query": {}, "url": { "type": "string" }, "user_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "request_id", "endpoint", "method", "request_params", "query", "url", "user_id", "ip_address", "user_agent", "timestamp" ] }, { "type": "object", "properties": { "note": { "type": "string", "const": "Debug mode enabled but no debug data collected" } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/locales": { "get": { "operationId": "youtube.locales", "summary": "Get supported YouTube locale metadata", "tags": [ "YouTube" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": {} } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/search": { "get": { "operationId": "youtube.search", "summary": "Search YouTube videos", "tags": [ "YouTube" ], "parameters": [ { "name": "query", "in": "query", "description": "Search query", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "limit", "in": "query", "description": "Number of results (default: 10, max: 20)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "page", "in": "query", "description": "Page number (default: 1, max: 10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "continuation", "in": "query", "description": "Token for pagination from previous response", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Country code (e.g., US).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "type", "in": "query", "description": "Filter by content type: video, channel, playlist, movie, all (default: all).", "schema": { "type": [ "string", "null" ], "enum": [ "video", "channel", "playlist", "movie", "all" ] } }, { "name": "order", "in": "query", "description": "Sort order: date, rating, relevance, viewCount.", "schema": { "type": [ "string", "null" ], "enum": [ "date", "rating", "relevance", "viewCount" ] } }, { "name": "videoDuration", "in": "query", "description": "Filter by duration: short, medium, long.", "schema": { "type": [ "string", "null" ], "enum": [ "short", "medium", "long" ] } }, { "name": "publishedAfter", "in": "query", "description": "Return videos published after a date/time (best-effort; any valid date string, RFC3339 recommended).", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "publishedBefore", "in": "query", "description": "Return videos published before a date/time (best-effort; any valid date string, RFC3339 recommended).", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "safeSearch", "in": "query", "description": "Content filtering: moderate, none, strict.", "schema": { "type": [ "string", "null" ], "enum": [ "moderate", "none", "strict" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "thumbnail": { "type": [ "string", "null" ] }, "duration": { "type": "string" }, "viewCount": { "type": "string" }, "publishedTime": { "type": "string" }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "thumbnail": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" }, "isVerifiedArtist": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "id", "name", "thumbnail", "verified", "isVerifiedArtist", "url" ] }, "badges": { "type": "array", "items": { "type": "string" } }, "isLive": { "type": "boolean" }, "isShort": { "type": "boolean" }, "isPremium": { "type": "boolean" } }, "required": [ "type", "id", "title", "description", "thumbnail", "duration", "viewCount", "publishedTime", "channel", "badges", "isLive", "isShort", "isPremium" ] } }, "pagination": { "type": "object", "properties": { "continuationToken": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "required": [ "continuationToken", "hasMore", "page", "pageSize" ] }, "query": { "type": "string" }, "filters": { "type": "object", "properties": { "type": { "type": "string" }, "sort": { "type": "string" }, "hl": { "type": [ "string", "null" ] }, "gl": { "type": [ "string", "null" ] } } } }, "required": [ "results", "pagination", "query", "filters" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/suggestions": { "get": { "operationId": "youtube.suggestions", "summary": "Get search suggestions", "tags": [ "YouTube" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1 } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Country code (e.g., US).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "locale": { "type": "object", "properties": { "hl": { "type": "string" }, "gl": { "type": "string" } }, "required": [ "hl", "gl" ] }, "suggestions": { "type": "array", "items": { "type": "string" } } }, "required": [ "query", "locale", "suggestions" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/video": { "get": { "operationId": "youtube.video", "summary": "Get video details", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "description": "YouTube video ID (alias: videoId)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "description": "YouTube video ID (alias: video_id)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "videoId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "thumbnail": { "type": "string" }, "duration": { "type": "string" }, "viewCount": { "type": "string" }, "shortViewCount": { "type": "string" }, "likeCount": { "type": "integer" }, "publishDate": { "type": "string" }, "uploadDate": { "type": "string" }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "thumbnail": { "type": [ "string", "null" ] }, "subscriberCount": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "required": [ "id", "name", "thumbnail", "subscriberCount", "verified" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "isLive": { "type": "boolean" }, "isPremium": { "type": "boolean" }, "isPrivate": { "type": "boolean" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "startTime": { "type": "integer" }, "startTimeMillis": { "type": "integer" }, "thumbnail": { "type": [ "string", "null" ] } }, "required": [ "title", "startTime", "startTimeMillis", "thumbnail" ] } }, "captions": { "type": "array", "items": { "type": "array", "items": {} } }, "comments": { "type": [ "array", "null" ], "items": { "type": "array", "items": {} } }, "relatedVideos": { "type": [ "array", "null" ], "items": { "type": "array", "items": {} } }, "annotations": { "type": [ "array", "null" ], "items": { "type": "array", "items": {} } }, "autoplay": { "type": [ "object", "null" ], "properties": { "countDownSecs": { "type": "integer" }, "sets": { "type": "integer" } }, "required": [ "countDownSecs", "sets" ] }, "cards": { "type": [ "array", "null" ], "items": { "type": "array", "items": {} } }, "endScreen": { "type": [ "object", "null" ], "properties": { "startMs": { "type": "integer" }, "elements": { "type": "array", "items": { "type": "array", "items": {} } } }, "required": [ "startMs", "elements" ] }, "hasStreamingData": { "type": "boolean" }, "license": { "type": [ "string", "null" ] }, "merchandise": { "type": [ "array", "null" ], "items": {} }, "playerConfig": { "type": [ "object", "null" ], "properties": { "audioConfig": { "type": "array", "items": {} }, "maxBitrate": { "type": "string" } }, "required": [ "audioConfig", "maxBitrate" ] }, "playerOverlays": { "type": [ "object", "null" ], "properties": { "endScreen": { "type": "array", "items": {} }, "autoplay": { "type": "array", "items": {} }, "shareButton": { "type": "array", "items": {} }, "decoratedPlayerBar": { "type": "array", "items": {} } }, "required": [ "endScreen", "autoplay", "shareButton", "decoratedPlayerBar" ] }, "streamingDataExpires": { "anyOf": [ { "type": "array", "items": {} }, { "type": "integer" }, { "type": "null" } ] }, "topComments": { "anyOf": [ { "type": "array", "items": {} }, { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "videoId", "title", "description", "thumbnail", "duration", "viewCount", "shortViewCount", "likeCount", "publishDate", "uploadDate", "channel", "hashtags", "keywords", "category", "isLive", "isPremium", "isPrivate", "chapters", "captions", "comments", "relatedVideos", "annotations", "autoplay", "cards", "endScreen", "hasStreamingData", "license", "merchandise", "playerConfig", "playerOverlays", "streamingDataExpires", "topComments" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/comments": { "get": { "operationId": "youtube.comments", "summary": "Get video comments", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "required": true, "description": "YouTube video ID", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "limit", "in": "query", "description": "Number of comments", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string" }, "videoTitle": { "type": "string" }, "sort": { "type": "string" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "string" }, "authorChannelId": { "type": "string" }, "likeCount": { "type": "integer" }, "publishedTime": { "type": "string" } }, "required": [ "id", "text", "author", "authorChannelId", "likeCount", "publishedTime" ] } }, "pagination": { "type": "object", "properties": { "totalComments": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "totalComments", "hasMore" ] }, "metadata": { "type": "object", "properties": { "commentsDisabled": { "type": "boolean" } }, "required": [ "commentsDisabled" ] } }, "required": [ "videoId", "videoTitle", "sort", "comments", "pagination", "metadata" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/transcript": { "get": { "operationId": "youtube.transcript", "summary": "Get video transcript", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "description": "YouTube video ID (aliases: videoId, id)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "description": "YouTube video ID (aliases: video_id, id)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "id", "in": "query", "description": "YouTube video ID (aliases: video_id, videoId)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "language", "in": "query", "description": "Transcript language code or name (alias: lang).", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "lang", "in": "query", "description": "Transcript language code or name (alias: language).", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "hl", "in": "query", "description": "Language code for localized upstream video info lookups (e.g., en).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Country code for localized upstream video info lookups (e.g., US).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string" }, "language": { "type": [ "string", "null" ] }, "languageName": { "type": [ "string", "null" ] }, "sourceLanguage": { "type": [ "string", "null" ] }, "sourceLanguageName": { "type": [ "string", "null" ] }, "isAutoGenerated": { "type": "boolean" }, "isTranslated": { "type": "boolean" }, "availableLanguages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "name": { "type": "string" }, "isAutoGenerated": { "type": "boolean" }, "isTranslatable": { "type": "boolean" } }, "required": [ "language", "name", "isAutoGenerated", "isTranslatable" ] } }, "translationLanguages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "name": { "type": "string" } }, "required": [ "language", "name" ] } }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "startMs": { "type": "integer" }, "durationMs": { "type": "integer" }, "endMs": { "type": "integer" }, "startTime": { "type": "integer" } }, "required": [ "text", "startMs", "durationMs", "endMs", "startTime" ] } }, "text": { "type": "string" } }, "required": [ "videoId", "language", "languageName", "sourceLanguage", "sourceLanguageName", "isAutoGenerated", "isTranslated", "availableLanguages", "translationLanguages", "transcript", "text" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/related": { "get": { "operationId": "youtube.related", "summary": "Get related videos", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "required": true, "description": "YouTube video ID", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "limit", "in": "query", "description": "Number of videos (default: 20, max: 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string" }, "count": { "type": "integer" }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": "string" }, "duration": { "type": "string" }, "viewCount": { "type": "string" }, "publishedTime": { "type": "string" }, "channel": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "thumbnail": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "required": [ "id", "name", "thumbnail", "verified" ] }, "badges": { "type": "array", "items": { "type": "string" } }, "isLive": { "type": "boolean" } }, "required": [ "id", "title", "thumbnail", "duration", "viewCount", "publishedTime", "channel", "badges", "isLive" ] } } }, "required": [ "videoId", "count", "videos" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/chapters": { "get": { "operationId": "youtube.chapters", "summary": "Get video chapters", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "description": "YouTube video ID", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "description": "YouTube video ID (11 characters). Alias for video_id.", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string" }, "hasChapters": { "type": "boolean" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "startTime": { "type": "integer" }, "startTimeMillis": { "type": "integer" }, "thumbnail": { "type": [ "string", "null" ] } }, "required": [ "title", "startTime", "startTimeMillis", "thumbnail" ] } } }, "required": [ "videoId", "hasChapters", "chapters" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/channel": { "get": { "operationId": "youtube.channel", "summary": "Get channel info", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "description": "YouTube channel ID (alias: channelId)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "description": "YouTube channel ID (alias: channel_id)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "subscriberCount": { "type": "string" }, "videoCount": { "type": [ "string", "null" ] }, "viewCount": { "type": [ "string", "null" ] }, "thumbnail": { "type": "string" }, "banner": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" }, "joinedDate": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "subscriberCount", "videoCount", "viewCount", "thumbnail", "banner", "country", "verified", "joinedDate" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/channel-videos": { "get": { "operationId": "youtube.channel-videos", "summary": "Get channel videos", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "description": "YouTube channel ID (alias: channelId)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "description": "YouTube channel ID (alias: channel_id)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Number of videos (default: 10, max: 30)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "page", "in": "query", "description": "Page number (default: 1, max: 10)", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "sort", "in": "query", "description": "Sort order: newest, popular, oldest (default: newest)", "schema": { "type": "string", "enum": [ "newest", "popular", "oldest" ] } }, { "name": "continuation", "in": "query", "description": "Token for pagination from previous response", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "channelId": { "type": "string" }, "sort": { "type": "string" }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "thumbnail": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "viewCount": { "type": [ "string", "null" ] }, "publishedTime": { "type": [ "string", "null" ] }, "isLive": { "type": "boolean" }, "isShort": { "type": "boolean" } }, "required": [ "id", "title", "description", "thumbnail", "duration", "viewCount", "publishedTime", "isLive", "isShort" ] } }, "pagination": { "type": "object", "properties": { "continuationToken": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } } }, "required": [ "channelId", "sort", "videos", "pagination" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/channel-playlists": { "get": { "operationId": "youtube.channel-playlists", "summary": "Get channel playlists", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "description": "YouTube channel ID (alias: channelId)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "description": "YouTube channel ID (alias: channel_id)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "channelId": { "type": "string" }, "playlists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "videoCount": { "type": "integer" }, "thumbnail": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "videoCount", "thumbnail" ] } }, "pagination": { "type": "object", "properties": { "continuationToken": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "continuationToken", "hasMore" ] } }, "required": [ "channelId", "playlists", "pagination" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/channel-community": { "get": { "operationId": "youtube.channel-community", "summary": "Get channel community posts", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "description": "YouTube channel ID (alias: channelId)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "description": "YouTube channel ID (alias: channel_id)", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "continuation", "in": "query", "description": "Token for pagination from previous response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "channelId": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "publishedTime": { "type": "string" }, "likeCount": { "type": "integer" }, "commentCount": { "type": "integer" }, "images": { "type": [ "array", "null" ], "items": { "type": "string" } }, "author": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "channelId": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "name", "channelId", "thumbnail" ] }, "poll": { "type": [ "object", "null" ], "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "votePercentage": { "type": "integer" } }, "required": [ "text", "votePercentage" ] } }, "totalVotes": { "type": "integer" } }, "required": [ "choices", "totalVotes" ] }, "video": { "type": [ "object", "null" ], "properties": { "videoId": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": "string" }, "duration": { "type": "string" }, "viewCount": { "type": "string" } }, "required": [ "videoId", "title", "thumbnail", "duration", "viewCount" ] }, "playlist": { "type": [ "object", "null" ], "properties": { "playlistId": { "type": "string" }, "title": { "type": "string" }, "videoCount": { "type": "integer" }, "thumbnail": { "type": "string" } }, "required": [ "playlistId", "title", "videoCount", "thumbnail" ] } }, "required": [ "id", "text", "publishedTime", "likeCount", "commentCount", "images", "author", "poll", "video", "playlist" ] } }, "pagination": { "type": "object", "properties": { "continuationToken": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "continuationToken", "hasMore" ] } }, "required": [ "channelId", "posts", "pagination" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/playlist": { "get": { "operationId": "youtube.playlist", "summary": "Get playlist details", "tags": [ "YouTube" ], "parameters": [ { "name": "playlist_id", "in": "query", "required": true, "description": "YouTube playlist ID", "schema": { "type": "string", "minLength": 3, "maxLength": 200 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "playlistId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "videoCount": { "type": "integer" }, "viewCount": { "type": [ "string", "null" ] }, "publishedTime": { "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "name": { "type": "string" }, "channelId": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "name", "channelId", "thumbnail" ] }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": "string" }, "duration": { "type": "string" }, "viewCount": { "type": [ "string", "null" ] }, "publishedTime": { "type": [ "string", "null" ] }, "channel": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "isLive": { "type": "boolean" }, "isShort": { "type": "boolean" } }, "required": [ "id", "title", "thumbnail", "duration", "viewCount", "publishedTime", "channel", "isLive", "isShort" ] } }, "pagination": { "type": "object", "properties": { "continuationToken": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "continuationToken", "hasMore" ] } }, "required": [ "playlistId", "title", "description", "videoCount", "viewCount", "publishedTime", "author", "videos", "pagination" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/trending": { "get": { "operationId": "youtube.trending", "summary": "Get trending videos", "tags": [ "YouTube" ], "parameters": [ { "name": "type", "in": "query", "description": "Trending category: now, music, gaming, movies", "schema": { "type": "string", "enum": [ "now", "music", "gaming", "movies" ] } }, { "name": "gl", "in": "query", "description": "Country code (e.g., US, DE)", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "description": "Language code (e.g., en)", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "continuation", "in": "query", "description": "Continuation token from a previous response, used to fetch the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "thumbnail": { "type": "string" }, "duration": { "type": "string" }, "viewCount": { "type": "string" }, "publishedTime": { "type": "string" }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "thumbnail": { "type": "string" }, "verified": { "type": "boolean" }, "isVerifiedArtist": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "id", "name", "thumbnail", "verified", "isVerifiedArtist", "url" ] }, "badges": { "type": "array", "items": { "type": "string" } }, "isLive": { "type": "boolean" }, "isShort": { "type": "boolean" }, "isPremium": { "type": "boolean" }, "expandableMetadata": {} }, "required": [ "type", "id", "title", "description", "thumbnail", "duration", "viewCount", "publishedTime", "channel", "badges", "isLive", "isShort", "isPremium", "expandableMetadata" ] } }, "pagination": { "type": "object", "properties": { "continuationToken": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "required": [ "continuationToken", "hasMore" ] }, "query": { "type": "string" }, "filters": { "type": "object", "properties": { "type": { "type": "string" }, "sort": { "type": "string" }, "hl": { "type": [ "string", "null" ] }, "gl": { "type": [ "string", "null" ] } }, "required": [ "type", "sort", "hl", "gl" ] }, "type": { "type": "string" }, "source": { "type": "string" }, "locale": { "type": "object", "properties": { "hl": { "type": "string" }, "gl": { "type": "string" } }, "required": [ "hl", "gl" ] } }, "required": [ "results", "pagination", "query", "filters", "type", "source", "locale" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "400": { "summary": "Validation failed - type must be one of: now, music, gaming, movies; gl must be a 2-letter country code; hl must be a 2-letter language code", "value": { "message": "Validation failed - type must be one of: now, music, gaming, movies; gl must be a 2-letter country code; hl must be a 2-letter language code" } } } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/youtube/{videoId}/transcript": { "get": { "operationId": "youtube.transcript-by-video", "summary": "Get video transcript", "tags": [ "YouTube" ], "parameters": [ { "name": "videoId", "in": "path", "required": true, "description": "YouTube video ID (aliases: video_id, id)", "schema": { "type": "string" } }, { "name": "video_id", "in": "query", "description": "YouTube video ID (aliases: videoId, id)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "id", "in": "query", "description": "YouTube video ID (aliases: video_id, videoId)", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "language", "in": "query", "description": "Transcript language code or name (alias: lang).", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "lang", "in": "query", "description": "Transcript language code or name (alias: language).", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "hl", "in": "query", "description": "Language code for localized upstream video info lookups (e.g., en).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "description": "Country code for localized upstream video info lookups (e.g., US).", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string" }, "language": { "type": [ "string", "null" ] }, "languageName": { "type": [ "string", "null" ] }, "sourceLanguage": { "type": [ "string", "null" ] }, "sourceLanguageName": { "type": [ "string", "null" ] }, "isAutoGenerated": { "type": "boolean" }, "isTranslated": { "type": "boolean" }, "availableLanguages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "name": { "type": "string" }, "isAutoGenerated": { "type": "boolean" }, "isTranslatable": { "type": "boolean" } }, "required": [ "language", "name", "isAutoGenerated", "isTranslatable" ] } }, "translationLanguages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "name": { "type": "string" } }, "required": [ "language", "name" ] } }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "startMs": { "type": "integer" }, "durationMs": { "type": "integer" }, "endMs": { "type": "integer" }, "startTime": { "type": "integer" } }, "required": [ "text", "startMs", "durationMs", "endMs", "startTime" ] } }, "text": { "type": "string" } }, "required": [ "videoId", "language", "languageName", "sourceLanguage", "sourceLanguageName", "isAutoGenerated", "isTranslated", "availableLanguages", "translationLanguages", "transcript", "text" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/zapier/oauth/token": { "post": { "operationId": "zapier.oauth.token", "tags": [ "ZapierOAuth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code" ] }, "code": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "required": [ "grant_type", "code", "redirect_uri", "client_id", "client_secret" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "scope": { "type": "string", "const": "api" }, "user_id": { "type": "string" }, "account_name": { "type": "string" } }, "required": [ "access_token", "token_type", "scope", "user_id", "account_name" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "invalid_grant" }, "error_description": { "type": "string", "const": "The authorization code is invalid or expired." } }, "required": [ "error", "error_description" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "invalid_client" }, "error_description": { "type": "string", "const": "Invalid Zapier OAuth client credentials." } }, "required": [ "error", "error_description" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "server_error" }, "error_description": { "type": "string", "const": "Zapier OAuth is not configured." } }, "required": [ "error", "error_description" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "BookingBulkPricesRequest": { "type": "object", "properties": { "debug": { "type": "string" }, "searches": { "type": "array", "items": { "type": "object", "properties": { "ss": { "type": "string", "minLength": 2, "maxLength": 200 }, "checkin": { "type": "string", "format": "date" }, "checkout": { "type": "string", "format": "date" }, "group_adults": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 }, "group_children": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20 }, "no_rooms": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 }, "dest_id": { "type": [ "integer", "null" ] }, "dest_type": { "type": [ "string", "null" ], "enum": [ "city", "region", "district", "hotel", "landmark", "airport" ] }, "lang": { "type": [ "string", "null" ], "maxLength": 10 }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, "required": [ "ss", "checkin", "checkout" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "searches" ], "title": "BookingBulkPricesRequest" }, "IdealistaDeeplinkBuildRequest": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] }, "location_id": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 }, "operation": { "type": [ "string", "null" ], "enum": [ "sale", "rent" ] }, "property_type": { "type": [ "string", "null" ], "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] }, "locale": { "type": [ "string", "null" ], "maxLength": 8 } }, "required": [ "country", "location_id" ], "title": "IdealistaDeeplinkBuildRequest" }, "IdealistaMapSimplifyRequest": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] }, "shape": { "type": "string" } }, "required": [ "country", "shape" ], "title": "IdealistaMapSimplifyRequest" }, "IdealistaShorturisRequest": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "es", "it", "pt", "fr" ] }, "direction": { "type": "string", "enum": [ "encode", "decode" ] }, "location_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._-]+$", "maxLength": 80 }, "operation": { "type": [ "string", "null" ], "enum": [ "sale", "rent" ] }, "property_type": { "type": [ "string", "null" ], "enum": [ "homes", "newDevelopments", "bedrooms", "offices", "premises", "transfers", "buildings", "storageRooms", "garages", "vacationRentals", "luxury", "lands" ] }, "locale": { "type": [ "string", "null" ], "maxLength": 8 }, "short_uris": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 40 }, "minItems": 1, "maxItems": 20 } }, "required": [ "country", "direction" ], "title": "IdealistaShorturisRequest" }, "SemrushContentBlogpostRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 3, "maxLength": 500 } }, "required": [ "text" ], "title": "SemrushContentBlogpostRequest" }, "SemrushContentRewriteRequest": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "paragraph-rewriter", "sentence-rewriter", "paraphrase-generator" ] }, "category": { "type": "string", "enum": [ "improve", "simplify", "summarize" ] }, "text": { "type": "string", "minLength": 3, "maxLength": 5000 } }, "required": [ "tool", "category", "text" ], "title": "SemrushContentRewriteRequest" }, "SemrushContentSummarizeRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 50, "maxLength": 10000 }, "length_penalty": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "format": { "type": [ "string", "null" ], "enum": [ "paragraph", "bullets" ] } }, "required": [ "text" ], "title": "SemrushContentSummarizeRequest" }, "SemrushContentTitlesRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 3, "maxLength": 500 } }, "required": [ "text" ], "title": "SemrushContentTitlesRequest" }, "SemrushReviewQrRequest": { "type": "object", "properties": { "business_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "place_id": { "type": "string", "pattern": "^[A-Za-z0-9_+-]+$", "minLength": 5, "maxLength": 255 } }, "required": [ "business_name", "place_id" ], "title": "SemrushReviewQrRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }