{ "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": "Pinterest API" }, { "name": "Startpage Search" }, { "name": "TikTok API" }, { "name": "Google Patents 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": "Brave Search", "description": "Brave Search API endpoints" }, { "name": "ImmobilienScout24", "description": "ImmobilienScout24 real estate API" } ], "security": [ { "apiKey": [] } ], "paths": { "\/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", "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": "Date filters - format: type:YYYYMMDD (e.g., \"filing:20231231\", \"publication:20230101\")", "schema": { "type": [ "string", "null" ], "pattern": "^(filing|publication|priority):\\d{8}$" } }, { "name": "after", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^(filing|publication|priority):\\d{8}$" } }, { "name": "country", "in": "query", "description": "Filters", "schema": { "type": [ "string", "null" ] } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "GRANT", "APPLICATION" ] } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "PATENT", "DESIGN" ] } }, { "name": "inventor", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "assignee", "in": "query", "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": { "$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-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": { "$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" } }, { "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" } }, { "name": "bookmark", "in": "query", "description": "Pagination token from a previous response.", "schema": { "type": "string" } } ], "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, "schema": { "type": "string", "maxLength": 500 } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "english", "deutsch", "french", "spanish", "italian", "portuguese", "dutch", "russian", "chinese", "japanese", "arabic", "all" ] } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10 } }, { "name": "safe_search", "in": "query", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "service": { "type": "string", "enum": [ "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": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "url": { "type": "string" }, "domain": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "integer" }, { "type": "object" }, { "type": "string", "enum": [ "" ] } ] }, "position": { "type": "integer", "enum": [ 1 ] } }, "required": [ "title", "description", "url", "domain", "position" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "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": "string", "description": "Startpage doesn't have this" }, "source": { "type": "string", "enum": [ "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": { "type": "string" } }, "required": [ "html" ] } ] } } } }, "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\/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, "schema": { "type": "string", "maxLength": 500 } }, { "name": "hd", "in": "query", "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, "schema": { "type": "string", "maxLength": 255 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 35 } }, { "name": "cursor", "in": "query", "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\/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", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "time", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "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", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "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", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "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, "schema": { "type": "string", "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 35 } }, { "name": "cursor", "in": "query", "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, "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, "schema": { "type": "string", "maxLength": 255 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "region", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "publish_time", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "sort_type", "in": "query", "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, "schema": { "type": "string", "maxLength": 10 } }, { "name": "count", "in": "query", "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, "schema": { "type": "string", "maxLength": 500 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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, "schema": { "type": "string", "maxLength": 100 } }, { "name": "video_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "challenge_name", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "region", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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, "schema": { "type": "string", "maxLength": 255 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "challenge_name", "in": "query", "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, "schema": { "type": "string", "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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, "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", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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, "schema": { "type": "string", "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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, "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", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "user_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "count", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "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, "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" ] } } } } } } }, "\/debugger": { "get": { "operationId": "api-debugger.debugger", "summary": "Get all API debugger endpoints configuration", "tags": [ "ApiDebugger" ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "enum": [ "Failed to load API debugger configuration" ] }, "error": { "type": "string", "enum": [ "An internal error occurred. Please try again later." ] } }, "required": [ "success", "message", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "enum": [ "Failed to load API debugger configuration" ] }, "error": { "type": "string", "enum": [ "Configuration file not found or empty" ] } }, "required": [ "success", "message", "error" ] } ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "endpoints": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "route": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "request_class": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "route", "description", "request_class" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "key", "label", "description", "endpoints" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/debugger\/{group}": { "get": { "operationId": "api-debugger.debugger.group", "summary": "Get details for a specific API debugger group", "tags": [ "ApiDebugger" ], "parameters": [ { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "enum": [ "Failed to load API debugger configuration" ] }, "error": { "type": "string", "enum": [ "An internal error occurred. Please try again later." ] } }, "required": [ "success", "message", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "enum": [ "Failed to load API debugger configuration" ] }, "error": { "type": "string", "enum": [ "Configuration file not found or empty" ] } }, "required": [ "success", "message", "error" ] } ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "group": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "description" ] }, "endpoints": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "route": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "request_class": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "route", "description", "request_class" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "group", "endpoints" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/debugger\/{group}\/{endpoint}": { "get": { "operationId": "api-debugger.debugger.endpoint", "summary": "Get details for a specific API debugger endpoint", "tags": [ "ApiDebugger" ], "parameters": [ { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "enum": [ "Failed to load API debugger configuration" ] }, "error": { "type": "string", "enum": [ "An internal error occurred. Please try again later." ] } }, "required": [ "success", "message", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "enum": [ "Failed to load API debugger configuration" ] }, "error": { "type": "string", "enum": [ "Configuration file not found or empty" ] } }, "required": [ "success", "message", "error" ] } ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "group": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "description" ] }, "endpoint": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "route": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "request_class": { "type": [ "string", "null" ] }, "parameters": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "name": { "type": "string" }, "rules": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "rules", "required" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "key", "label", "route", "description", "request_class", "parameters" ] } }, "required": [ "group", "endpoint" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "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", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "suchwort", "in": "query", "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", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "wo", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "berufsfeld", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "arbeitgeber", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "angebotsart", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2", "4", "34" ] } }, { "name": "arbeitszeit", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^(vz|tz|snw|ho|mj)(;(vz|tz|snw|ho|mj))*$" } }, { "name": "befristung", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2" ] } }, { "name": "veroeffentlichtseit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "umkreis", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "10", "25", "50", "100", "150", "200" ] } }, { "name": "zeitarbeit", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "pav", "in": "query", "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": { "$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" ] } } } } } } }, "\/brave\/search": { "get": { "operationId": "brave.search", "summary": "Search using Brave Search", "tags": [ "Brave Search" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 500 } }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "en", "de", "fr", "es", "it", "pt", "nl", "ru", "zh", "ja", "ar", "all" ] } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } } ], "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" }, "redirect_link": { "type": [ "string", "null" ] }, "displayed_link": { "type": [ "string", "null" ] }, "snippet": { "type": [ "string", "null" ] }, "source": { "type": "string" } }, "required": [ "position", "title", "link", "redirect_link", "displayed_link", "snippet" ] } }, "search_information": { "type": "object", "properties": { "query_displayed": { "type": "string" } }, "required": [ "query_displayed" ] }, "related_searches": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "link": { "type": "string" } }, "required": [ "query", "link" ] } }, "people_also_search_for": { "type": "array", "items": {} }, "related_questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } }, "required": [ "question", "answer", "link", "title" ] } }, "things_to_know": { "type": "array", "items": {} }, "knowledge_graph": {}, "see_results_about": {}, "twitter_card": {}, "inline_videos": { "type": "array", "items": {} }, "inline_images": { "type": "array", "items": {} }, "local_map": {}, "local_results": {}, "popular_products": {}, "perspectives": { "type": "array", "items": {} }, "nutrition_information": {}, "refine_this_search": {}, "results_count": { "type": "integer" }, "engine_used": { "type": "string" } }, "required": [ "organic_results", "search_information", "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", "results_count", "engine_used" ] } } } }, "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" ] } } } } } } }, "\/email\/verify": { "post": { "operationId": "email.verify", "tags": [ "EmailVerification" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EmailVerifyRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": {}, "domain": { "anyOf": [ {}, { "type": "string" } ] }, "band": { "anyOf": [ {}, { "type": "string", "enum": [ "risky" ] } ] }, "score": {}, "code": { "type": "string" }, "role": { "type": "string", "enum": [ "true", "false" ] }, "free_email": { "type": "string", "enum": [ "true", "false" ] }, "result": { "type": "string" }, "reason": { "type": "string" }, "send_transactional": { "type": "string" }, "did_you_mean": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] } }, "required": [ "email", "domain", "band", "score", "code", "role", "free_email", "result", "reason", "send_transactional", "did_you_mean" ] } } } }, "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", "schema": { "type": [ "string", "null" ], "enum": [ "google_hotels" ] } }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "check_in_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "check_out_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "children", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6 } }, { "name": "currency", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "3", "8", "13" ] } }, { "name": "min_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "hotel_class", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "2", "3", "4", "5" ] } }, { "name": "free_cancellation", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "children_ages[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 17 } } }, { "name": "rating", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "7", "8", "9" ] } }, { "name": "amenities[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "vacation_rentals", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "eco_certified", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "special_offers", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "property_types[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "brands[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "bedrooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "bathrooms", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "next_page_token", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "property_token", "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" ] } } } } } } }, "\/google-hotels\/autocomplete": { "get": { "operationId": "google-hotels.autocomplete", "tags": [ "Google Hotels" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "currency", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "location", "hotel", "all" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "502": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Request failed" ] } ] } }, "required": [ "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" ] } } } } } } }, "\/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", "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", "schema": { "type": [ "string", "null" ], "enum": [ "photo", "clipart", "lineart", "gif", "face" ] } }, { "name": "imgcolor", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "color", "gray", "trans", "red", "orange", "yellow", "green", "teal", "blue", "purple", "pink", "white", "black", "brown" ] } }, { "name": "imgar", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "tall", "square", "wide" ] } }, { "name": "tbs", "in": "query", "description": "Advanced Filters", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "safe", "in": "query", "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": { "anyOf": [ { "type": "object" }, { "type": "array", "items": { "type": "string" } } ] } } } }, "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to parse data from JSEval." ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An unexpected error occurred during JSEval processing." ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Network error during JSEval API call." ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "JSEval API returned an error." ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "JSEval API execution failed." ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Google Images returned an empty response body." ] } }, "required": [ "error" ] } ] } } } }, "502": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Google Images request was blocked upstream." ] } }, "required": [ "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" ] } } } } } } }, "\/google\/jobs": { "get": { "operationId": "google-jobs.search", "summary": "Search for jobs", "tags": [ "Google Jobs" ], "parameters": [ { "name": "q", "in": "query", "description": "Required only if next_page_token is not provided", "schema": { "type": "string", "maxLength": 500 } }, { "name": "next_page_token", "in": "query", "description": "Pagination token", "schema": { "type": [ "string", "null" ] } }, { "name": "uule", "in": "query", "description": "Geographic Location", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "lrad", "in": "query", "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": "Date posted filter (days)", "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": "Language & Localization", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "google_domain", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "page", "in": "query", "description": "Pagination - Google Jobs uses next_page_token, not page", "schema": { "type": "string" } } ], "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" ] } } } } } } }, "\/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": "Support both 'q' and 'query' parameters for consistency with other autocomplete endpoints\nThe prepareForValidation method ensures 'query' is always set if 'q' is provided", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "ll", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.?\\d*,-?\\d+\\.?\\d*$" } }, { "name": "google_domain", "in": "query", "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": { "$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\/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, "schema": { "type": "string" } }, { "name": "lon", "in": "query", "schema": { "type": [ "number", "null" ] } }, { "name": "lat", "in": "query", "schema": { "type": [ "number", "null" ] } }, { "name": "zoom", "in": "query", "required": true, "schema": { "type": "number", "minimum": 3, "maximum": 21 } }, { "name": "limit", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "google_domain", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^google\\.(?:[a-z]{2}|com|com\\.[a-z]{2}|co\\.[a-z]{2})$", "maxLength": 100 } }, { "name": "fields", "in": "query", "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": { "$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\/advance-search": { "get": { "operationId": "google-maps-api.advance-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, "schema": { "type": "string" } }, { "name": "lon", "in": "query", "schema": { "type": [ "number", "null" ] } }, { "name": "lat", "in": "query", "schema": { "type": [ "number", "null" ] } }, { "name": "zoom", "in": "query", "required": true, "schema": { "type": "number", "minimum": 3, "maximum": 21 } }, { "name": "limit", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "google_domain", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^google\\.(?:[a-z]{2}|com|com\\.[a-z]{2}|co\\.[a-z]{2})$", "maxLength": 100 } }, { "name": "fields", "in": "query", "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": { "$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\/business": { "get": { "operationId": "google-maps-api.business-info", "description": "INTENTIONALLY PRIVATE - Not exposed in docs or playground.\nThis endpoint returns cached business information from the local database only.\nIt does NOT make live requests to Google Maps.\n\nFor live data from Google Maps, use getBusinessDetails() instead.\n\nRetrieve business information from the local database.", "summary": "Get Business Info", "tags": [ "Google Maps" ], "parameters": [ { "name": "business_id", "in": "query", "required": true, "description": "Accepts both google_id format (0x...:0x...) and place_id format (ChIJ...)", "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", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "business_id": { "type": "string" }, "place_id": { "type": [ "string", "null" ] }, "rating": { "type": [ "number", "null" ] }, "review_count": { "type": [ "integer", "null" ] }, "price_level": { "type": [ "string", "null" ] }, "price_level_text": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "phone_numbers": { "type": [ "array", "null" ], "items": { "type": "string" } }, "full_address": { "type": [ "string", "null" ] }, "street_address_alt": { "type": [ "string", "null" ] }, "street_address_full": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "neighborhood": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "subtypes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "type": { "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" ] }, "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", "null" ], "items": { "type": "object", "properties": { "photo_id": { "type": "string" }, "photo_url": { "type": "string" } }, "required": [ "photo_id", "photo_url" ] } }, "attributes": { "type": [ "array", "null" ], "items": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "business_id", "place_id", "rating", "review_count", "price_level", "price_level_text", "website", "domain", "phone_numbers", "full_address", "street_address_alt", "street_address_full", "district", "neighborhood", "city", "state", "zip_code", "country_code", "latitude", "longitude", "timezone", "subtypes", "type", "short_description", "full_description", "owner_id", "owner_name", "owner_link", "order_link", "google_mid", "opening_hours", "current_status", "photos_sample", "attributes", "created_at", "updated_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" ] } } } } } } }, "\/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": "Accepts both google_id format (0x...:0x...) and place_id format (ChIJ...)", "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", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "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" ] }, "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 }, "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", "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", "photo_count", "about", "address", "menu_link", "order_link", "price_level", "district", "street_address", "city", "zipcode", "state", "country", "emails_and_contacts", "share_link" ] } } } } }, "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\/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": "Accepts both google_id format (0x...:0x...) and place_id format (ChIJ...)", "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", "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "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": "Accepts both google_id format (0x...:0x...) and place_id format (ChIJ...)", "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", "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "sort", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "2", "3", "4" ] } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "pages", "in": "query", "description": "Number of pages to fetch in a single request (1-50). Each page counts as one API credit. When pages > 1, response includes pages_fetched, pages_requested, and error fields.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } } ], "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_link": { "type": [ "string", "null" ] }, "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": [ "string", "null" ] }, "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_link", "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" ] }, "pages_fetched": { "type": [ "integer", "null" ] }, "pages_requested": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "items", "nextPage", "pages_fetched", "pages_requested", "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" ] } } } } } } }, "\/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, "schema": { "type": "string", "pattern": "^C[A-Za-z0-9_-]+$", "minLength": 10, "maxLength": 100 } }, { "name": "business_id", "in": "query", "required": true, "description": "Accepts both google_id format (0x...:0x...) and place_id format (ChIJ...)", "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": { "$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\/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, "schema": { "type": "string" } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "google_domain", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^google\\.(?:[a-z]{2}|com|com\\.[a-z]{2}|co\\.[a-z]{2})$", "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "fields", "in": "query", "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": { "$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\/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, "schema": { "type": "string", "minLength": 2, "maxLength": 500 } }, { "name": "destination", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 500 } }, { "name": "mode", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "driving", "walking", "bicycling", "transit" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "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": { "$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" ] } } } } } } }, "\/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 (5 params)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uule", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "google_domain", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "cr", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "hl", "in": "query", "description": "Language & Localization (2 params)", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "lr", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "ludocid", "in": "query", "description": "Advanced Google Parameters (6 params)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "lsig", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "kgmid", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "si", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "ibp", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "uds", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "tbs", "in": "query", "description": "Search Filters & Safety (5 params)", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "as_qdr", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "safe", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "nfpr", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "filter", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "tbm", "in": "query", "description": "Search Type & Pagination (3 params)", "schema": { "type": [ "string", "null" ], "enum": [ "isch", "vid", "nws", "lcl", "shop", "pts" ] } }, { "name": "start", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "description": "Backward Compatible (2 params)", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "amount", "in": "query", "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" }, "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": "string" } }, "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": [ "array", "null" ], "items": { "type": "object", "additionalProperties": {} } }, "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": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/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.\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": "Pagination\npage and start are mutually exclusive - use page for easier pagination (1-based)\nor start for direct offset control (0-based)\nMax start is 170 because Google CSE API has a hard limit where offset + num must not exceed 190", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "start", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 170 } }, { "name": "page", "in": "query", "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", "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", "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", "schema": { "type": [ "string", "null" ], "enum": [ "date", "date:r", "date:d" ] } }, { "name": "filter", "in": "query", "description": "Content filtering (only params that can't be set via query modifiers)\nNOTE: fileType, exactTerms, siteSearch removed - use query modifiers instead:\nfiletype:pdf, \"exact phrase\", site:domain.com", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "rights", "in": "query", "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": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/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, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "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": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/google-translate": { "get": { "operationId": "google-translate-api.translate", "summary": "Translate text between languages", "tags": [ "Google Translate" ], "parameters": [ { "name": "source", "in": "query", "required": true, "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, "schema": { "type": "string", "minLength": 1 } }, { "name": "target", "in": "query", "required": true, "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, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "geo", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "time_range", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "1h", "4h", "1d", "7d", "30d", "90d", "1y", "5y", "all" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "search_type", "in": "query", "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": "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": "Bad Gateway - Google Trends upstream request failed", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "geo", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "time_range", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "1h", "4h", "1d", "7d", "30d", "90d", "1y", "5y", "all" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "search_type", "in": "query", "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": "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": "Bad Gateway - Google Trends upstream request failed", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "geo", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "hl", "in": "query", "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": "Bad Gateway - Google Trends upstream request failed", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "hl", "in": "query", "description": "Keep consistent with other Google Finance requests.", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch search results" ] }, "code": { "type": "string", "enum": [ "SERVICE_ERROR" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "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", "enum": [ "No results found for the given query" ] }, "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "status": { "type": "integer", "enum": [ 404 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Rate limit exceeded. Please try again later." ] }, "code": { "type": "string", "enum": [ "RATE_LIMITED" ] }, "status": { "type": "integer", "enum": [ 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": "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", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "exchange", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "period_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "quarterly", "annual" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(-[a-z]{2})?$", "maxLength": 10 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}$", "maxLength": 10 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch quote" ] }, "code": { "type": "string", "enum": [ "SERVICE_ERROR" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "params": { "type": "array", "items": {} }, "headers": { "type": "object", "properties": { "Accept": { "type": "string", "enum": [ "application\/json" ] }, "X-API-KEY": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "[missing]" ] } ] } }, "required": [ "Accept", "X-API-KEY" ] } }, "required": [ "method", "url", "params", "headers" ] }, "response": { "type": "object", "properties": { "status_code": { "type": "integer", "enum": [ 500 ] }, "duration_ms": { "type": "integer" } }, "required": [ "status_code", "duration_ms" ] }, "error_details": { "type": "object", "properties": { "symbol": { "type": "string" }, "exchange": { "type": [ "string", "null" ] }, "exception": { "type": "string" } }, "required": [ "symbol", "exchange", "exception" ] } }, "required": [ "request", "response", "error_details" ] }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "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" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Rate limit exceeded. Please try again later." ] }, "code": { "type": "string", "enum": [ "RATE_LIMITED" ] }, "status": { "type": "integer", "enum": [ 429 ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "params": { "type": "array", "items": {} }, "headers": { "type": "object", "properties": { "Accept": { "type": "string", "enum": [ "application\/json" ] }, "X-API-KEY": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "[missing]" ] } ] } }, "required": [ "Accept", "X-API-KEY" ] } }, "required": [ "method", "url", "params", "headers" ] }, "response": { "type": "object", "properties": { "status_code": { "type": "integer", "enum": [ 429 ] }, "duration_ms": { "type": "integer" } }, "required": [ "status_code", "duration_ms" ] }, "error_details": { "type": "object", "properties": { "symbol": { "type": "string" }, "exchange": { "type": [ "string", "null" ] }, "attempt": { "type": "integer", "enum": [ 0 ] } }, "required": [ "symbol", "exchange", "attempt" ] } }, "required": [ "request", "response", "error_details" ] }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "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": "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", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "exchange", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "range", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 8 } }, { "name": "start_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "end_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "interval", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch historical data" ] }, "code": { "type": "string", "enum": [ "SERVICE_ERROR" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "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", "enum": [ "No historical data found for the given symbol" ] }, "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "status": { "type": "integer", "enum": [ 404 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Rate limit exceeded. Please try again later." ] }, "code": { "type": "string", "enum": [ "RATE_LIMITED" ] }, "status": { "type": "integer", "enum": [ 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": "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", "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", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "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": "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", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "exchange", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch intraday data" ] }, "code": { "type": "string", "enum": [ "SERVICE_ERROR" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "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" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "No intraday data found for the given symbol" ] }, "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "status": { "type": "integer", "enum": [ 404 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Rate limit exceeded. Please try again later." ] }, "code": { "type": "string", "enum": [ "RATE_LIMITED" ] }, "status": { "type": "integer", "enum": [ 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": "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", "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", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 10 } }, { "name": "trend", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "indexes", "most-active", "gainers", "losers", "climate-leaders", "cryptocurrencies", "currencies" ] } }, { "name": "index_market", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "americas", "europe-middle-east-africa", "asia-pacific" ] } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch markets data" ] }, "code": { "type": "string", "enum": [ "SERVICE_ERROR" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "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": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "No markets data found" ] }, "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "status": { "type": "integer", "enum": [ 404 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Rate limit exceeded. Please try again later." ] }, "code": { "type": "string", "enum": [ "RATE_LIMITED" ] }, "status": { "type": "integer", "enum": [ 429 ] }, "_debug": { "type": "string" } }, "required": [ "error", "code", "status", "_debug" ] } } } }, "502": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch markets data" ] }, "code": { "type": "string", "enum": [ "SERVICE_ERROR" ] }, "status": { "type": "integer", "enum": [ 502 ] }, "_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": "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", "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, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "adults", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "exclude_basic", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "max_stops", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "any", "nonstop", "one_or_fewer", "two_or_fewer" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "departure_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "top_flights", "cheapest", "departure_time", "arrival_time", "duration" ] } }, { "name": "airlines[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2 } } }, { "name": "include_baggage", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "departure_time_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "departure_time_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "max_duration_minutes", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "max_price", "in": "query", "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": { "$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\/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, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "adults", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "exclude_basic", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "max_stops", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "any", "nonstop", "one_or_fewer", "two_or_fewer" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "departure_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "return_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "top_flights", "cheapest", "departure_time", "arrival_time", "duration" ] } }, { "name": "airlines[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2 } } }, { "name": "include_baggage", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "departure_time_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "departure_time_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "arrival_time_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 } }, { "name": "max_duration_minutes", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "max_price", "in": "query", "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, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "adults", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "exclude_basic", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "max_stops", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "any", "nonstop", "one_or_fewer", "two_or_fewer" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } }, { "name": "from_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "trip_duration", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "currency", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } ], "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": { "$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\/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": "Required booking parameters", "schema": { "type": "string" } }, { "name": "origin", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "destination", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3}$", "minLength": 3, "maxLength": 3 } }, { "name": "departure_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "airline", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2 } }, { "name": "flight_number", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "adults", "in": "query", "description": "Passenger counts", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9 } }, { "name": "children", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_in_seat", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "infants_on_lap", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9 } }, { "name": "cabin_class", "in": "query", "description": "Flight preferences", "schema": { "type": [ "string", "null" ], "enum": [ "economy", "premium_economy", "business", "first" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$" } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z]{2}$" } } ], "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": { "$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\/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": "google_domain", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "description": "Language & Localization", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "tbs", "in": "query", "description": "Advanced Filters", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "safe", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "active", "off" ] } }, { "name": "nfpr", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "filter", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "start", "in": "query", "description": "Pagination", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "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": "lr", "in": "query", "description": "Language restriction (e.g., lang_en for English-only results).", "schema": { "type": [ "string", "null" ], "maxLength": 200 } } ], "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": { "$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, "schema": { "type": "string", "maxLength": 255 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "apartment-rent", "apartment-buy", "house-rent", "house-buy" ] } }, { "name": "price_min", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "price_max", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "rooms_min", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "rooms_max", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "size_min", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "size_max", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "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, "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, "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "limit", "in": "query", "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, "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, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "apartment-rent", "apartment-buy", "house-rent", "house-buy" ] } }, { "name": "price_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "price_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "rooms_min", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "rooms_max", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "size_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "size_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "per_page", "in": "query", "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", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "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": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 0 ] } ] }, "results": { "type": "array", "prefixItems": [ { "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" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "success", "total_results", "page", "total_pages", "results" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "Failed to fetch search results" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] }, "message": { "type": "string", "enum": [ "Upstream rate limit exceeded" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "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, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "limit", "in": "query", "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", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "Location request failed" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "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", "enum": [ "coordinates" ] }, "postal_code": { "type": "null" }, "full_name": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_km": { "type": "integer", "enum": [ 10 ] }, "source": { "type": "string", "enum": [ "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", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "Location request failed" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "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", "enum": [ "coordinates" ] }, "postal_code": { "type": "null" }, "full_name": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "radius_km": { "type": "integer", "enum": [ 10 ] }, "source": { "type": "string", "enum": [ "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, "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", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string", "enum": [ "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, "schema": { "type": "string", "pattern": "^AD[0-9]{2}[A-Z]{2}[0-9]{1,6}$" } }, { "name": "distribution", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "Rent", "Buy" ] } }, { "name": "estate_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "Apartment", "House" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "Count request failed" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "total_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "raw": {} }, "required": [ "success", "total_count", "raw" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "Immowelt count failed" ] }, "http_status": { "type": "integer" } }, "required": [ "code", "message", "http_status" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_LOCATION" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "Places data request failed" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "places": { "type": "array", "prefixItems": [ { "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": { "anyOf": [ { "type": "string" }, { "type": [ "string", "null" ] } ] }, "lon": { "anyOf": [ { "type": "string" }, { "type": [ "string", "null" ] } ] }, "full_name": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "immowelt_bff" ] } }, "required": [ "id", "name", "type", "postal_codes", "lat", "lon", "full_name", "source" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "raw": {} }, "required": [ "success", "places", "raw" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "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\/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, "schema": { "type": "array", "items": { "type": "string", "pattern": "^AD[0-9]{2}[A-Z]{2}[0-9]{1,6}$" } } }, { "name": "parent_types[]", "in": "query", "required": true, "schema": { "type": "array", "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_ERROR" ] }, "message": { "type": "string", "enum": [ "Places data request failed" ] } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "places": { "type": "array", "prefixItems": [ { "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": { "anyOf": [ { "type": "string" }, { "type": [ "string", "null" ] } ] }, "lon": { "anyOf": [ { "type": "string" }, { "type": [ "string", "null" ] } ] }, "full_name": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "immowelt_bff" ] } }, "required": [ "id", "name", "type", "postal_codes", "lat", "lon", "full_name", "source" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "raw": {} }, "required": [ "success", "places", "raw" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "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, "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", "enum": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "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": [ "UPSTREAM_ERROR" ] }, "message": { "type": "string", "enum": [ "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, "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, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_]+(,[a-zA-Z0-9_]+)*$", "minLength": 1, "maxLength": 1000 } }, { "name": "language", "in": "query", "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, "schema": { "type": "string", "maxLength": 500 } }, { "name": "location", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "country", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "radius", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "radius_unit", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "MILES", "KILOMETERS" ] } }, { "name": "job_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "full_time", "part_time", "contract", "internship", "remote" ] } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "date" ] } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "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" }, "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", "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, "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" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "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", "posts", "posts_count", "more_available", "next_max_id" ] } } } }, "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\/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", "schema": { "type": "string", "pattern": "^https?:\\\/\\\/(www\\.)?instagram\\.com\\\/(?:[^\\\/]+\\\/)?(?:p|reel|tv)\\\/[A-Za-z0-9_-]+\\\/?(?:\\?.*)?$" } }, { "name": "shortcode", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "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", "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" ] } } } } } } }, "\/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" }, "example": "Zahnarzt" }, { "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" }, "example": "Berlin" }, { "name": "page", "in": "query", "description": "Page number (1-500)", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Results per page (1-28)", "schema": { "type": "integer" }, "example": 28 } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while processing the request" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch data from Jameda" ] }, "message": { "type": "string", "enum": [ "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", "enum": [ "Search results not found on Jameda" ] }, "message": { "type": "string", "enum": [ "No search results found for the given query on Jameda." ] }, "http_code": { "type": "integer", "enum": [ 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 }, "example": "\/meike-hutzenlaub\/orthopaede\/aachen" } ], "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": "limit", "in": "query", "schema": { "type": "string" } }, { "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 }, "example": "\/meike-hutzenlaub\/orthopaede\/aachen" }, { "name": "page", "in": "query", "description": "Page number (1-500)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Sort order applied locally to available reviews", "schema": { "type": [ "string", "null" ], "enum": [ "newest", "oldest", "highest", "lowest" ] }, "example": "newest" }, { "name": "rating", "in": "query", "description": "Filter by rating (1-5), comma-separated for multiple", "schema": { "type": [ "string", "null" ], "pattern": "^[1-5](,[1-5])*$" }, "example": "4,5" }, { "name": "per_page", "in": "query", "description": "Results per page (1-100) applied locally", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 10 } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while processing the reviews request" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] } } } }, "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" }, "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", "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" ] } }, "required": [ "sort", "rating" ] }, "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" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Doctor not found on Jameda" ] }, "message": { "type": "string", "enum": [ "The provided doctor URL does not exist on Jameda or the profile could not be parsed." ] }, "http_code": { "type": "integer", "enum": [ 404 ] } }, "required": [ "error", "message", "http_code" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Reviews for facilities are not supported" ] }, "message": { "type": "string", "enum": [ "The reviews endpoint currently only supports individual doctors, not facilities (gesundheitseinrichtungen). Please use a doctor profile URL instead." ] }, "http_code": { "type": "integer", "enum": [ 404 ] }, "entity_type": { "type": "string", "enum": [ "facility" ] } }, "required": [ "error", "message", "http_code", "entity_type" ] } ] } } } }, "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\/slots": { "get": { "operationId": "jameda.slots", "description": "This endpoint returns 410 Gone - the booking-service.jameda.de domain no longer exists.", "summary": "Get available appointment slots for a doctor", "deprecated": true, "tags": [ "Jameda" ], "parameters": [ { "name": "profile_id", "in": "query", "description": "Doctor profile ID (deprecated - new API uses doctor_id + address_id)", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "81157780" }, { "name": "service_id", "in": "query", "description": "Service ID (optional)", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "from", "in": "query", "description": "Start datetime in ISO8601 format", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "to", "in": "query", "description": "End datetime in ISO8601 format", "schema": { "type": [ "string", "null" ], "maxLength": 50 } }, { "name": "insuranceType", "in": "query", "description": "Filter by insurance type: statutory or private", "schema": { "type": [ "string", "null" ], "maxLength": 50 } } ], "responses": { "410": { "description": "Endpoint deprecated - Jameda booking API migrated to v3", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "migration_info": { "type": "object", "properties": { "new_api": { "type": "string" }, "required_params": { "type": "array", "items": { "type": "string" } }, "authentication": { "type": "string" }, "how_to_get_ids": { "type": "string" } }, "required": [ "new_api", "required_params", "authentication", "how_to_get_ids" ] } }, "required": [ "error", "message", "migration_info" ] } } } }, "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\/services": { "get": { "operationId": "jameda.services", "summary": "Get services offered by a doctor", "tags": [ "Jameda" ], "parameters": [ { "name": "profile_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } } ], "responses": { "410": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Gone" ] }, "message": { "type": "string", "enum": [ "This endpoint is deprecated. The booking-service.jameda.de domain no longer exists." ] }, "migration_info": { "type": "object", "properties": { "new_api": { "type": "string", "enum": [ "https:\/\/www.jameda.de\/api\/v3\/doctors\/{doctor_id}\/addresses\/{address_id}\/services\/calendar" ] }, "required_params": { "type": "array", "prefixItems": [ { "type": "string", "enum": [ "doctor_id" ] }, { "type": "string", "enum": [ "address_id" ] } ], "minItems": 2, "maxItems": 2, "additionalItems": false }, "authentication": { "type": "string", "enum": [ "OAuth bearer token required" ] }, "how_to_get_ids": { "type": "string", "enum": [ "Use the \/api\/jameda\/doctor-details endpoint to get booking_ids (doctor_id + address_id)" ] } }, "required": [ "new_api", "required_params", "authentication", "how_to_get_ids" ] } }, "required": [ "error", "message", "migration_info" ] } } } }, "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-location": { "get": { "operationId": "jameda.autocomplete-location", "summary": "Get location autocomplete suggestions", "tags": [ "Jameda" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while processing the request" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch location suggestions from Jameda" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "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", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "query", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while processing the request" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch service suggestions from Jameda" ] }, "message": { "type": "string", "enum": [ "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", "enum": [ "application\/json" ] }, "Accept-Language": { "type": "string", "enum": [ "de-DE,de;q=0.9,en;q=0.7" ] }, "User-Agent": { "type": "string", "enum": [ "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", "enum": [ "https:\/\/www.jameda.de" ] }, "Referer": { "type": "string", "enum": [ "https:\/\/www.jameda.de\/" ] } }, "required": [ "Accept", "Accept-Language", "User-Agent", "Origin", "Referer" ] }, "response_headers": { "type": "array", "items": {} }, "response_body": { "type": "string" }, "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", "enum": [ "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": { "type": "string" }, "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", "enum": [ "application\/json" ] }, "Accept-Language": { "type": "string", "enum": [ "de-DE,de;q=0.9,en;q=0.7" ] }, "User-Agent": { "type": "string", "enum": [ "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", "enum": [ "https:\/\/www.jameda.de" ] }, "Referer": { "type": "string", "enum": [ "https:\/\/www.jameda.de\/" ] } }, "required": [ "Accept", "Accept-Language", "User-Agent", "Origin", "Referer" ] }, "response_headers": { "type": "array", "items": {} }, "response_body": { "type": "string" }, "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" ] } } } } } } }, "\/kleinanzeigen\/search": { "get": { "operationId": "kleinanzeigen.search", "tags": [ "Kleinanzeigen" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "location", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "category", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "price_min", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "price_max", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while processing the search request" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch data from Kleinanzeigen" ] }, "message": { "type": "string", "enum": [ "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, "schema": { "type": "number", "minimum": 1 } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while fetching ad details" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch ad details from Kleinanzeigen" ] }, "message": { "type": "string", "enum": [ "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", "enum": [ "Ad not found" ] }, "message": { "type": "string", "enum": [ "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", "enum": [ "An error occurred while fetching shipping options" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to parse shipping options response" ] }, "message": { "type": "string", "enum": [ "Invalid JSON response." ] } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch shipping options from Kleinanzeigen" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] } }, "required": [ "error", "message" ] } ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "meta": { "type": "object", "properties": { "duration_ms": { "type": "number" } }, "required": [ "duration_ms" ] } }, "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", "enum": [ "An error occurred while fetching industries" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] }, "_debug": { "type": [ "object", "null" ], "properties": { "note": { "type": "string", "enum": [ "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", "enum": [ 1 ] }, "name": { "type": "string", "enum": [ "Banken \/ Finanzdienstleistungen" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 2 ] }, "name": { "type": "string", "enum": [ "Baugewerbe \/ Bau" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 3 ] }, "name": { "type": "string", "enum": [ "Beratung \/ Consulting" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 4 ] }, "name": { "type": "string", "enum": [ "Bildung \/ Forschung \/ Wissenschaft" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 5 ] }, "name": { "type": "string", "enum": [ "Chemie" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 6 ] }, "name": { "type": "string", "enum": [ "Dienstleistung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 7 ] }, "name": { "type": "string", "enum": [ "Druck \/ Papier \/ Verpackung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 8 ] }, "name": { "type": "string", "enum": [ "EDV \/ IT" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 9 ] }, "name": { "type": "string", "enum": [ "Einzelhandel \/ Handel" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 10 ] }, "name": { "type": "string", "enum": [ "Elektro" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 11 ] }, "name": { "type": "string", "enum": [ "Energie \/ Rohstoffe \/ Umwelt" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 12 ] }, "name": { "type": "string", "enum": [ "Fahrzeugbau \/ -zulieferer" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 13 ] }, "name": { "type": "string", "enum": [ "Freizeit \/ Touristik \/ Gastronomie \/ Sport" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 14 ] }, "name": { "type": "string", "enum": [ "Gesundheit \/ Soziales \/ Pflege" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 15 ] }, "name": { "type": "string", "enum": [ "Gro\u00dfhandel" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 16 ] }, "name": { "type": "string", "enum": [ "Immobilien" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 17 ] }, "name": { "type": "string", "enum": [ "Industrie" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 18 ] }, "name": { "type": "string", "enum": [ "Internet \/ Multimedia" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 19 ] }, "name": { "type": "string", "enum": [ "Kunst \/ Kultur \/ Unterhaltung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 20 ] }, "name": { "type": "string", "enum": [ "Land- \/ Forstwirtschaft \/ Fischerei" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 21 ] }, "name": { "type": "string", "enum": [ "Lebensmittel" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 22 ] }, "name": { "type": "string", "enum": [ "Marketing \/ PR \/ Werbung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 23 ] }, "name": { "type": "string", "enum": [ "Maschinenbau \/ Anlagenbau" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 24 ] }, "name": { "type": "string", "enum": [ "Medien \/ Verlage" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 25 ] }, "name": { "type": "string", "enum": [ "Medizintechnik" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 26 ] }, "name": { "type": "string", "enum": [ "Metall" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 27 ] }, "name": { "type": "string", "enum": [ "\u00d6ffentlicher Dienst \/ Verb\u00e4nde \/ Einrichtungen" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 28 ] }, "name": { "type": "string", "enum": [ "Personaldienstleistung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 29 ] }, "name": { "type": "string", "enum": [ "Pharma \/ Biotech" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 30 ] }, "name": { "type": "string", "enum": [ "Rechtsberatung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 31 ] }, "name": { "type": "string", "enum": [ "Sonstige Branchen" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 32 ] }, "name": { "type": "string", "enum": [ "Steuerberatung \/ Wirtschaftspr\u00fcfung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 33 ] }, "name": { "type": "string", "enum": [ "Telekommunikation" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 34 ] }, "name": { "type": "string", "enum": [ "Textil \/ Leder \/ Bekleidung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 35 ] }, "name": { "type": "string", "enum": [ "Transport \/ Verkehr \/ Logistik" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 36 ] }, "name": { "type": "string", "enum": [ "Versicherung" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 37 ] }, "name": { "type": "string", "enum": [ "Konsumg\u00fcter \/ Gebrauchsg\u00fcter" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 38 ] }, "name": { "type": "string", "enum": [ "Elektronik \/ Elektrotechnik" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 39 ] }, "name": { "type": "string", "enum": [ "Feinmechanik \/ Optik" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 40 ] }, "name": { "type": "string", "enum": [ "Erd\u00f6l \/ Erdgas" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 41 ] }, "name": { "type": "string", "enum": [ "Baustoff" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 42 ] }, "name": { "type": "string", "enum": [ "Bergbau" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 43 ] }, "name": { "type": "string", "enum": [ "Luft- \/ Raumfahrt" ] } }, "required": [ "id", "name" ] }, { "type": "object", "properties": { "id": { "type": "integer", "enum": [ 44 ] }, "name": { "type": "string", "enum": [ "Luftfahrt" ] } }, "required": [ "id", "name" ] } ], "minItems": 44, "maxItems": 44, "additionalItems": false }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "description": { "type": "string", "enum": [ "All available Kununu industry categories with their IDs" ] } }, "required": [ "total", "description" ] }, "_debug": { "type": [ "object", "null" ], "properties": { "note": { "type": "string", "enum": [ "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, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "countries[]", "in": "query", "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": { "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" ] } } } }, "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": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 1 ] } ] }, "resultsStart": { "type": "string" }, "resultsEnd": { "type": "string" }, "totalResults": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "currentPage", "totalPages", "resultsStart", "resultsEnd", "totalResults", "limit", "offset" ] }, "filters": { "type": [ "string", "null" ] }, "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", "enum": [ "kununu\/search" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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": "array", "items": {} }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "currentPage": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 1 ] } ] }, "resultsStart": { "type": "string" }, "resultsEnd": { "type": "string" }, "totalResults": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "currentPage", "totalPages", "resultsStart", "resultsEnd", "totalResults", "limit", "offset" ] }, "filters": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "string" } }, "required": [ "pagination", "filters", "duration_ms", "cached", "cached_at" ] }, "_debug": { "type": [ "object", "null" ], "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } }, "required": [ "success", "data", "meta", "_debug" ] } ] } } } }, "404": { "description": "Requested offset exceeds the available results", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Kununu blocked the request (anti-bot protection). Try again later." ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable due to bot protection. Please retry." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/search" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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" ] } } } }, "401": { "description": "API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/kununu\/reviews": { "get": { "operationId": "kununu.reviews", "summary": "Get reviews for a company on Kununu", "tags": [ "Kununu" ], "parameters": [ { "name": "uuid", "in": "query", "description": "Alias parameters for chaining from search endpoint", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "slug", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } }, { "name": "countryCode", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } }, { "name": "score_filters[]", "in": "query", "schema": { "type": "array", "enum": [ "excellent", "good", "satisfactory", "subpar" ], "items": { "type": "string", "enum": [ "excellent", "good", "satisfactory", "subpar" ] } } }, { "name": "recommended_filters[]", "in": "query", "schema": { "type": "array", "enum": [ "yes", "no" ], "items": { "type": "string", "enum": [ "yes", "no" ] } } }, { "name": "jobstatus_filters[]", "in": "query", "schema": { "type": "array", "enum": [ "current", "former" ], "items": { "type": "string", "enum": [ "current", "former" ] } } }, { "name": "position_filters[]", "in": "query", "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", "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", "schema": { "type": "array", "enum": [ "yes", "no" ], "items": { "type": "string", "enum": [ "yes", "no" ] } } }, { "name": "date_filters[]", "in": "query", "schema": { "type": "array", "enum": [ "24months", "12months", "6months", "30days" ], "items": { "type": "string", "enum": [ "24months", "12months", "6months", "30days" ] } } }, { "name": "country", "in": "query", "required": true, "description": "Country code of the company (e.g., \"de\", \"at\", \"ch\")", "schema": { "type": "string" } }, { "name": "company_slug", "in": "query", "required": true, "description": "Company slug from Kununu (e.g., \"bmw-group\", \"sap-se\")", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "required": true, "description": "Company ID from Kununu (UUID format)", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": "integer" } }, { "name": "review_type", "in": "query", "description": "Type of reviews: \"employees\" or \"candidates\" (default: \"employees\")", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort order: \"worst\", \"best\", \"newest\", \"oldest\"", "schema": { "type": "string" } }, { "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" } } ], "responses": { "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" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "type": "array", "items": {} }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "totalPages": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 1 ] } ] }, "resultsStart": { "type": "string" }, "resultsEnd": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "type": "object" } ] }, "totalResults": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } }, "required": [ "currentPage", "totalPages", "resultsStart", "resultsEnd", "totalResults" ] }, "filters": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" } }, "required": [ "pagination", "filters", "duration_ms", "cached" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/reviews" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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" }, "filters": { "type": "string" }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "string" } }, "required": [ "pagination", "filters", "duration_ms", "cached", "cached_at" ] }, "_debug": { "type": [ "object", "null" ], "properties": { "note": { "type": "string", "enum": [ "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", "enum": [ "Kununu blocked the request (anti-bot protection). Try again later." ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable due to bot protection. Please retry." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/reviews" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] } } } }, "404": { "description": "Company not found on Kununu", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "description": "One or more parameters failed validation", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "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", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "countries[]", "in": "query", "description": "Filter by country codes (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 to get the list.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 44 } } ], "responses": { "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" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "type": "array", "items": {} }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 1 ] } ] }, "resultsStart": { "type": "string" }, "resultsEnd": { "type": "string" }, "totalResults": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] } }, "required": [ "currentPage", "totalPages", "resultsStart", "resultsEnd", "totalResults" ] }, "filters": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" } }, "required": [ "pagination", "filters", "duration_ms", "cached" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/profiles" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "totalPages": { "type": "integer", "enum": [ 0 ] }, "resultsStart": { "type": "integer", "enum": [ 0 ] }, "resultsEnd": { "type": "integer", "enum": [ 0 ] }, "totalResults": { "type": "integer", "enum": [ 0 ] } }, "required": [ "currentPage", "totalPages", "resultsStart", "resultsEnd", "totalResults" ] }, "filters": { "type": "null" }, "duration_ms": { "type": "number" } }, "required": [ "pagination", "filters", "duration_ms" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/profiles" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } ] } }, "required": [ "success", "data", "meta", "_debug" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "meta": { "type": "object", "properties": { "pagination": { "type": "string" }, "filters": { "type": [ "string", "null" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "string" } }, "required": [ "pagination", "filters", "duration_ms", "cached", "cached_at" ] }, "_debug": { "type": [ "object", "null" ], "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } }, "required": [ "success", "data", "meta", "_debug" ] } ] } } } }, "404": { "description": "Requested page exceeds the available pages", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Kununu blocked the request (anti-bot protection). Try again later." ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable due to bot protection. Please retry." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/profiles" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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" ] } } } }, "401": { "description": "API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/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": "Original parameter names (required unless corresponding alias is used)", "schema": { "type": "string", "enum": [ "de", "at", "ch" ] } }, { "name": "company_slug", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9\\-]+$", "minLength": 1, "maxLength": 255 } }, { "name": "slug", "in": "query", "description": "Alias parameters for chaining from search endpoint", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } }, { "name": "countryCode", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "ch" ] } } ], "responses": { "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" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "basic_info": { "type": "object", "properties": { "name": { "anyOf": [ {}, { "type": [ "string", "null" ] } ] }, "uuid": {}, "slug": {}, "city": {}, "country": {}, "industry": {}, "employer_segment": {}, "status": {}, "url": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "name", "uuid", "slug", "city", "country", "industry", "employer_segment", "status", "url", "website", "description" ] }, "ratings": { "type": "object", "properties": { "overall_score": {}, "recommendation_rate": {}, "total_reviews": {}, "employee_reviews": {}, "applicant_reviews": {}, "salary_ranges_count": {} }, "required": [ "overall_score", "recommendation_rate", "total_reviews", "employee_reviews", "applicant_reviews", "salary_ranges_count" ] }, "structured_data": { "type": "object", "properties": { "organization": { "type": [ "object", "null" ] }, "website": { "type": [ "string", "null" ] }, "rating": { "type": [ "object", "null" ] }, "faqs": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "breadcrumbs": { "type": [ "object", "null" ] } }, "required": [ "organization", "website", "rating", "faqs", "breadcrumbs" ] }, "social_media": { "anyOf": [ {}, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "awards": { "anyOf": [ {}, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "benefits": { "anyOf": [ {}, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "faqs": { "anyOf": [ {}, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "general_info": { "anyOf": [ {}, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "metadata": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "og_title": { "type": [ "string", "null" ] }, "og_description": { "type": [ "string", "null" ] }, "og_url": { "type": [ "string", "null" ] }, "canonical_url": { "type": [ "string", "null" ] }, "twitter_title": { "type": [ "string", "null" ] }, "twitter_description": { "type": [ "string", "null" ] } }, "required": [ "title", "og_title", "og_description", "og_url", "canonical_url", "twitter_title", "twitter_description" ] } }, "required": [ "basic_info", "ratings", "structured_data", "social_media", "awards", "benefits", "faqs", "general_info", "metadata" ] }, "meta": { "type": "object", "properties": { "url": { "type": "string" }, "duration_ms": { "type": "number" }, "scraped_at": { "type": [ "string", "null" ] }, "cached": { "type": "boolean" } }, "required": [ "url", "duration_ms", "scraped_at", "cached" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/company-details" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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": { "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", "cached_at" ] }, "_debug": { "type": [ "object", "null" ], "properties": { "note": { "type": "string", "enum": [ "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", "enum": [ "Kununu blocked the request (anti-bot protection). Try again later." ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable due to bot protection. Please retry." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/company-details" ] }, "method": { "type": "string", "enum": [ "GET" ] }, "request_params": { "type": "string" }, "query": { "type": [ "string", "null" ] }, "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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" ] } } } }, "401": { "description": "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" ] } } } } } } }, "\/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" } }, { "name": "country", "in": "query", "description": "Country code: de (Germany), at (Austria), ch (Switzerland). Default: de", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1, ~30 results per page)", "schema": { "type": "integer" } }, { "name": "location", "in": "query", "description": "City or location name (e.g., \"Berlin\"). Plain city names are resolved automatically.", "schema": { "type": "string" } }, { "name": "radius", "in": "query", "description": "Search radius in km around location. Values: 10, 20, 30, 50, 100, 200. Requires location.", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort order: \"newest\" (newest first), \"kununuScore\" (by company score). Default: relevance", "schema": { "type": "string" } }, { "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": {} } }, { "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" } } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "An error occurred while processing the request" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/jobs" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to parse Kununu Jobs API response" ] }, "message": { "type": "string", "enum": [ "Invalid JSON response" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/jobs" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch data from Kununu Jobs API" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/jobs" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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": { "currentPage": { "type": "integer" }, "lastPage": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 1 ] } ] }, "totalJobs": { "type": "integer" } }, "required": [ "currentPage", "lastPage", "totalJobs" ] }, "duration_ms": { "type": "number" }, "cached": { "type": "boolean" }, "cached_at": { "type": "null" }, "warnings": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ], "minItems": 2, "maxItems": 2, "additionalItems": false } }, "required": [ "pagination", "duration_ms", "cached", "cached_at", "warnings" ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/jobs" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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", "null" ], "properties": { "note": { "type": "string", "enum": [ "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", "enum": [ "Kununu blocked the request (anti-bot protection). Try again later." ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable due to bot protection. Please retry." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/jobs" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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", "enum": [ "Page not found" ] }, "message": { "type": "string" }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "kununu\/jobs" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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" ] } } } } } } }, "\/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": "Pagination\npage and start are mutually exclusive - use page for easier pagination (1-based)\nor start for direct offset control (0-based)\nMax start is 170 because Google CSE API has a hard limit where offset + num must not exceed 190", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "start", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 170 } }, { "name": "page", "in": "query", "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", "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", "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", "schema": { "type": [ "string", "null" ], "enum": [ "date", "date:r", "date:d" ] } }, { "name": "filter", "in": "query", "description": "Content filtering (only params that can't be set via query modifiers)\nNOTE: fileType, exactTerms, siteSearch removed - use query modifiers instead:\nfiletype:pdf, \"exact phrase\", site:domain.com", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "rights", "in": "query", "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" } } } }, "\/linkedin\/jobs\/search": { "get": { "operationId": "linkedin.jobs.search", "description": "Search LinkedIn job listing pages via Google 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": "Pagination\npage and start are mutually exclusive - use page for easier pagination (1-based)\nor start for direct offset control (0-based)\nMax start is 170 because Google CSE API has a hard limit where offset + num must not exceed 190", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "start", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 170 } }, { "name": "page", "in": "query", "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", "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", "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", "schema": { "type": [ "string", "null" ], "enum": [ "date", "date:r", "date:d" ] } }, { "name": "filter", "in": "query", "description": "Content filtering (only params that can't be set via query modifiers)\nNOTE: fileType, exactTerms, siteSearch removed - use query modifiers instead:\nfiletype:pdf, \"exact phrase\", site:domain.com", "schema": { "type": [ "integer", "null" ], "enum": [ "0", "1" ] } }, { "name": "rights", "in": "query", "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" } } } }, "\/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, "schema": { "type": "string", "format": "uri", "pattern": "^https:\\\/\\\/(?:(?:[a-z]{2}|www)\\.)?linkedin\\.com\\\/in\\\/[a-zA-Z0-9_-]+\\\/?(?:\\?.*)?$" } }, { "name": "use_cache", "in": "query", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "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, "schema": { "type": "string", "format": "uri", "pattern": "^https:\\\/\\\/(www\\.)?linkedin\\.com\\\/company\\\/[a-zA-Z0-9._-]+\\\/?$" } }, { "name": "use_cache", "in": "query", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "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": { "$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\/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, "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", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "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": { "$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\/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, "schema": { "type": "string", "format": "uri", "pattern": "^https?:\\\/\\\/(www\\.|[a-z]{2}\\.)?linkedin\\.com\\\/jobs\\\/view\\\/[a-z0-9\\-]*(\\d+)\\\/?$" } }, { "name": "use_cache", "in": "query", "schema": { "type": "boolean" } }, { "name": "maximum_cache_age", "in": "query", "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" } } } }, "\/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", "enum": [ "Documentation generation failed" ] }, "message": { "type": "string", "enum": [ "Unable to generate API documentation. Please try again later." ] } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } } } } }, "\/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", "enum": [ "Documentation generation failed" ] }, "message": { "type": "string", "enum": [ "Unable to generate API documentation. Please try again later." ] } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } } } } }, "\/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, "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": { "$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" ] } } } } } } }, "\/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, "schema": { "type": "integer" } }, { "name": "region_type", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ "1", "2", "4", "5", "6" ] } }, { "name": "market", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+$", "maxLength": 30 } }, { "name": "min_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "num_beds", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10 } }, { "name": "num_baths", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10 } }, { "name": "property_types", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^([1-8](,[1-8])*)?$" } }, { "name": "status", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "9", "130", "131" ] } }, { "name": "sold_within_days", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 365 } }, { "name": "num_homes", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 450 } }, { "name": "page", "in": "query", "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": { "$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" ] } } } } } } }, "\/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, "schema": { "type": "integer" } }, { "name": "listing_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "predictedValue": { "type": "number" }, "lastSoldPrice": { "type": "number" }, "numBeds": { "type": "integer" }, "numBaths": { "type": "number" } }, "required": [ "predictedValue", "lastSoldPrice", "numBeds", "numBaths" ] } }, "required": [ "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" ] } } } } } } }, "\/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, "schema": { "type": "integer" } } ], "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": { "$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" ] } } } } } } }, "\/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, "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": [ "integer", "null" ] }, "country_rank": { "type": [ "integer", "null" ] }, "country_code": { "type": [ "integer", "null" ] }, "category_rank": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "engagement": { "type": "object", "properties": { "visits": { "type": [ "integer", "null" ] }, "time_on_site": { "type": [ "number", "null" ] }, "page_per_visit": { "type": [ "number", "null" ] }, "bounce_rate": { "type": [ "number", "null" ] }, "month": { "type": [ "integer", "null" ] }, "year": { "type": [ "integer", "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, "schema": { "type": "string", "maxLength": 500 } }, { "name": "location", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "country", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "nl", "be" ] } }, { "name": "radius", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 200 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "date" ] } }, { "name": "job_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "full_time", "part_time", "internship", "freelance" ] } }, { "name": "work_from_home", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "date_posted", "in": "query", "schema": { "type": [ "integer", "null" ], "enum": [ "1", "3", "7", "30" ] } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 } }, { "name": "limit", "in": "query", "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" ] }, "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", "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, "schema": { "type": "string", "maxLength": 500 } }, { "name": "country", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "de", "at", "nl", "be" ] } }, { "name": "limit", "in": "query", "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": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "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" }, "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", "enum": [ "DEU" ] }, "name": { "type": "string", "enum": [ "Germany" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "GBR" ] }, "name": { "type": "string", "enum": [ "United Kingdom" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "AUT" ] }, "name": { "type": "string", "enum": [ "Austria" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CHE" ] }, "name": { "type": "string", "enum": [ "Switzerland" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NLD" ] }, "name": { "type": "string", "enum": [ "Netherlands" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "ESP" ] }, "name": { "type": "string", "enum": [ "Spain" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "ITA" ] }, "name": { "type": "string", "enum": [ "Italy" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FRA" ] }, "name": { "type": "string", "enum": [ "France" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "BEL" ] }, "name": { "type": "string", "enum": [ "Belgium" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "POL" ] }, "name": { "type": "string", "enum": [ "Poland" ] } }, "required": [ "code", "name" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PRT" ] }, "name": { "type": "string", "enum": [ "Portugal" ] } }, "required": [ "code", "name" ] } ], "minItems": 11, "maxItems": 11, "additionalItems": false }, "total_markets": { "type": "integer" } }, "required": [ "markets", "total_markets" ] }, "message": { "type": "string", "enum": [ "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", "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, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "market", "in": "query", "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, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 500 } }, { "name": "market", "in": "query", "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, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "size", "in": "query", "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, "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, "schema": { "type": "string", "pattern": "^[a-z0-9_-]+$", "minLength": 1, "maxLength": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "reviews_count", "latest_review" ] } }, { "name": "claimed", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "country", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 } }, { "name": "trustscore", "in": "query", "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": { "$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\/company-search": { "get": { "operationId": "trustpilot.company-search", "summary": "Search for companies on Trustpilot", "tags": [ "Trustpilot" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "country", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2 } }, { "name": "min_rating", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "any", "3", "4", "4.5" ] } }, { "name": "min_review_count", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "any", "25", "50", "100", "250", "500" ] } }, { "name": "locale", "in": "query", "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": { "$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\/company-details": { "get": { "operationId": "trustpilot.company-details", "summary": "Get company details from Trustpilot", "tags": [ "Trustpilot" ], "parameters": [ { "name": "company_domain", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "minLength": 3, "maxLength": 255 } }, { "name": "locale", "in": "query", "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": { "$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\/company-reviews": { "get": { "operationId": "trustpilot.company-reviews", "summary": "Get company reviews from Trustpilot", "tags": [ "Trustpilot" ], "parameters": [ { "name": "company_domain", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "minLength": 3, "maxLength": 255 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "verified", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "with_replies", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "query", "in": "query", "description": "'sometimes|required' combination ensures:\n- If query is not provided at all: validation passes (optional parameter)\n- If query is provided as empty string: validation fails (required rejects empty strings)\n- If query is provided with value: min\/max rules apply", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "rating", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[1-5](,[1-5])*$" } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "recency" ] } }, { "name": "locale", "in": "query", "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": "fields", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "date_posted", "in": "query", "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": { "$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\/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", "enum": [ "FR" ] }, "name": { "type": "string", "enum": [ "France" ] }, "tld": { "type": "string", "enum": [ "fr" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DE" ] }, "name": { "type": "string", "enum": [ "Germany" ] }, "tld": { "type": "string", "enum": [ "de" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "ES" ] }, "name": { "type": "string", "enum": [ "Spain" ] }, "tld": { "type": "string", "enum": [ "es" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "IT" ] }, "name": { "type": "string", "enum": [ "Italy" ] }, "tld": { "type": "string", "enum": [ "it" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NL" ] }, "name": { "type": "string", "enum": [ "Netherlands" ] }, "tld": { "type": "string", "enum": [ "nl" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "BE" ] }, "name": { "type": "string", "enum": [ "Belgium" ] }, "tld": { "type": "string", "enum": [ "be" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "AT" ] }, "name": { "type": "string", "enum": [ "Austria" ] }, "tld": { "type": "string", "enum": [ "at" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PL" ] }, "name": { "type": "string", "enum": [ "Poland" ] }, "tld": { "type": "string", "enum": [ "pl" ] }, "currency": { "type": "string", "enum": [ "PLN" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CZ" ] }, "name": { "type": "string", "enum": [ "Czech Republic" ] }, "tld": { "type": "string", "enum": [ "cz" ] }, "currency": { "type": "string", "enum": [ "CZK" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LT" ] }, "name": { "type": "string", "enum": [ "Lithuania" ] }, "tld": { "type": "string", "enum": [ "lt" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LU" ] }, "name": { "type": "string", "enum": [ "Luxembourg" ] }, "tld": { "type": "string", "enum": [ "lu" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SK" ] }, "name": { "type": "string", "enum": [ "Slovakia" ] }, "tld": { "type": "string", "enum": [ "sk" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "HU" ] }, "name": { "type": "string", "enum": [ "Hungary" ] }, "tld": { "type": "string", "enum": [ "hu" ] }, "currency": { "type": "string", "enum": [ "HUF" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RO" ] }, "name": { "type": "string", "enum": [ "Romania" ] }, "tld": { "type": "string", "enum": [ "ro" ] }, "currency": { "type": "string", "enum": [ "RON" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PT" ] }, "name": { "type": "string", "enum": [ "Portugal" ] }, "tld": { "type": "string", "enum": [ "pt" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SE" ] }, "name": { "type": "string", "enum": [ "Sweden" ] }, "tld": { "type": "string", "enum": [ "se" ] }, "currency": { "type": "string", "enum": [ "SEK" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DK" ] }, "name": { "type": "string", "enum": [ "Denmark" ] }, "tld": { "type": "string", "enum": [ "dk" ] }, "currency": { "type": "string", "enum": [ "DKK" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FI" ] }, "name": { "type": "string", "enum": [ "Finland" ] }, "tld": { "type": "string", "enum": [ "fi" ] }, "currency": { "type": "string", "enum": [ "EUR" ] } }, "required": [ "code", "name", "tld", "currency" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "US" ] }, "name": { "type": "string", "enum": [ "United States" ] }, "tld": { "type": "string", "enum": [ "com" ] }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "code", "name", "tld", "currency" ] } ], "minItems": 19, "maxItems": 19, "additionalItems": false }, "total_countries": { "type": "integer" } }, "required": [ "countries", "total_countries" ] }, "message": { "type": "string", "enum": [ "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": "query", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "newest_first", "price_low_to_high", "price_high_to_low" ] } }, { "name": "brand_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "catalog_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "color_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "size_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "material_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "status_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "price_from", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "price_to", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "country", "in": "query", "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": "query", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "newest_first", "price_low_to_high", "price_high_to_low" ] } }, { "name": "brand_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "catalog_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "color_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "size_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "material_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 200 } }, { "name": "status_ids", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "price_from", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "price_to", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 0 } }, { "name": "country", "in": "query", "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, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "country", "in": "query", "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": { "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": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/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, "schema": { "type": "string", "maxLength": 50 } }, { "name": "country", "in": "query", "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" ] }, "url": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ] }, "condition_title": { "type": [ "string", "null" ] }, "brand": { "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", "url", "condition", "condition_title", "brand", "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, "schema": { "type": "string", "maxLength": 50 } }, { "name": "country", "in": "query", "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, "schema": { "type": "string", "maxLength": 50 } }, { "name": "country", "in": "query", "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, "schema": { "type": "string", "maxLength": 50 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "relevance", "newest_first", "price_low_to_high", "price_high_to_low" ] } }, { "name": "country", "in": "query", "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, "schema": { "type": "string", "pattern": "^[0-9]+$", "maxLength": 50 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 999 } }, { "name": "country", "in": "query", "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" ] } } } }, "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" ] } } } }, "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" ] } } } } } } }, "\/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", "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" ] } } } }, "401": { "description": "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" ] } } } } } } }, "\/web-scraper": { "get": { "operationId": "web-scraper.scrape", "tags": [ "WebScraper" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048 } }, { "name": "include_html", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "response_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "json", "markdown" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "site_status_code": { "type": "string" }, "url": { "type": "string" }, "final_url": { "type": "string" }, "data": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "keywords": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, { "type": "array", "items": {} } ] }, "favicon": { "type": [ "string", "null" ] }, "social_links": { "type": "array", "items": {} }, "links": { "type": "array", "items": {} }, "emails": { "type": "array", "items": {} }, "phone_numbers": { "type": "array", "items": {} }, "images": { "type": "array", "items": {} }, "body_text": { "type": "string" }, "languages_detected": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ], "minItems": 2, "maxItems": 2, "additionalItems": false }, { "type": "array", "prefixItems": [ { "type": "string", "enum": [ "en" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } ] }, "html": { "type": [ "string", "null" ] } }, "required": [ "title", "description", "keywords", "favicon", "social_links", "links", "emails", "phone_numbers", "images", "body_text", "languages_detected", "html" ] } }, "required": [ "success", "site_status_code", "url", "final_url", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "site_status_code": { "type": "string" }, "url": { "type": "string" }, "final_url": { "type": "string" }, "markdown": { "type": "string" } }, "required": [ "success", "site_status_code", "url", "final_url", "markdown" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "error_code": { "type": "string" } }, "required": [ "success", "error", "error_code" ] } ] }, { "type": "string" } ] } } } }, "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "enum": [ "An unexpected error occurred while scraping the URL." ] }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } }, "required": [ "success", "error", "error_code" ] }, { "type": "string", "enum": [ "Error: An unexpected error occurred while scraping the URL." ] } ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "enum": [ "Invalid URL format." ] }, "error_code": { "type": "string", "enum": [ "INVALID_URL" ] } }, "required": [ "success", "error", "error_code" ] }, { "type": "string", "enum": [ "Error: Invalid URL format." ] } ] } } } }, "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" ] } } } } } } }, "\/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" } }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Results per page (1-50, default: 15)", "schema": { "type": "integer" } }, { "name": "country", "in": "query", "description": "Country code: DE (Germany), AT (Austria), CH (Switzerland). Default: DE", "schema": { "type": "string" } }, { "name": "countries", "in": "query", "description": "Filter by country codes (comma-separated, e.g., \"DE,AT\")", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_type", "in": "query", "description": "Filter by supplier type (comma-separated)", "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "description": "Filter by attribute codes (comma-separated)", "schema": { "type": "string" } }, { "name": "verified", "in": "query", "description": "Only show verified suppliers", "schema": { "type": "boolean" } }, { "name": "top_responder", "in": "query", "description": "Only show top responders", "schema": { "type": "boolean" } }, { "name": "radius", "in": "query", "description": "Search radius in km (requires lat\/lng)", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort: relevance, recency, trending, distance", "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Language code (default: de)", "schema": { "type": "string" } }, { "name": "latitude", "in": "query", "description": "Location filter: latitude", "schema": { "type": "object" }, "x-deepObject-style": "qs" }, { "name": "longitude", "in": "query", "description": "Location filter: longitude", "schema": { "type": "object" }, "x-deepObject-style": "qs" } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Internal service error" ] }, "message": { "type": "string", "enum": [ "An unexpected error occurred." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "wlw\/search" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "Debug mode enabled but no debug data collected" ] } }, "required": [ "note" ] } ] } }, "required": [ "error", "message", "_debug" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Failed to fetch data from WLW API" ] }, "message": { "type": "string", "enum": [ "Service temporarily unavailable. Please try again." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "wlw\/search" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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" }, { "type": "integer", "enum": [ 1 ] } ] }, "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", "enum": [ "wlw\/search" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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", "null" ], "properties": { "note": { "type": "string", "enum": [ "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", "enum": [ "Invalid response from WLW API" ] }, "message": { "type": "string", "enum": [ "Unexpected response format." ] }, "_debug": { "anyOf": [ { "type": "object", "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string", "enum": [ "wlw\/search" ] }, "method": { "type": "string", "enum": [ "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": "null" }, { "type": "object", "properties": { "note": { "type": "string", "enum": [ "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\/search": { "get": { "operationId": "youtube.search", "summary": "Search YouTube videos", "tags": [ "YouTube" ], "parameters": [ { "name": "query", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "continuation", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "video", "channel", "playlist", "movie", "all" ] } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "date", "rating", "relevance", "viewCount" ] } }, { "name": "videoDuration", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "short", "medium", "long" ] } }, { "name": "publishedAfter", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "publishedBefore", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "safeSearch", "in": "query", "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, "schema": { "type": "string", "minLength": 1 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "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", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "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, "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "limit", "in": "query", "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\/related": { "get": { "operationId": "youtube.related", "summary": "Get related videos", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "limit", "in": "query", "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", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "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", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "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", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "popular", "oldest" ] } }, { "name": "continuation", "in": "query", "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", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "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", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "continuation", "in": "query", "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, "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", "schema": { "type": "string", "enum": [ "now", "music", "gaming", "movies" ] } }, { "name": "gl", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "continuation", "in": "query", "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" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/youtube-external\/locales": { "get": { "operationId": "youtube-external.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-external\/search": { "get": { "operationId": "youtube-external.search", "summary": "Search YouTube videos", "tags": [ "YouTube" ], "parameters": [ { "name": "query", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 1 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "continuation", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "video", "channel", "playlist", "movie", "all" ] } }, { "name": "order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "date", "rating", "relevance", "viewCount" ] } }, { "name": "videoDuration", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "short", "medium", "long" ] } }, { "name": "publishedAfter", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "publishedBefore", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "safeSearch", "in": "query", "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-external\/suggestions": { "get": { "operationId": "youtube-external.suggestions", "summary": "Get search suggestions", "tags": [ "YouTube" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "hl", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "gl", "in": "query", "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-external\/video": { "get": { "operationId": "youtube-external.video", "summary": "Get video details", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "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-external\/comments": { "get": { "operationId": "youtube-external.comments", "summary": "Get video comments", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "limit", "in": "query", "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-external\/related": { "get": { "operationId": "youtube-external.related", "summary": "Get related videos", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "limit", "in": "query", "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-external\/chapters": { "get": { "operationId": "youtube-external.chapters", "summary": "Get video chapters", "tags": [ "YouTube" ], "parameters": [ { "name": "video_id", "in": "query", "schema": { "type": "string", "minLength": 11, "maxLength": 11 } }, { "name": "videoId", "in": "query", "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-external\/channel": { "get": { "operationId": "youtube-external.channel", "summary": "Get channel info", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "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-external\/channel-videos": { "get": { "operationId": "youtube-external.channel-videos", "summary": "Get channel videos", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "popular", "oldest" ] } }, { "name": "continuation", "in": "query", "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-external\/channel-playlists": { "get": { "operationId": "youtube-external.channel-playlists", "summary": "Get channel playlists", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "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-external\/channel-community": { "get": { "operationId": "youtube-external.channel-community", "summary": "Get channel community posts", "tags": [ "YouTube" ], "parameters": [ { "name": "channel_id", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "channelId", "in": "query", "schema": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]+$", "minLength": 3, "maxLength": 100 } }, { "name": "continuation", "in": "query", "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-external\/playlist": { "get": { "operationId": "youtube-external.playlist", "summary": "Get playlist details", "tags": [ "YouTube" ], "parameters": [ { "name": "playlist_id", "in": "query", "required": true, "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-external\/trending": { "get": { "operationId": "youtube-external.trending", "summary": "Get trending videos", "tags": [ "YouTube" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "now", "music", "gaming", "movies" ] } }, { "name": "gl", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "hl", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "continuation", "in": "query", "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" }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "EmailVerifyRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ], "title": "EmailVerifyRequest" } }, "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" ] } } } } } } }