{ "openapi": "3.0.0", "info": { "title": "TikTok Shop Scraper API", "description": "Scrape TikTok Shop products, shops, sellers and reviews across both API versions. Fast JSON, cursor pagination, one consistent response contract.", "version": "1.0.0", "x-category": "eCommerce", "x-long-description": "Scrape TikTok Shop products, shops, sellers and reviews across both API versions. Fast JSON, cursor pagination, one consistent response contract.", "x-website": "https://toolzerhub.com", "x-documentation-url": "https://docs.toolzerhub.com", "x-public": true }, "externalDocs": { "description": "Full documentation", "url": "https://docs.toolzerhub.com" }, "x-documentation": { "readme": "# TikTok Shop Scraper API\n\nScrape TikTok Shop products, shops, sellers and reviews across both API versions. Fast JSON, cursor pagination, one consistent response contract.\n\nEvery endpoint here follows the **same contract** — learn it once and it applies\nacross the whole API. Full interactive docs, schemas and runnable examples live\nat **https://docs.toolzerhub.com**.\n\n## Authentication\nYour RapidAPI key is sent automatically as the `X-RapidAPI-Key` header — the\nplayground and generated code snippets add it for you. No other setup.\n\n## Response shape\nEvery successful call returns a JSON object with a single `data` field:\n\n```json\n{ \"data\": { ... } }\n```\n\nEndpoints that return a list put an array in `data` alongside a `pageInfo`\nobject — `{ \"cursor\": \"…\", \"hasNextPage\": true }`. Pass the `cursor` back on the\nnext request to page forward. Every response also carries an\n`X-Toolzer-Request-Id` header (quote it if you ever report an issue).\n\n## Errors\nFailures return the matching HTTP status and a structured body:\n\n```json\n{ \"error\": { \"code\": \"…\", \"status\": 400, \"message\": \"…\", \"retryable\": false, \"details\": null } }\n```\n\n`retryable: true` means the call is worth retrying after a short backoff;\n`false` means fix the request first.\n\n## Health\n`GET /health` returns `{ \"status\": \"ok\" }` — free, unmetered, for uptime checks.\n\n## Support\nQuestions or issues? **contact@toolzerhub.com**\n", "url": "https://docs.toolzerhub.com" }, "servers": [ { "url": "https://api.toolzerhub.com", "description": "Production" } ], "tags": [ { "name": "TikTok Shop - Products", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." }, { "name": "TikTok Shop - Product", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." }, { "name": "TikTok Shop - Seller", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." }, { "name": "TikTok Shop - Categories", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." }, { "name": "TikTok Shop - Shop", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." }, { "name": "TikTok Shop - Search", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." }, { "name": "TikTok Shop - Category", "description": "Search TikTok Shop products and retrieve product details, reviews, seller catalogs, shop profiles, categories, and trending products." } ], "paths": { "/v1/tiktok-shop/product/detail": { "get": { "operationId": "Get TikTok Shop Product Detail V2", "tags": [ "TikTok Shop - Product" ], "summary": "Get product details", "description": "Returns full product information for the required `product_id` — title, media, SKUs and pricing, shop details, and review summary.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,30}$", "example": "1730927783781307026", "description": "Numeric TikTok Shop product ID." }, "required": true, "description": "Numeric TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "product_info": { "type": "object", "properties": { "product_model": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "additionalProperties": { "nullable": true } }, "shop_info": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "review_info": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "categories": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } } }, "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/product/reviews": { "get": { "operationId": "Get TikTok Shop Product Reviews V2", "tags": [ "TikTok Shop - Product" ], "summary": "List product reviews", "description": "List customer reviews for a TikTok Shop product, including ratings, text, media, and available seller replies.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,30}$", "example": "1730927783781307026", "description": "Numeric TikTok Shop product ID." }, "required": true, "description": "Numeric TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 30, "example": 30, "description": "How many reviews to return (1-500). Reviews are collected in pages of up to 100, so larger values take longer to answer." }, "required": false, "description": "How many reviews to return (1-500). Reviews are collected in pages of up to 100, so larger values take longer to answer.", "name": "count", "in": "query" }, { "schema": { "type": "string", "enum": [ "recommended", "most_recent" ], "default": "recommended", "example": "recommended", "description": "Review ordering." }, "required": false, "description": "Review ordering.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "5_star", "4_star", "3_star", "2_star", "1_star", "with_media", "verified_purchase" ], "default": "all", "example": "all", "description": "Restrict to a star rating, to reviews carrying photos/video, or to verified purchases. `total_reviews` in the response reflects the filter, so it doubles as a count per rating." }, "required": false, "description": "Restrict to a star rating, to reviews carrying photos/video, or to verified purchases. `total_reviews` in the response reflects the filter, so it doubles as a count per rating.", "name": "filter", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "product_reviews": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "string" } }, "required": [ "review_id" ], "additionalProperties": { "nullable": true } } }, "total_reviews": { "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "product_reviews" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/products/search": { "get": { "operationId": "Search TikTok Shop Products V2", "tags": [ "TikTok Shop - Products" ], "summary": "Search products", "description": "Returns products matching the required `keyword`. `count` (default 30, max 150) sets how many to return; `has_more` says whether more exist beyond what was returned.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wireless earbuds", "description": "Keyword to search TikTok Shop products for." }, "required": true, "description": "Keyword to search TikTok Shop products for.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "name": "region", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 150, "default": 30, "example": 30, "description": "How many products to return (1-150). Results are collected in pages of about 30, so larger values take longer to answer. Fewer may come back than asked for — the response's own has_more flag is the source of truth on whether more exist." }, "required": false, "description": "How many products to return (1-150). Results are collected in pages of about 30, so larger values take longer to answer. Fewer may come back than asked for — the response's own has_more flag is the source of truth on whether more exist.", "name": "count", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "shops": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "has_more": { "type": "boolean" }, "load_more_params": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/category/products": { "get": { "operationId": "Get TikTok Shop Category Products V2", "tags": [ "TikTok Shop - Category" ], "summary": "List category products", "description": "Returns products for the required `category_id`. This surface randomizes: repeat calls return different products, so treat the result as a sample of the category rather than a stable page.", "parameters": [ { "schema": { "type": "integer", "nullable": true, "example": 601450, "description": "Category ID (see the top-level category reference in research/tiktok-shop/06-homepage.md)." }, "required": false, "description": "Category ID (see the top-level category reference in research/tiktok-shop/06-homepage.md).", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 150, "default": 20, "example": 20, "description": "How many products to return (1-150). Results are collected in pages of about 20, so larger values take longer to answer. Fewer may come back than asked for — the response's own has_more flag is the source of truth on whether more exist." }, "required": false, "description": "How many products to return (1-150). Results are collected in pages of about 20, so larger values take longer to answer. Fewer may come back than asked for — the response's own has_more flag is the source of truth on whether more exist.", "name": "count", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "categoryInfo": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "categoryProductsData": { "type": "object", "properties": { "productList": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "categoryReviews": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "hasMore": { "type": "boolean" } }, "required": [ "productList" ], "additionalProperties": { "nullable": true } } }, "required": [ "categoryProductsData" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/seller/products": { "get": { "operationId": "Get TikTok Shop Seller Products V2", "tags": [ "TikTok Shop - Shop" ], "summary": "List seller products", "description": "Returns the product catalog for the required `seller_id`. `count` (default 30, max 150) sets how many to return; `has_more` says whether the seller has more beyond what was returned.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "7495516049083828882", "description": "TikTok Shop seller/shop ID." }, "required": true, "description": "TikTok Shop seller/shop ID.", "name": "seller_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For seller data in SG/MY/PH/TH/VN, use /v2/tiktok-shop/seller/products.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For seller data in SG/MY/PH/TH/VN, use /v2/tiktok-shop/seller/products.", "name": "region", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 150, "default": 30, "example": 30, "description": "How many products to return (1-150). Results are collected in pages of about 30, so larger values take longer to answer. Fewer may come back than asked for — the response's own has_more flag is the source of truth on whether more exist." }, "required": false, "description": "How many products to return (1-150). Results are collected in pages of about 30, so larger values take longer to answer. Fewer may come back than asked for — the response's own has_more flag is the source of truth on whether more exist.", "name": "count", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "has_more": { "type": "boolean" }, "load_more_params": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/shop/info": { "get": { "operationId": "Get TikTok Shop Info V2", "tags": [ "TikTok Shop - Shop" ], "summary": "Get shop profile", "description": "Returns seller/shop profile information for the required `seller_id`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "7495516049083828882", "description": "TikTok Shop seller/shop ID." }, "required": true, "description": "TikTok Shop seller/shop ID.", "name": "seller_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For seller data in SG/MY/PH/TH/VN, use /v2/tiktok-shop/seller/products.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For seller data in SG/MY/PH/TH/VN, use /v2/tiktok-shop/seller/products.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/home/carousels": { "get": { "operationId": "Get TikTok Shop Home Carousels V2", "tags": [ "TikTok Shop - Products" ], "summary": "Get homepage carousels", "description": "Returns the TikTok Shop homepage product carousels and deals module. Rails carrying products come back resolved in `hydrated_carousels`, keyed by `component_id`; personalized rails that require a logged-in shopper are omitted rather than returned empty.", "parameters": [ { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "carousels": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "deals": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "hydrated_carousels": { "type": "array", "items": { "type": "object", "properties": { "component_id": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "has_more": { "type": "boolean" } }, "required": [ "component_id", "products", "has_more" ] } } }, "required": [ "carousels" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/product/you-may-like": { "get": { "operationId": "Get TikTok Shop You May Like V2", "tags": [ "TikTok Shop - Product" ], "summary": "List related products", "description": "Returns the 'you may like' recommendation carousel shown on the required `product_id`'s detail page.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,30}$", "example": "1730927783781307026", "description": "Numeric TikTok Shop product ID." }, "required": true, "description": "Numeric TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "has_more": { "type": "boolean" }, "load_more_params": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/product/more-from-shop": { "get": { "operationId": "Get TikTok Shop More From Shop V2", "tags": [ "TikTok Shop - Product" ], "summary": "List more products from shop", "description": "Returns other products from the same seller as the required `product_id`, as shown in that product's 'more from this shop' rail.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,30}$", "example": "1730927783781307026", "description": "Numeric TikTok Shop product ID." }, "required": true, "description": "Numeric TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "load_more_params": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/product/top-reviewed": { "get": { "operationId": "Get TikTok Shop Top Reviewed V2", "tags": [ "TikTok Shop - Product" ], "summary": "List top-reviewed products", "description": "Returns the review-ranked product list for the required `product_id`'s seller. US only: no other storefront publishes this widget on its product pages.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,30}$", "example": "1730927783781307026", "description": "Numeric TikTok Shop product ID." }, "required": true, "description": "Numeric TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. Use /v1/tiktok-shop/product/detail for product details in other supported regions.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. Use /v1/tiktok-shop/product/detail for product details in other supported regions.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/product/showcase-videos": { "get": { "operationId": "Get TikTok Shop Product Showcase Videos V2", "tags": [ "TikTok Shop - Product" ], "summary": "List product showcase videos", "description": "Returns creator and affiliate showcase videos for the required `product_id`, including video and cover URLs, author details, and play/like counts. US only: no other storefront publishes this widget on its product pages.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,30}$", "example": "1730927783781307026", "description": "Numeric TikTok Shop product ID." }, "required": true, "description": "Numeric TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. Use /v1/tiktok-shop/product/detail for product details in other supported regions.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. Use /v1/tiktok-shop/product/detail for product details in other supported regions.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "product_id": { "type": "string" }, "videos": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "height": { "type": "integer" }, "width": { "type": "integer" }, "duration": { "type": "integer", "minimum": 0 }, "author_id": { "type": "string" }, "author_name": { "type": "string" }, "author_avatar_url": { "type": "string" }, "play_count": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "like_count": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "upload_time": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "expiration_time": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "title": { "type": "string" }, "cover_image_url": { "type": "string" }, "content_url": { "type": "string" }, "bc_ad_label_text": { "type": "string" } }, "required": [ "item_id" ] } } }, "required": [ "product_id", "videos" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/search/recommended-shops": { "get": { "operationId": "Get TikTok Shop Recommended Shops V2", "tags": [ "TikTok Shop - Search" ], "summary": "Get recommended shop", "description": "Returns the shop spotlighted in search results for the required `keyword`, together with its own product list.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wireless earbuds", "description": "Keyword to search TikTok Shop products for." }, "required": true, "description": "Keyword to search TikTok Shop products for.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "default_shop_info": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "default_shop_products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "default_shop_products_has_more": { "type": "boolean" }, "default_shop_products_next_search_param": { "type": "string" }, "shops": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } } }, "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/search/frequently-bought-together": { "get": { "operationId": "Get TikTok Shop Frequently Bought Together V2", "tags": [ "TikTok Shop - Search" ], "summary": "List frequently bought together", "description": "Returns the 'frequently bought together' product list shown in search results for the required `keyword`. Commonly empty — not every product has a bundling signal.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wireless earbuds", "description": "Keyword to search TikTok Shop products for." }, "required": true, "description": "Keyword to search TikTok Shop products for.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "offset": { "type": "number" }, "has_more": { "type": "boolean" }, "load_more_params": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/search/recommended-for-you": { "get": { "operationId": "Get TikTok Shop Recommended For You V2", "tags": [ "TikTok Shop - Search" ], "summary": "List recommended products", "description": "Returns the 'recommended for you' product list shown in search results for the required `keyword`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wireless earbuds", "description": "Keyword to search TikTok Shop products for." }, "required": true, "description": "Keyword to search TikTok Shop products for.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "offset": { "type": "number" }, "has_more": { "type": "boolean" }, "load_more_params": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/search/related-terms": { "get": { "operationId": "Get TikTok Shop Related Terms V2", "tags": [ "TikTok Shop - Search" ], "summary": "List related search terms", "description": "Returns the related search-term and category chips shown alongside search results for the required `keyword`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wireless earbuds", "description": "Keyword to search TikTok Shop products for." }, "required": true, "description": "Keyword to search TikTok Shop products for.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "enum": [ "US" ], "default": "US", "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "example": "US" }, "required": false, "description": "Storefront region. This endpoint supports US. For keyword search in SG/MY/PH/TH/VN, use /v2/tiktok-shop/products/search.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "search_words": { "type": "object", "properties": { "related_links": { "type": "array", "items": { "type": "object", "properties": { "link": { "type": "string" }, "name": { "type": "string" } }, "required": [ "link", "name" ], "additionalProperties": { "nullable": true } } } }, "required": [ "related_links" ], "additionalProperties": { "nullable": true } }, "categories": { "type": "object", "properties": { "related_links": { "type": "array", "items": { "type": "object", "properties": { "link": { "type": "string" }, "name": { "type": "string" } }, "required": [ "link", "name" ], "additionalProperties": { "nullable": true } } } }, "required": [ "related_links" ], "additionalProperties": { "nullable": true } } }, "required": [ "search_words", "categories" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v1/tiktok-shop/category/breadcrumbs": { "get": { "operationId": "Get TikTok Shop Category Breadcrumbs V2", "tags": [ "TikTok Shop - Category" ], "summary": "Get category breadcrumbs", "description": "Returns the ancestor breadcrumb chain (root-first) for the required `category_id`.", "parameters": [ { "schema": { "type": "integer", "nullable": true, "example": 601450, "description": "Category ID (see the top-level category reference in research/tiktok-shop/06-homepage.md)." }, "required": false, "description": "Category ID (see the top-level category reference in research/tiktok-shop/06-homepage.md).", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "JP", "MX" ], "default": "US", "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "example": "US" }, "required": false, "description": "TikTok Shop storefront to read from. Results, pricing, and availability are region-specific.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } } }, "required": [ "segments" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 1, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": true } }, "/v2/tiktok-shop/products/search": { "get": { "operationId": "Search TikTok Shop Products", "tags": [ "TikTok Shop - Products" ], "summary": "Search products", "description": "Search TikTok Shop products by keyword. Send the response pagination values to continue the search.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "phone", "description": "Keyword to search TikTok Shop products for." }, "required": true, "description": "Keyword to search TikTok Shop products for.", "name": "keyword", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Pagination offset." }, "required": false, "description": "Pagination offset.", "name": "offset", "in": "query" }, { "schema": { "type": "string", "default": "", "description": "Pass the previous response's `load_more_params.page_token` to fetch the next page.", "example": "" }, "required": false, "description": "Pass the previous response's `load_more_params.page_token` to fetch the next page.", "name": "page_token", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "has_more": { "type": "boolean" }, "load_more_params": { "type": "object", "properties": { "offset": { "type": "number" }, "page_token": { "type": "string" }, "api_source": { "type": "number" } }, "additionalProperties": { "nullable": true } } }, "required": [ "products" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/products/search/suggestions": { "get": { "operationId": "Get TikTok Shop Search Suggestions", "tags": [ "TikTok Shop - Products" ], "summary": "Get search suggestions", "description": "Get TikTok Shop autocomplete and related search terms for a keyword.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "phone", "description": "Partial keyword to get search suggestions for." }, "required": true, "description": "Partial keyword to get search suggestions for.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "default": "en-US", "example": "en-US", "description": "Language code for the suggestions." }, "required": false, "description": "Language code for the suggestions.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "nullable": true, "items": { "type": "string" } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/product/detail": { "get": { "operationId": "Get TikTok Shop Product Detail", "tags": [ "TikTok Shop - Product" ], "summary": "Get product details", "description": "Get a TikTok Shop product's media, SKUs, shop data, review summary, and vouchers.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "1732432759321694958", "description": "TikTok Shop product ID (from a search or category result)." }, "required": true, "description": "TikTok Shop product ID (from a search or category result).", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "description": "TikTok Shop region code.", "example": "SG" }, "required": true, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "product_info": { "type": "object", "properties": { "product_model": { "type": "object", "properties": { "product_id": { "type": "string" }, "seller_id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": { "nullable": true } } }, "additionalProperties": { "nullable": true } }, "shop_info": { "type": "object", "additionalProperties": { "nullable": true } }, "reviews_info": { "nullable": true }, "hot_reviews": { "nullable": true }, "vouchers": { "nullable": true }, "category_info": { "nullable": true }, "shop_performance": { "nullable": true } }, "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/product/reviews": { "get": { "operationId": "Get TikTok Shop Product Reviews", "tags": [ "TikTok Shop - Product" ], "summary": "List product reviews", "description": "List customer reviews for a TikTok Shop product. Use the response pagination values to continue the list.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "1729408816995078528", "description": "TikTok Shop product ID." }, "required": true, "description": "TikTok Shop product ID.", "name": "product_id", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1, "description": "Page number. When the response's `has_more` is true, request `page_start + 1` for the next page." }, "required": false, "description": "Page number. When the response's `has_more` is true, request `page_start + 1` for the next page.", "name": "page_start", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "default": 2, "example": 2, "description": "Review sort rule." }, "required": false, "description": "Review sort rule.", "name": "sort_rule", "in": "query" }, { "schema": { "type": "string", "enum": [ "no_filter", "with_media", "verified_purchase" ], "default": "no_filter", "example": "no_filter", "description": "Review filter. no_filter = all reviews, with_media = reviews containing images/video, verified_purchase = verified purchase reviews only." }, "required": false, "description": "Review filter. no_filter = all reviews, with_media = reviews containing images/video, verified_purchase = verified purchase reviews only.", "name": "filter_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "5_star", "4_star", "3_star", "2_star", "1_star" ], "default": "all", "example": "all", "description": "Star rating filter. all = every rating, 5_star..1_star = only reviews with that star rating." }, "required": false, "description": "Star rating filter. all = every rating, 5_star..1_star = only reviews with that star rating.", "name": "filter_value", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "product_reviews": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "has_more": { "anyOf": [ { "type": "boolean" }, { "type": "number" } ] }, "total_reviews": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "review_ratings": { "type": "object", "properties": { "review_count": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "overall_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "rating_result": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" } ] } } }, "additionalProperties": { "nullable": true } } }, "required": [ "product_reviews" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/seller/products": { "get": { "operationId": "Get TikTok Shop Seller Products", "tags": [ "TikTok Shop - Seller" ], "summary": "List seller products", "description": "List a seller's TikTok Shop product catalog in its default order. Send `search_params` from the response to continue the list.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "7495150558072178725", "description": "TikTok Shop seller ID." }, "required": true, "description": "TikTok Shop seller ID.", "name": "seller_id", "in": "query" }, { "schema": { "type": "string", "default": "", "description": "Opaque search/filter params for the seller's product list.", "example": "" }, "required": false, "description": "Opaque search/filter params for the seller's product list.", "name": "search_params", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "products": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, "has_more": { "anyOf": [ { "type": "boolean" }, { "type": "number" } ] }, "next_search_param": { "type": "string" } }, "required": [ "products", "next_search_param" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/categories": { "get": { "operationId": "Get TikTok Shop Categories", "tags": [ "TikTok Shop - Categories" ], "summary": "List categories", "description": "List the TikTok Shop product category tree.", "parameters": [ { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "self": { "type": "object", "properties": { "category_id": { "type": "string" }, "category_level": { "type": "number" }, "is_leaf": { "type": "boolean" }, "parent_category_id": { "type": "string" }, "category_name": { "type": "string" }, "category_name_en": { "type": "string" }, "image_url": { "type": "string" } }, "required": [ "category_id" ], "additionalProperties": { "nullable": true } }, "children": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } } }, "required": [ "self", "children" ], "additionalProperties": { "nullable": true } } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/category/products": { "get": { "operationId": "Get TikTok Shop Category Products", "tags": [ "TikTok Shop - Categories" ], "summary": "List category products", "description": "List TikTok Shop products in a category. Use the response pagination values to continue the list.", "parameters": [ { "schema": { "type": "integer", "nullable": true, "example": 601450, "description": "Category ID from the `/categories` endpoint." }, "required": false, "description": "Category ID from the `/categories` endpoint.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Pagination offset." }, "required": false, "description": "Pagination offset.", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "productList": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "hasMore": { "type": "boolean" } }, "required": [ "productList" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/products/trending": { "get": { "operationId": "Get TikTok Shop Trending Products", "tags": [ "TikTok Shop - Products" ], "summary": "List trending products", "description": "List currently popular TikTok Shop products.", "deprecated": true, "parameters": [ { "schema": { "type": "string", "enum": [ "US", "GB", "SG", "MY", "PH", "TH", "VN", "ID" ], "default": "US", "description": "TikTok Shop region code.", "example": "US" }, "required": false, "description": "TikTok Shop region code.", "name": "region", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 20, "example": 20, "description": "Number of trending products to request in this batch." }, "required": false, "description": "Number of trending products to request in this batch.", "name": "count", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated product IDs already received. Send all collected IDs to request the next batch when hasMore is true." }, "required": false, "description": "Comma-separated product IDs already received. Send all collected IDs to request the next batch when hasMore is true.", "name": "exclude_product_ids", "in": "query" }, { "schema": { "type": "string", "default": true, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "example": "true" }, "required": false, "description": "When false, returns the unshaped source payload — the response shape is NOT guaranteed to match the documented schema.", "name": "clean", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "productList": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": { "nullable": true } } }, "hasMore": { "type": "boolean", "description": "Whether another batch of products is available." } }, "required": [ "productList" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } }, "/v2/tiktok-shop/shop/resolve-share-link": { "get": { "operationId": "Resolve TikTok Shop Share Link", "tags": [ "TikTok Shop - Shop" ], "summary": "Resolve share link", "description": "Resolve a TikTok Shop share link to its seller ID or product ID.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "https://vt.tiktok.com/ZT2AHoGsE/", "description": "TikTok Shop share link (short or full URL). Must be an https URL on vt.tiktok.com, vm.tiktok.com, www.tiktok.com or shop.tiktok.com." }, "required": true, "description": "TikTok Shop share link (short or full URL). Must be an https URL on vt.tiktok.com, vm.tiktok.com, www.tiktok.com or shop.tiktok.com.", "name": "share_link", "in": "query" } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "properties": { "seller_id": { "type": "string" }, "product_id": { "type": "string" }, "resolved_url": { "type": "string" } }, "required": [ "resolved_url" ], "additionalProperties": { "nullable": true } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error422" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "string", "description": "Requests allowed in the current window.", "example": "600" }, "required": true, "description": "Requests allowed in the current window." }, "RateLimit-Remaining": { "schema": { "type": "string", "description": "Requests left in the current window.", "example": "594" }, "required": true, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "string", "description": "Seconds until the current window resets.", "example": "37" }, "required": true, "description": "Seconds until the current window resets." }, "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "503": { "description": "Service Unavailable", "headers": { "Retry-After": { "schema": { "type": "string", "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110.", "example": "37" }, "required": true, "description": "Whole seconds to wait before retrying. Never `0`, per RFC 9110." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error503" } } } } }, "x-credits": 2, "x-audience": "customer", "x-status": "live", "x-product": "tiktok-shop", "x-toolzer-verified": false } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Error400": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "INVALID_REQUEST" }, "status": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad request" }, "retryable": { "type": "boolean", "example": false }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "ErrorDetails": { "type": "object", "nullable": true, "properties": { "reason": { "$ref": "#/components/schemas/ErrorReason" }, "retryAfter": { "type": "number", "description": "Seconds to wait before retrying." }, "worker": { "$ref": "#/components/schemas/ErrorWorkerDetail" } }, "additionalProperties": { "nullable": true }, "description": "Additional error information. Use `code` for error handling; `reason` identifies the cause and may gain new values.", "example": { "reason": "blocked_by_site", "retryAfter": 60 } }, "ErrorReason": { "type": "string", "enum": [ "analysis_failed", "analysis_unavailable", "blocked_by_site", "capacity_exhausted", "capacity_limited", "captcha_required", "cold_blocked", "cursor_invalid", "free_access_cooldown", "free_access_limit", "invalid_parameter", "login_required", "marketplace_unavailable", "media_processing_failed", "media_too_large", "media_unreadable", "mint_capture_miss", "mint_challenge_unsolved", "mint_exit_mismatch", "mint_incomplete", "mint_transport", "mint_unvalidated", "operator_action_required", "parser_contract_broken", "record_not_found", "region_not_supported", "route_not_found", "session_failed", "site_auth_required", "site_refused", "site_rejected", "site_throttled", "site_timeout", "site_unreachable", "under_maintenance", "unsupported_operation", "worker_fault" ], "example": "blocked_by_site" }, "ErrorWorkerDetail": { "type": "object", "properties": { "site": { "type": "string" }, "route": { "type": "string" }, "operation": { "type": "string" }, "status": { "type": "number", "description": "The status the source itself answered with." }, "attempt": { "type": "number" }, "retried": { "type": "boolean" } }, "description": "Additional request diagnostics, including the source status and retry attempts when available.", "example": { "site": "tripadvisor", "route": "tripadvisor.detail", "status": 403 } }, "Error401": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "UNAUTHORIZED" }, "status": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Missing or invalid API key" }, "retryable": { "type": "boolean", "example": false }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "Error429": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "RATE_LIMITED" }, "status": { "type": "number", "example": 429 }, "message": { "type": "string", "example": "Rate limit exceeded" }, "retryable": { "type": "boolean", "example": true }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "Error500": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "SITE_ERROR" }, "status": { "type": "number", "example": 500 }, "message": { "type": "string", "example": "We could not complete this request against the site" }, "retryable": { "type": "boolean", "example": false }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "Error503": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "SITE_UNAVAILABLE" }, "status": { "type": "number", "example": 503 }, "message": { "type": "string", "example": "This site is temporarily unavailable" }, "retryable": { "type": "boolean", "example": true }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "Error402": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "PAYMENT_REQUIRED" }, "status": { "type": "number", "example": 402 }, "message": { "type": "string", "example": "Not enough credits to cover this request" }, "retryable": { "type": "boolean", "example": false }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "Error422": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "INVALID_REQUEST" }, "status": { "type": "number", "example": 422 }, "message": { "type": "string", "example": "The request is valid but cannot be served for this input" }, "retryable": { "type": "boolean", "example": false }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "FacebookPage": { "type": "object", "nullable": true, "properties": { "pageId": { "type": "string", "nullable": true }, "posts": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" } }, "required": [ "pageId", "posts", "pageInfo" ] }, "FacebookPageInfo": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true }, "hasNextPage": { "type": "boolean" } }, "required": [ "cursor", "hasNextPage" ] }, "FacebookAbout": { "type": "object", "nullable": true, "properties": { "sections": { "type": "array", "items": { "type": "object", "properties": { "sectionType": { "type": "string", "nullable": true }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } } }, "required": [ "sectionType", "fields" ] } } }, "required": [ "sections" ] }, "FacebookPosts": { "type": "object", "nullable": true, "properties": { "posts": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" }, "nodeId": { "type": "string" } }, "required": [ "posts", "pageInfo" ] }, "Error404": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "PAYMENT_REQUIRED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "SITE_UNAVAILABLE", "SITE_ERROR", "INTERNAL_ERROR" ], "example": "NOT_FOUND" }, "status": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "Resource not found" }, "retryable": { "type": "boolean", "example": false }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "required": [ "code", "status", "message", "retryable", "details" ] } }, "required": [ "error" ] }, "FacebookCollection": { "type": "object", "nullable": true, "properties": { "collectionId": { "type": "string", "nullable": true }, "totalCount": { "type": "number", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" } }, "required": [ "collectionId", "totalCount", "items", "pageInfo" ] }, "FacebookVideos": { "type": "object", "nullable": true, "properties": { "videos": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" }, "pageTypedId": { "type": "string" } }, "required": [ "videos", "pageInfo" ] }, "FacebookAlbums": { "type": "object", "nullable": true, "properties": { "albums": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" }, "collectionId": { "type": "string" } }, "required": [ "albums", "pageInfo" ] }, "FacebookPost": { "type": "object", "nullable": true, "properties": { "comments": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" } }, "required": [ "comments", "pageInfo" ] }, "FacebookMarketplace": { "type": "object", "nullable": true, "properties": { "listings": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } } }, "required": [ "listings" ] }, "FacebookMarketplaceItem": { "type": "object", "nullable": true, "properties": { "listing": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "related": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } } }, "required": [ "listing", "related" ] }, "FacebookVideoSearch": { "type": "object", "nullable": true, "properties": { "videos": { "type": "array", "items": { "$ref": "#/components/schemas/FacebookVideoSearchResult" } }, "pageInfo": { "$ref": "#/components/schemas/FacebookPageInfo" } }, "required": [ "videos", "pageInfo" ] }, "FacebookVideoSearchResult": { "type": "object", "properties": { "videoId": { "type": "string" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "publishedText": { "type": "string", "nullable": true }, "durationText": { "type": "string", "nullable": true }, "thumbnailUrl": { "type": "string", "nullable": true }, "isLive": { "type": "boolean" }, "owner": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "isVerified": { "type": "boolean" } }, "required": [ "id", "name", "url", "isVerified" ] } }, "required": [ "videoId", "title", "description", "url", "publishedText", "durationText", "thumbnailUrl", "isLive", "owner" ] }, "RedditSubredditPostsResponse": { "type": "object", "nullable": true, "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" }, "description": "The posts, in Reddit's own feed order, de-duplicated by id across however many upstream pages the walk took. Empty for an exhausted feed **and for a community that does not exist** — the two are indistinguishable in Reddit's own response." }, "count": { "type": "number", "example": 25, "description": "**How many posts are in `posts`, counted from the array itself.** It is a count of DISTINCT posts: duplicates Reddit re-serves past about page 6 are dropped before this is taken, so it never overstates what you received.\n\n**It is not a paging signal.** `count < requested_count` means the feed ran out, which `end_of_feed` states directly — that is the field to branch on." }, "requested_count": { "type": "number", "example": 25, "description": "**The `count` this request asked for**, echoed so a comparison against what arrived never rests on two layers agreeing about a default." }, "subreddit": { "type": "string", "nullable": true, "example": "technology", "description": "**The community this request read, after cleaning** — with any `r/` prefix and any pasted URL already reduced away. Echoed so a join against your own input does not depend on normalisation matching." }, "sort": { "type": "string", "nullable": true, "example": "best", "description": "**The sort this request used**, echoed after cleaning so a join against your own input does not rest on a default matching. One of `best`, `hot`, `new`, `top`, `rising`, `controversial`.\n\nThe `time` window is **not** echoed, because the effective one is chosen upstream when you omit it (`ALL` on `top` and `controversial`, nothing anywhere else) and this response would otherwise be asserting a window it did not pick." }, "next_cursor": { "type": "string", "nullable": true, "example": "dDNfMXZheTE5OA==", "description": "**Send this back as `after` to continue. The ONLY authority on whether more posts exist** — never the row count.\n\nIt points at the last post actually RETURNED rather than the last one fetched: the final upstream page usually overshoots `count` and is trimmed, and a cursor pointing past the trim would silently skip the overshoot on your next call.\n\nNull means the feed is exhausted, which `end_of_feed` restates as a boolean. It decodes to `t3_` — not a secret, and not something that expires." }, "end_of_feed": { "type": "boolean", "example": false, "description": "**`true` when there is nothing after this page. Derived from `next_cursor` alone and never from how full the page came back**, because a short page is not an ending: it means the walk hit its own page ceiling or the feed genuinely ran out, and only the cursor tells you which.\n\nThis is the field to loop on." }, "pages_fetched": { "type": "number", "example": 2, "description": "**How many of Reddit's ~24-post pages this call walked to satisfy your `count`.** Published because it is the whole cost model of the endpoint made visible: it is one billed call regardless, and this is the number of round trips you did not have to make. Rising sharply against a steady `count` means Reddit is re-serving posts already seen and the walk is discarding them." }, "usage_note": { "type": "string", "nullable": true, "example": "`count` is satisfied here, not upstream: Reddit serves ~24 posts a page and this walks them for you. A short result is not a short page — it means the feed ran out, and `end_of_feed` says so outright. `next_cursor` is not an opaque server token: it is base64('t3_' + the last post's id), so `after` will also accept that bare post id.", "description": "The two things about this endpoint that produce wrong conclusions if you do not know them — that a short result is an ended feed rather than a short page, and that the cursor is constructible — restated in every response so they travel with the data rather than living only in these docs." } }, "required": [ "posts", "count", "requested_count", "subreddit", "sort", "next_cursor", "end_of_feed", "pages_fetched", "usage_note" ] }, "RedditPost": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "1vay198", "description": "**Reddit's base36 post id** — the `1vay198` in a permalink. This is also the value `after` takes, so walking a feed needs nothing constructed and nothing guessed." }, "fullname": { "type": "string", "nullable": true, "example": "t3_1vay198", "description": "Reddit's own `t3_`-prefixed identifier for the post — the form its internals speak. `after` accepts this too." }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vay198/example_post_title/", "description": "The site-relative path to the post's comment page, as Reddit states it. `url` is the same thing absolute." }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/r/technology/comments/1vay198/example/", "description": "**The post's page on reddit.com.** Note what it is NOT: the thing the post links to. That is `content_url`, and on a link post the two point at completely different places." }, "title": { "type": "string", "nullable": true, "example": "Example post title", "description": "The post title, as submitted." }, "subreddit": { "type": "string", "nullable": true, "example": "technology", "description": "The community the post lives in, bare. Worth reading rather than assuming it equals what you asked for — a feed can carry cross-posted rows." }, "subreddit_prefixed": { "type": "string", "nullable": true, "example": "r/technology", "description": "The same name in Reddit's display form." }, "subreddit_id": { "type": "string", "nullable": true, "example": "t5_2qh16", "description": "Reddit's `t5_` id for the community. Stable across a rename, which the name is not." }, "author": { "type": "string", "nullable": true, "example": "example_user", "description": "The posting account's username, without `u/`. Deleted accounts publish as Reddit's own placeholder rather than as null." }, "author_id": { "type": "string", "nullable": true, "example": "t2_abc123", "description": "Reddit's `t2_` id for the account. Survives a rename." }, "author_icon": { "type": "string", "nullable": true, "example": null, "description": "The author's avatar, when the card carried one. Null is common and means the fragment did not include it — not that the account has no avatar." }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000", "description": "**When the post was submitted, in Reddit's own ISO 8601 form** with milliseconds and a `+0000` offset. Republished verbatim rather than reformatted: rewriting a timestamp is a good way to introduce a timezone bug into data that did not have one." }, "score": { "type": "number", "nullable": true, "example": 1284, "description": "**Net score — upvotes minus downvotes, as Reddit displays it.** The breakdown does not exist anywhere in this payload: Reddit publishes the net figure and `upvote_ratio` and nothing else, so ups and downs cannot be recovered from here by anyone, including us." }, "upvote_ratio": { "type": "number", "nullable": true, "example": 0.94, "description": "The share of votes that were upvotes, 0-1. Together with `score` it is the whole of what Reddit says about voting on a post." }, "comment_count": { "type": "number", "nullable": true, "example": 213, "description": "How many comments the post has. **The comments themselves are not available on this API** — see the tag description." }, "award_count": { "type": "number", "nullable": true, "example": 0, "description": "How many awards the post carries. A count only; the award detail is not in a feed fragment." }, "domain": { "type": "string", "nullable": true, "example": "arstechnica.com", "description": "**The host `content_url` points at, and the field that says what kind of post this is at a glance**: an external host for a link post, `i.redd.it` / `v.redd.it` for uploaded media, `self.` for a text post." }, "content_url": { "type": "string", "nullable": true, "example": "https://arstechnica.com/example-article/", "description": "**What the post points at** — the outbound link on a link post, the media URL on an image or video one. Reddit does not separate those two, so neither does this; `domain` is how you tell which you have. For the post's own Reddit page, read `url`." }, "post_type": { "type": "string", "nullable": true, "example": "link", "description": "Reddit's own classification: `link`, `image`, `video`, `gallery`, `text` or `multi_media`. It is the cheapest way to predict whether `text` and `media` will be populated." }, "flair": { "type": "string", "nullable": true, "example": "Society", "description": "The post's flair label, when it has one. Most posts do not, and the flair element is present-but-empty on those — so null here means 'no flair' rather than 'not parsed'." }, "flair_url": { "type": "string", "nullable": true, "example": "/r/technology/?f=flair_name%3A%22Society%22", "description": "Reddit's own link to the community filtered by this flair. Useful as a facet; not a value to key on." }, "thumbnail": { "type": "string", "nullable": true, "example": "https://external-preview.redd.it/example.jpg", "description": "**The card thumbnail — anchored on Reddit's own thumbnail marker, not 'the first image in the card'.** That distinction is measured: on posts whose author has a custom avatar the first image is the avatar, and seven of the 24 posts in the reference capture are exactly that shape. Null on posts with no thumbnail." }, "media": { "$ref": "#/components/schemas/RedditPostMedia" }, "text": { "type": "string", "nullable": true, "example": null, "description": "**The post body, and only self posts have one.** Measured on the same 24-post fragment: null for every post. A link post's body IS empty — the link is the content — so null here is a fact about the post rather than a gap in the parse." }, "nsfw": { "type": "boolean", "nullable": true, "example": null, "description": "**Tri-state, and null does NOT mean 'safe'.** `` carries no NSFW attribute at all; the only signal in the markup rides on the media lightbox element, which appears on **image posts and nothing else** — measured across a 30-post capture, present on the 10 image posts and absent from every video, gallery, link and text post.\n\nSo this is `true`/`false` on an image post and **`null` (unknown) on every other kind**, which is most of a feed. Publishing null as `false` would be asserting something Reddit never said. **Do not use this field to build a safe-content filter** — it cannot support one." }, "spoiler": { "type": "boolean", "example": false, "description": "Whether the post is marked as a spoiler. A real boolean: Reddit sets the attribute only when true, so absence is a measured `false`." }, "locked": { "type": "boolean", "example": false, "description": "Whether commenting is locked. A real boolean, same as `spoiler`." }, "archived": { "type": "boolean", "example": false, "description": "Whether the post is archived (too old to vote or comment on). A real boolean, same as `spoiler`." }, "language": { "type": "string", "nullable": true, "example": "en", "description": "Reddit's own language tag for the post." } }, "required": [ "id", "fullname", "permalink", "url", "title", "subreddit", "subreddit_prefixed", "subreddit_id", "author", "author_id", "author_icon", "created_at", "score", "upvote_ratio", "comment_count", "award_count", "domain", "content_url", "post_type", "flair", "flair_url", "thumbnail", "media", "text", "nsfw", "spoiler", "locked", "archived", "language" ] }, "RedditPostMedia": { "type": "object", "nullable": true, "properties": { "kind": { "type": "string", "nullable": true, "example": "image", "description": "`image`, `video` or `gallery` — which of the three shapes below the rest of this object is in. Read it before reading anything else here: the fields that are populated depend on it entirely." }, "url": { "type": "string", "nullable": true, "example": "https://i.redd.it/example.jpeg", "description": "**The canonical media URL** — `i.redd.it` for an image, the HLS playlist (`v.redd.it/.../HLSPlaylist.m3u8`) for a video. On a gallery this is the cover rather than a page; the pages are in `items`." }, "poster": { "type": "string", "nullable": true, "example": null, "description": "**Video only.** The still frame shown before playback." }, "preview": { "type": "string", "nullable": true, "example": null, "description": "**Video only.** The short silent mp4 Reddit autoplays in the feed. Not the full video — that is the HLS playlist in `url`." }, "caption_url": { "type": "string", "nullable": true, "example": null, "description": "**Video only.** The caption track, when the post has one." }, "items": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": null, "description": "**Gallery only.** The individual pages, in the order Reddit lays them out. Null on every other kind — an empty array would claim a gallery with no pages." } }, "required": [ "kind", "url", "poster", "preview", "caption_url", "items" ], "description": "**Media for the post, and genuinely null on most rows.** Measured on a real 24-post fragment of a link-heavy community: null for every single post. It is populated on image, video and gallery posts and on nothing else, so treat its absence as the normal case rather than as a parse failure — `post_type` predicts it.\n\nOne record for all three kinds: read `kind` first, and the slots the other kinds do not use are null." }, "RedditSearchResponse": { "type": "object", "nullable": true, "properties": { "results": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RedditSearchPost" }, { "$ref": "#/components/schemas/RedditSearchSubreddit" }, { "$ref": "#/components/schemas/RedditSearchComment" }, { "$ref": "#/components/schemas/RedditSearchUser" } ] }, "description": "**The results, in Reddit's own ranked order, de-duplicated by fullname.** Four record shapes, one per corpus, and every row states its own `kind` — `post`, `subreddit`, `comment` or `user`. Branch on that before reading anything else.\n\n**`type=media` returns `kind: \"post\"` rows**, because that is what they are: posts rendered through a media unit, carrying a `media` URL and no counters.\n\nEmpty is a normal answer for a query with no matches." }, "query": { "type": "string", "nullable": true, "example": "chatgpt", "description": "**The query this request ran**, echoed after trimming." }, "type": { "type": "string", "nullable": true, "example": "posts", "description": "**The corpus this request searched**, echoed after cleaning so a join against your own input does not rest on a default matching. One of `posts`, `communities`, `comments`, `people`, `media`." }, "count": { "type": "number", "example": 25, "description": "**How many results are in `results`, counted from the array itself** — distinct results, since search pages repeat and the duplicates are dropped before this is taken." }, "requested_count": { "type": "number", "example": 25, "description": "**The `count` this request asked for**, echoed. On `type=people` expect `count` to fall well short of it; that corpus is one page." }, "next_cursor": { "type": "string", "nullable": true, "example": null, "description": "**Always null on this endpoint, and that is a decision rather than a gap.**\n\nSearch's cursor is the one on this site we cannot construct — it is base64 of Reddit's ranking-pipeline state, not of a fullname — so it cannot be re-aimed at the trimmed list a response actually returns. Publishing the cursor of the last page FETCHED would silently skip the overshoot between `count` and the page boundary. **Raise `count` to go deeper.**\n\nThe field exists so that a caller writing one paging loop across this plane finds the shape they expect, and finds it saying 'no more from here'." }, "end_of_feed": { "type": "boolean", "example": false, "description": "**`true` when the walk reached the end of the corpus rather than the end of your `count`.** Unlike the feed endpoints this is not derived from a cursor — there is none — it is the walk reporting that Reddit stopped handing back pages.\n\n**On `type=people` expect it `true` almost immediately**: that corpus is one short page and then no cursor at all." }, "pages_fetched": { "type": "number", "example": 4, "description": "**How many search pages this call walked.** Pages are small (7-14 results) and repeat, so this runs higher against a given `count` than a feed endpoint's would." }, "usage_note": { "type": "string", "nullable": true, "example": "Search pages are small (7-14 results) and repeat across pages, so `count` counts distinct results. Search records are genuinely thinner than feed rows — Reddit renders them as SDUI markup with no post elements at all, so score and comment count come from the visible counter row and are null wherever the renderer omits it (all media results, for instance). type=people returns one short page and then no cursor; a small result there is the corpus, not an error. Raise `count` to go deeper — the cursor is not exposed because it cannot be re-aimed at a trimmed list.", "description": "Why these records are thinner than feed rows, why `people` is short, and why depth is controlled with `count` rather than a cursor — restated in every response." } }, "required": [ "results", "query", "type", "count", "requested_count", "next_cursor", "end_of_feed", "pages_fetched", "usage_note" ] }, "RedditSearchPost": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "nullable": true, "example": "1vay198" }, "fullname": { "type": "string", "nullable": true, "example": "t3_1vay198" }, "title": { "type": "string", "nullable": true, "example": "Example post title" }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vay198/example/" }, "author": { "type": "string", "nullable": true, "example": "example_user" }, "author_id": { "type": "string", "nullable": true, "example": "t2_abc123" }, "subreddit": { "type": "string", "nullable": true, "example": "technology" }, "subreddit_id": { "type": "string", "nullable": true, "example": "t5_2qh16" }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000" }, "score": { "type": "number", "nullable": true, "example": 1284, "description": "**Net score, read off the visible counter row** — the only place a score appears in search markup at all. **Null on every `type=media` result**, because the media unit renders no counter row; that is a property of the renderer rather than of the post, and null here is 'not rendered' rather than zero." }, "comment_count": { "type": "number", "nullable": true, "example": 213, "description": "How many comments the post has, from the same counter row as `score` — and null on media results for the same reason." }, "nsfw": { "type": "boolean", "nullable": true, "example": false, "description": "**Whether Reddit marks the post NSFW. This is the ONE surface on this API where the flag is stated rather than inferred** — search's telemetry context carries it for every result, unlike a feed fragment where it only exists on image posts.\n\n**It is still nullable and null still means unknown, not safe.** A result whose context omits the field publishes null, and **no NSFW filter is offered on this endpoint** — a filter built on a field that can be unknown is a filter that fails silently." }, "spoiler": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the post is marked as a spoiler, from the same telemetry context. Nullable for the same reason `nsfw` is." }, "subreddit_nsfw": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the COMMUNITY is marked NSFW — a different claim from the post's own flag, and stated separately by Reddit. Null means the context did not say." }, "snippet": { "type": "string", "nullable": true, "example": null, "description": "**Reddit's own matched excerpt**, present when the hit was on a comment under the post rather than on its title. Null when the match was the title itself." }, "snippet_fullname": { "type": "string", "nullable": true, "example": null, "description": "The fullname of the thing the `snippet` came from — normally the matching comment, which is how you get from the excerpt to its source." }, "media": { "type": "string", "nullable": true, "example": null, "description": "**The full-size image on a `type=media` result**, anchored on Reddit's own primary-media marker rather than on 'the first image in the block' — that block also holds a blurred background copy and the community icon. Null on every other search type." } }, "required": [ "kind", "id", "fullname", "title", "permalink", "author", "author_id", "subreddit", "subreddit_id", "created_at", "score", "comment_count", "nsfw", "spoiler", "subreddit_nsfw", "snippet", "snippet_fullname", "media" ], "description": "**A post as SEARCH states it — thinner than the same post in a feed, because search renders less.** No upvote ratio, no flair, no body, no media beyond the media unit's own image: those are not omitted here, they are absent from the markup search serves. Read `/v1/reddit/post-details` for the full record of any post you find." }, "RedditSearchSubreddit": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "subreddit" ], "example": "subreddit" }, "id": { "type": "string", "nullable": true, "example": "2qh16" }, "fullname": { "type": "string", "nullable": true, "example": "t5_2qh16" }, "name": { "type": "string", "nullable": true, "example": "technology" }, "prefixed_name": { "type": "string", "nullable": true, "example": "r/technology" }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/r/technology/" }, "description": { "type": "string", "nullable": true, "example": "Subreddit dedicated to the news and discussions about…" }, "weekly_visitors": { "type": "number", "nullable": true, "example": 4305645, "description": "**Reddit's own weekly-visitor figure. NOT a subscriber count** — no subscriber total is exposed on any surface reachable without a login, and publishing this as one would answer that question wrongly." }, "weekly_contributions": { "type": "number", "nullable": true, "example": 1204 }, "icon": { "type": "string", "nullable": true, "example": null }, "nsfw": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the community is marked NSFW, as Reddit's own telemetry context states it. **Null means unknown, not safe.**" }, "quarantined": { "type": "boolean", "nullable": true, "example": false } }, "required": [ "kind", "id", "fullname", "name", "prefixed_name", "url", "description", "weekly_visitors", "weekly_contributions", "icon", "nsfw", "quarantined" ], "description": "**A community result.** The two numbers are Reddit's weekly visitor and contribution figures — neither is a member count, which this site does not publish anywhere logged-out." }, "RedditSearchComment": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "comment" ], "example": "comment" }, "id": { "type": "string", "nullable": true, "example": "p44qdpd" }, "fullname": { "type": "string", "nullable": true, "example": "t1_p44qdpd" }, "post_fullname": { "type": "string", "nullable": true, "example": "t3_1vay198" }, "post_title": { "type": "string", "nullable": true, "example": "Example post title" }, "subreddit": { "type": "string", "nullable": true, "example": "technology" }, "subreddit_id": { "type": "string", "nullable": true, "example": "t5_2qh16" }, "author": { "type": "string", "nullable": true, "example": "example_user", "description": "**The commenting account.** It is a bare text node in search markup with no attribute and no test hook on it, so it is matched narrowly and allowed to fail: null here means the parse declined to guess rather than that the comment has no author." }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vay198/example/p44qdpd/" }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000" }, "body": { "type": "string", "nullable": true, "example": "The matched comment text." }, "nsfw": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the POST the comment is on is marked NSFW — Reddit states the post's flag here, not the comment's. **Null means unknown.**" } }, "required": [ "kind", "id", "fullname", "post_fullname", "post_title", "subreddit", "subreddit_id", "author", "permalink", "created_at", "body", "nsfw" ], "description": "**A comment result, scoped to the comment rather than to the post it sits under.** A search comment block renders the post's permalink, title and timestamp above the comment's own; the fields here are read from inside the comment's block so the two cannot be confused." }, "RedditSearchUser": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user" ], "example": "user" }, "id": { "type": "string", "nullable": true, "example": "abc123" }, "fullname": { "type": "string", "nullable": true, "example": "t2_abc123" }, "name": { "type": "string", "nullable": true, "example": "spez" }, "prefixed_name": { "type": "string", "nullable": true, "example": "u/spez" }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/user/spez/" }, "karma": { "type": "number", "nullable": true, "example": 940933 }, "description": { "type": "string", "nullable": true, "example": null }, "icon": { "type": "string", "nullable": true, "example": null } }, "required": [ "kind", "id", "fullname", "name", "prefixed_name", "url", "karma", "description", "icon" ], "description": "**An account result — only returned by `type=people`, which is one short page and then ends.** Measured: 4 results, then no cursor at all. A `count` of 50 coming back as 4 is the corpus, not a failure." }, "RedditPopularPostsResponse": { "type": "object", "nullable": true, "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" }, "description": "The posts, in the order Reddit served them, de-duplicated by id across however many pages the walk took.\n\n**Ordering is not stable across calls.** This feed re-ranks between requests — two identical calls shared 23 of 25 posts rather than 25 — so the same `count` asked for twice is a similar set in a possibly different order, not a repeatable page. Treat it as a sample of what is popular now." }, "count": { "type": "number", "example": 25, "description": "**How many posts are in `posts`, counted from the array itself** — and DISTINCT posts, which on this feed is the whole point. An 8-page walk saw a 22.5% duplicate rate; those are dropped before this is taken, so it never overstates what you received.\n\n**It is not a paging signal.** `end_of_feed` is." }, "requested_count": { "type": "number", "example": 25, "description": "**The `count` this request asked for**, echoed so a comparison against what arrived never rests on two layers agreeing about a default." }, "next_cursor": { "type": "string", "nullable": true, "example": "dDNfMXZheTE5OA==", "description": "**Send this back as `after` to continue. The only authority on whether more posts exist** — never the row count.\n\nIt is built here rather than read from Reddit, which ships no cursor for this feed at all: it is `base64('t3_' + the last RETURNED post's id)`, so `after` equally accepts that bare id. Pointing at the last returned post rather than the last fetched one is what stops a resume skipping the final page's overshoot.\n\nNull means the walk reached the end, which `end_of_feed` restates." }, "end_of_feed": { "type": "boolean", "example": false, "description": "**`true` when there is nothing after this page. Derived from `next_cursor` alone and never from how full the page came back.** This is the field to loop on." }, "pages_fetched": { "type": "number", "example": 3, "description": "**How many of Reddit's pages this call walked.** Expect it to run higher here than on `/v1/reddit/subreddit-posts` for the same `count`: this feed re-serves posts already seen at a measured 22.5% rate and the walk discards them, so roughly a quarter of the pages buy nothing." }, "usage_note": { "type": "string", "nullable": true, "example": "r/popular re-ranks between calls: two identical requests share about 23 of 25 posts and an 8-page walk returns roughly 155 distinct posts out of 200 rows. `count` here is DISTINCT posts, so a walk of this feed is about 25% less efficient than its page size suggests. Reddit ships no cursor for this feed, so `next_cursor` is base64('t3_' + the last post's id), built here; `after` will equally accept that bare post id.", "description": "The things about this feed that produce wrong conclusions if you do not know them — that it samples as much as it pages, and that the cursor is constructible — restated in every response so they travel with the data." } }, "required": [ "posts", "count", "requested_count", "next_cursor", "end_of_feed", "pages_fetched", "usage_note" ] }, "RedditUserPostsResponse": { "type": "object", "nullable": true, "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RedditProfilePost" }, { "$ref": "#/components/schemas/RedditProfileComment" } ] }, "description": "**The feed, in Reddit's own order, with posts and comments interleaved.** Every row carries `kind` — `post` or `profile_comment` — and the two shapes are genuinely different records rather than one shape with empty halves. Branch on `kind` before reading anything else.\n\nDe-duplicated by id across the walk. Empty for an exhausted feed **and for an account that does not exist**, which Reddit's fragment does not distinguish." }, "username": { "type": "string", "nullable": true, "example": "spez", "description": "**The account this request read, after cleaning** — with any `u/` prefix and any pasted URL already reduced away." }, "include": { "type": "string", "nullable": true, "example": "all", "description": "**The `include` this request applied**, echoed after cleaning so a join against your own input does not rest on a default matching. One of `all`, `posts`, `comments`." }, "count": { "type": "number", "example": 25, "description": "**How many rows are in `items`, counted from the array itself** — after `include` was applied, so on a filtered request this is what survived the filter rather than what was fetched.\n\n**A short count is not a paging signal**; `end_of_feed` is." }, "post_count": { "type": "number", "example": 2, "description": "**How many of `items` are posts.** Published beside `comment_count` because the mix is the surprising part of this feed: an active account runs roughly 1 post to 10 comments, and seeing that ratio in the response is what explains a slow `include=posts` walk." }, "comment_count": { "type": "number", "example": 23, "description": "**How many of `items` are comments.** Together with `post_count` it sums to `count`." }, "requested_count": { "type": "number", "example": 25, "description": "**The `count` this request asked for**, echoed." }, "next_cursor": { "type": "string", "nullable": true, "example": "dDFfcDQ0cWRwZA==", "description": "**Send this back as `after` to continue. The only authority on whether more items exist** — never the row count.\n\n**It is built from the last ITEM, not the last post**, and that is what keeps a walk moving: this feed's cursor is the last element whatever kind it is, so it is normally a comment's `t1_` fullname. A cursor built from the last POST instead does not error — it re-serves the same page indefinitely.\n\n**It points at the last item RETURNED, which on a filtered request is the last item KEPT.** Null means the walk ended, which `end_of_feed` restates." }, "end_of_feed": { "type": "boolean", "example": false, "description": "**`true` when there is nothing after this page. Derived from `next_cursor` alone and never from how full the page came back.**\n\n**On `include=posts` this is the field that tells you what a short result meant**: `false` with fewer rows than you asked for means the walk hit its page budget while filtering, not that the account ran out. Send the cursor back and keep going." }, "pages_fetched": { "type": "number", "example": 4, "description": "**How many of Reddit's pages this call walked.** On `include=posts` expect it to be high against a small `count` — roughly one row in ten of an active account's overview is a post, and the filter runs after the page is fetched." }, "usage_note": { "type": "string", "nullable": true, "example": "Reddit's 'overview' is ONE feed carrying posts and comments interleaved, with no server-side filter — every row says which it is in `kind`, and `include` filters them here rather than upstream. An active account runs roughly 1 post to 10 comments, so include=posts walks a lot of pages for a few rows and may return fewer than `count`; `end_of_feed` says whether that was the account ending or the page budget. `next_cursor` is normally a COMMENT's fullname, because this feed's cursor is the last item and the last item is usually a comment.", "description": "The three things about this feed that produce wrong conclusions if you do not know them — that it interleaves, that `include` filters after the walk, and that the cursor is an item rather than a post — restated in every response." } }, "required": [ "items", "username", "include", "count", "post_count", "comment_count", "requested_count", "next_cursor", "end_of_feed", "pages_fetched", "usage_note" ] }, "RedditProfilePost": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "post" ], "example": "post", "description": "**Always `post` on this row.** Read it before anything else: the overview feed interleaves posts and comments, and the two carry different fields." }, "id": { "type": "string", "nullable": true, "example": "1vay198", "description": "**Reddit's base36 post id** — the `1vay198` in a permalink. This is also the value `after` takes, so walking a feed needs nothing constructed and nothing guessed." }, "fullname": { "type": "string", "nullable": true, "example": "t3_1vay198", "description": "Reddit's own `t3_`-prefixed identifier for the post — the form its internals speak. `after` accepts this too." }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vay198/example_post_title/", "description": "The site-relative path to the post's comment page, as Reddit states it. `url` is the same thing absolute." }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/r/technology/comments/1vay198/example/", "description": "**The post's page on reddit.com.** Note what it is NOT: the thing the post links to. That is `content_url`, and on a link post the two point at completely different places." }, "title": { "type": "string", "nullable": true, "example": "Example post title", "description": "The post title, as submitted." }, "subreddit": { "type": "string", "nullable": true, "example": "technology", "description": "The community the post lives in, bare. Worth reading rather than assuming it equals what you asked for — a feed can carry cross-posted rows." }, "subreddit_prefixed": { "type": "string", "nullable": true, "example": "r/technology", "description": "The same name in Reddit's display form." }, "subreddit_id": { "type": "string", "nullable": true, "example": "t5_2qh16", "description": "Reddit's `t5_` id for the community. Stable across a rename, which the name is not." }, "author": { "type": "string", "nullable": true, "example": "example_user", "description": "The posting account's username, without `u/`. Deleted accounts publish as Reddit's own placeholder rather than as null." }, "author_id": { "type": "string", "nullable": true, "example": "t2_abc123", "description": "Reddit's `t2_` id for the account. Survives a rename." }, "author_icon": { "type": "string", "nullable": true, "example": null, "description": "The author's avatar, when the card carried one. Null is common and means the fragment did not include it — not that the account has no avatar." }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000", "description": "**When the post was submitted, in Reddit's own ISO 8601 form** with milliseconds and a `+0000` offset. Republished verbatim rather than reformatted: rewriting a timestamp is a good way to introduce a timezone bug into data that did not have one." }, "score": { "type": "number", "nullable": true, "example": 1284, "description": "**Net score — upvotes minus downvotes, as Reddit displays it.** The breakdown does not exist anywhere in this payload: Reddit publishes the net figure and `upvote_ratio` and nothing else, so ups and downs cannot be recovered from here by anyone, including us." }, "upvote_ratio": { "type": "number", "nullable": true, "example": 0.94, "description": "The share of votes that were upvotes, 0-1. Together with `score` it is the whole of what Reddit says about voting on a post." }, "comment_count": { "type": "number", "nullable": true, "example": 213, "description": "How many comments the post has. **The comments themselves are not available on this API** — see the tag description." }, "award_count": { "type": "number", "nullable": true, "example": 0, "description": "How many awards the post carries. A count only; the award detail is not in a feed fragment." }, "domain": { "type": "string", "nullable": true, "example": "arstechnica.com", "description": "**The host `content_url` points at, and the field that says what kind of post this is at a glance**: an external host for a link post, `i.redd.it` / `v.redd.it` for uploaded media, `self.` for a text post." }, "content_url": { "type": "string", "nullable": true, "example": "https://arstechnica.com/example-article/", "description": "**What the post points at** — the outbound link on a link post, the media URL on an image or video one. Reddit does not separate those two, so neither does this; `domain` is how you tell which you have. For the post's own Reddit page, read `url`." }, "post_type": { "type": "string", "nullable": true, "example": "link", "description": "Reddit's own classification: `link`, `image`, `video`, `gallery`, `text` or `multi_media`. It is the cheapest way to predict whether `text` and `media` will be populated." }, "flair": { "type": "string", "nullable": true, "example": "Society", "description": "The post's flair label, when it has one. Most posts do not, and the flair element is present-but-empty on those — so null here means 'no flair' rather than 'not parsed'." }, "flair_url": { "type": "string", "nullable": true, "example": "/r/technology/?f=flair_name%3A%22Society%22", "description": "Reddit's own link to the community filtered by this flair. Useful as a facet; not a value to key on." }, "thumbnail": { "type": "string", "nullable": true, "example": "https://external-preview.redd.it/example.jpg", "description": "**The card thumbnail — anchored on Reddit's own thumbnail marker, not 'the first image in the card'.** That distinction is measured: on posts whose author has a custom avatar the first image is the avatar, and seven of the 24 posts in the reference capture are exactly that shape. Null on posts with no thumbnail." }, "media": { "$ref": "#/components/schemas/RedditPostMedia" }, "text": { "type": "string", "nullable": true, "example": null, "description": "**The post body, and only self posts have one.** Measured on the same 24-post fragment: null for every post. A link post's body IS empty — the link is the content — so null here is a fact about the post rather than a gap in the parse." }, "nsfw": { "type": "boolean", "nullable": true, "example": null, "description": "**Tri-state, and null does NOT mean 'safe'.** `` carries no NSFW attribute at all; the only signal in the markup rides on the media lightbox element, which appears on **image posts and nothing else** — measured across a 30-post capture, present on the 10 image posts and absent from every video, gallery, link and text post.\n\nSo this is `true`/`false` on an image post and **`null` (unknown) on every other kind**, which is most of a feed. Publishing null as `false` would be asserting something Reddit never said. **Do not use this field to build a safe-content filter** — it cannot support one." }, "spoiler": { "type": "boolean", "example": false, "description": "Whether the post is marked as a spoiler. A real boolean: Reddit sets the attribute only when true, so absence is a measured `false`." }, "locked": { "type": "boolean", "example": false, "description": "Whether commenting is locked. A real boolean, same as `spoiler`." }, "archived": { "type": "boolean", "example": false, "description": "Whether the post is archived (too old to vote or comment on). A real boolean, same as `spoiler`." }, "language": { "type": "string", "nullable": true, "example": "en", "description": "Reddit's own language tag for the post." } }, "required": [ "kind", "id", "fullname", "permalink", "url", "title", "subreddit", "subreddit_prefixed", "subreddit_id", "author", "author_id", "author_icon", "created_at", "score", "upvote_ratio", "comment_count", "award_count", "domain", "content_url", "post_type", "flair", "flair_url", "thumbnail", "media", "text", "nsfw", "spoiler", "locked", "archived", "language" ] }, "RedditProfileComment": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "profile_comment" ], "example": "profile_comment", "description": "**Always `profile_comment` on this row**, and the name is a warning as much as a label: this is a PROFILE-feed comment, which is a thinner record than the comment-tree shape `/v1/reddit/post-comments` returns." }, "id": { "type": "string", "nullable": true, "example": "p44qdpd", "description": "Reddit's base36 comment id. This is also what `after` takes, so resuming a walk needs nothing constructed." }, "fullname": { "type": "string", "nullable": true, "example": "t1_p44qdpd", "description": "Reddit's `t1_`-prefixed identifier for the comment. `after` accepts this too." }, "body": { "type": "string", "nullable": true, "example": "This is the comment text as rendered.", "description": "**The comment text.** Decoded out of Reddit's rich-text JSON payload rather than lifted from the rendered HTML, so it carries no markup." }, "score": { "type": "number", "nullable": true, "example": 42, "description": "Net score. It rides on the nested action row rather than on the comment element itself, so null means the fragment did not render one — a hidden or very new score — rather than a score of zero." }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000", "description": "When the comment was posted, in Reddit's own ISO 8601 form, verbatim." }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vay198/example/p44qdpd/", "description": "The site-relative path to the comment in its own thread — the way to get from this row to its context." }, "subreddit": { "type": "string", "nullable": true, "example": "technology", "description": "**The community the comment was made in.** The one thing this shape has that the comment-tree shape does not need, because a profile feed spans posts and communities." } }, "required": [ "kind", "id", "fullname", "body", "score", "created_at", "permalink", "subreddit" ], "description": "**A comment as a profile feed states it — deliberately thinner than a comment-tree row, because the source is thinner.**\n\n`` is a different element from the one a post page renders: it carries no parent, no depth, no reply structure and no author (you asked for the account, so the author is the account). Those fields are ABSENT here rather than published as permanent nulls — a `depth: 0` on every row would imply a tree this feed has no place in.\n\nFor depth, parentage and reply structure, read `/v1/reddit/post-comments`." }, "RedditUserCommentsResponse": { "type": "object", "nullable": true, "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/RedditProfileComment" }, "description": "The account's comments, newest first, de-duplicated by id across the walk. Empty for an account with no comments **and for one that does not exist** — Reddit's fragment does not distinguish them." }, "username": { "type": "string", "nullable": true, "example": "spez", "description": "**The account this request read, after cleaning** — with any `u/` prefix and any pasted URL already reduced away." }, "count": { "type": "number", "example": 25, "description": "**How many comments are in `comments`, counted from the array itself.** Distinct ids: this feed measured zero duplicates over 8 pages, so the de-duplication behind it has nothing to do here — but it runs anyway, and this is counted after it." }, "requested_count": { "type": "number", "example": 25, "description": "**The `count` this request asked for**, echoed." }, "next_cursor": { "type": "string", "nullable": true, "example": "dDFfcDQ0cWRwZA==", "description": "**Send this back as `after` to continue.** It is `base64('t1_' + the last RETURNED comment's id)`, so `after` equally accepts that bare id. Null means the account ran out, which `end_of_feed` restates — and on this feed, unlike the others here, that reading is well supported by measurement." }, "end_of_feed": { "type": "boolean", "example": false, "description": "**`true` when the account has no more comments. Derived from `next_cursor` alone.** This is the field to loop on." }, "pages_fetched": { "type": "number", "example": 1, "description": "**How many of Reddit's ~25-comment pages this call walked.** It tracks `count / 25` closely here, because this is the one feed on this API that measured no duplicates at all." }, "usage_note": { "type": "string", "nullable": true, "example": "`count` is satisfied by walking Reddit's ~25-comment pages. This feed measured 200 comments with 200 distinct ids over 8 pages, so unlike the subreddit and popular feeds a short result here really does mean the account ran out of comments. These rows are a profile shape, not a comment-tree shape: they carry the body, score and permalink but no parent, no depth and no replies, because a profile feed spans posts and has no tree to be at a depth in. `next_cursor` is base64('t1_' + the last comment's id).", "description": "What a short result means on this feed (the account ran out) and what these rows are not (a comment tree), restated in every response." } }, "required": [ "comments", "username", "count", "requested_count", "next_cursor", "end_of_feed", "pages_fetched", "usage_note" ] }, "RedditPostCommentsResponse": { "type": "object", "nullable": true, "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" }, "description": "**The comments collected, FLAT, in prefix order** — the tree read depth-first, de-duplicated by id. Rebuild the nesting from `depth` and `parent_fullname`, both of which Reddit states.\n\n**This is a partial read of the tree unless `end_of_tree` is true.** Read `unfollowed_branches` and `truncated_threads` before treating it as the post's comments." }, "subreddit": { "type": "string", "nullable": true, "example": "technology", "description": "**The community this request read**, after cleaning." }, "post_id": { "type": "string", "nullable": true, "example": "1vqcqpz", "description": "**The post this request read**, after cleaning — with any `t3_` prefix and any pasted permalink already reduced away." }, "post_fullname": { "type": "string", "nullable": true, "example": "t3_1vqcqpz" }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vqcqpz/example_post_title/", "description": "**The post's canonical permalink, slug included** — read from Reddit's own comment-tree element rather than assembled. The slug is not cosmetic: the same post id without it answers 500 with an empty body, and a slug cannot be derived from an id." }, "sort": { "type": "string", "nullable": true, "example": "CONFIDENCE", "description": "**The sort actually in effect.** Your `sort` when you sent one; otherwise Reddit's own default as IT names it, which is `CONFIDENCE` — a value this API does not accept as an input, because no spelling of it has been measured as one. So this field is echoed in two different vocabularies by design, and it is the honest way to say which ordering you got." }, "total_comments": { "type": "number", "nullable": true, "example": 226, "description": "**Reddit's own total for the post — the denominator to judge `count` against.** It is what the site displays, and it counts the whole tree including branches this call did not follow. `count` well below it with `end_of_tree: false` is a partial read, not a discrepancy." }, "count": { "type": "number", "example": 25, "description": "**How many comments are in `comments`, counted from the array itself** — distinct comments, de-duplicated across every branch the walk followed.\n\n**Never read it as 'the post has this many comments'**; that is `total_comments`." }, "requested_count": { "type": "number", "example": 25, "description": "**The `count` this request asked for**, echoed." }, "end_of_tree": { "type": "boolean", "example": false, "description": "**`true` only when the whole tree was read: no branch left queued AND no thread left truncated.** It is the single field that says whether `comments` is the post's comments or a slice of them.\n\n**A short `comments` array does not imply this.** Following one branch of a 226-comment post to exhaustion reached 52 comments and reported no onward cursor — which reads exactly like a finished tree if you only count rows. That is the failure this field exists to prevent." }, "unfollowed_branches": { "type": "number", "example": 14, "description": "**How many 'load more' cursors were still queued when the walk stopped** — branches that exist, are reachable, and were not read because `count` or the page budget ran out first.\n\nReddit's cursors are a TREE rather than a chain: the root batch of a 226-comment post handed back **19 of them at once**. Raise `count` to consume more of the queue." }, "truncated_threads": { "type": "number", "example": 0, "description": "**How many subtrees Reddit gave no cursor for at all** — the 'continue this thread' links, which carry only a permalink.\n\n**These cannot be followed by raising `count`.** The only way to read one is to fetch its permalink as a post in its own right, which is a different request than this endpoint makes. Counted so that a tree with unreachable branches is never published as a complete one." }, "pages_fetched": { "type": "number", "example": 3, "description": "**How many batches this call fetched** — the root batch plus one per 'load more' cursor followed." }, "usage_note": { "type": "string", "nullable": true, "example": "Comments come back FLAT in prefix order, each carrying `depth` and `parent_fullname` — Reddit states both, neither is inferred from indentation — so a nested tree can be rebuilt exactly. The 'load more' cursors are a tree rather than a chain: one batch hands back several and this queues all of them, so `end_of_tree` is false while `unfollowed_branches` is non-zero. `truncated_threads` counts subtrees Reddit only links to by permalink and gives no cursor for; those need a separate request against that permalink.", "description": "That the tree is flat and rebuildable, and that the cursors are a tree rather than a chain — restated in every response so a partial read is never mistaken for a whole one." } }, "required": [ "comments", "subreddit", "post_id", "post_fullname", "permalink", "sort", "total_comments", "count", "requested_count", "end_of_tree", "unfollowed_branches", "truncated_threads", "pages_fetched", "usage_note" ] }, "RedditComment": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "comment" ], "example": "comment" }, "id": { "type": "string", "nullable": true, "example": "p44qdpd" }, "fullname": { "type": "string", "nullable": true, "example": "t1_p44qdpd", "description": "Reddit's `t1_` identifier for the comment — the value another row's `parent_fullname` points at, and therefore the key to rebuild the tree on." }, "parent_fullname": { "type": "string", "nullable": true, "example": "t1_p44qab1", "description": "**What this comment replies to** — another comment's `t1_` fullname, or the post's `t3_` fullname at depth 0. **Reddit states it; it is not inferred from indentation.**" }, "post_fullname": { "type": "string", "nullable": true, "example": "t3_1vqcqpz" }, "depth": { "type": "number", "nullable": true, "example": 0, "description": "**How deep in the tree this comment sits, 0 for a top-level one.** Reddit's own attribute, not a count of ancestors we found — which matters, because a partial tree does not contain all of a deep comment's ancestors and a derived depth would be wrong exactly when it was needed." }, "position": { "type": "number", "nullable": true, "example": 3, "description": "The comment's position among its siblings, as Reddit states it." }, "parent_positions": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0 ], "description": "**The path down the tree to this comment**, as Reddit's own positional array. Empty at depth 0." }, "author": { "type": "string", "nullable": true, "example": "example_user", "description": "The commenting account, without `u/`. A deleted account publishes as Reddit's own placeholder rather than as null." }, "author_icon": { "type": "string", "nullable": true, "example": null }, "body": { "type": "string", "nullable": true, "example": "This is the comment text as rendered.", "description": "**The comment text**, decoded out of Reddit's rich-text JSON rather than lifted from the rendered HTML. **Null on a deleted comment**, which is published rather than dropped — see `is_deleted`." }, "score": { "type": "number", "nullable": true, "example": 42 }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000" }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vqcqpz/example/p44qdpd/" }, "award_count": { "type": "number", "nullable": true, "example": 0 }, "is_deleted": { "type": "boolean", "example": false, "description": "**Whether the comment was deleted. A deleted comment is published rather than dropped**, because it keeps its position in the tree and its replies — with no body and no score, which is exactly what Reddit renders. Dropping it would orphan every reply under it." }, "is_collapsed": { "type": "boolean", "example": false, "description": "Whether Reddit renders the comment collapsed by default (downvoted, or flagged by the community's own settings)." } }, "required": [ "kind", "id", "fullname", "parent_fullname", "post_fullname", "depth", "position", "parent_positions", "author", "author_icon", "body", "score", "created_at", "permalink", "award_count", "is_deleted", "is_collapsed" ], "description": "**One comment from a post's tree, published FLAT.**\n\nThe array is in prefix order — the tree read depth-first — and every row carries `depth` and `parent_fullname` **as Reddit states them**, so a nested structure can be rebuilt exactly and a caller who wants to stream does not have to build one. Nothing here is inferred from indentation." }, "RedditSubredditInfoResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "2qh16" }, "fullname": { "type": "string", "nullable": true, "example": "t5_2qh16", "description": "Reddit's `t5_` id for the community. Stable across a rename, which the name is not." }, "name": { "type": "string", "nullable": true, "example": "technology" }, "display_name": { "type": "string", "nullable": true, "example": "/r/Technology", "description": "The community's own display spelling, including its capitalisation. Reddit emits it with stray whitespace; that is trimmed." }, "prefixed_name": { "type": "string", "nullable": true, "example": "r/technology" }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/r/technology/" }, "description": { "type": "string", "nullable": true, "example": "Subreddit dedicated to the news and discussions about…" }, "weekly_active_users": { "type": "number", "nullable": true, "example": 4305645, "description": "**Reddit's own `weekly-active-users` figure. THIS IS NOT A SUBSCRIBER COUNT and it is not renamed into one.** 4,305,645 is not r/technology's member total — the figure runs far above member totals, and where the real subscriber count lives is unknown: no subscriber figure is exposed on any surface reachable without a login.\n\nPublishing this as `subscribers` would answer that question wrongly and invisibly, so it is published under Reddit's own name for it." }, "weekly_contributions": { "type": "number", "nullable": true, "example": 1204 }, "created_at": { "type": "string", "nullable": true, "example": "2008-01-25T05:00:00.000+0000", "description": "**The community's cake day**, from the 'Created' tooltip in the rail." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RedditSubredditRule" }, "description": "**The community's full numbered rule list**, each with its expanded description. Empty for a community that publishes none." }, "usage_note": { "type": "string", "nullable": true, "example": "From the subreddit's right-rail fragment, not from its page: the page shell carries no Open Graph, no Twitter card and no JSON-LD at all. `weekly_active_users` is Reddit's own `weekly-active-users` attribute and is NOT the subscriber count — it runs far above member totals and no subscriber figure is exposed on any surface reachable without a login. `rules` is the full numbered list with each rule's expanded description.", "description": "Where this record comes from, and the one field on it that is routinely misread — restated in every response." } }, "required": [ "id", "fullname", "name", "display_name", "prefixed_name", "url", "description", "weekly_active_users", "weekly_contributions", "created_at", "rules", "usage_note" ] }, "RedditSubredditRule": { "type": "object", "properties": { "number": { "type": "number", "nullable": true, "example": 1, "description": "The rule's position in the community's own numbered list." }, "title": { "type": "string", "nullable": true, "example": "Submissions must be about technology" }, "description": { "type": "string", "nullable": true, "example": "The full expanded text of the rule.", "description": "**The rule's expanded body**, decoded from Reddit's rich-text JSON. Null when the community wrote a title and no body." } }, "required": [ "number", "title", "description" ] }, "RedditPostDetailsResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "1vay198", "description": "**Reddit's base36 post id** — the `1vay198` in a permalink. This is also the value `after` takes, so walking a feed needs nothing constructed and nothing guessed." }, "fullname": { "type": "string", "nullable": true, "example": "t3_1vay198", "description": "Reddit's own `t3_`-prefixed identifier for the post — the form its internals speak. `after` accepts this too." }, "permalink": { "type": "string", "nullable": true, "example": "/r/technology/comments/1vay198/example_post_title/", "description": "The site-relative path to the post's comment page, as Reddit states it. `url` is the same thing absolute." }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/r/technology/comments/1vay198/example/", "description": "**The post's page on reddit.com.** Note what it is NOT: the thing the post links to. That is `content_url`, and on a link post the two point at completely different places." }, "title": { "type": "string", "nullable": true, "example": "Example post title", "description": "The post title, as submitted." }, "subreddit": { "type": "string", "nullable": true, "example": "technology", "description": "The community the post lives in, bare. Worth reading rather than assuming it equals what you asked for — a feed can carry cross-posted rows." }, "subreddit_prefixed": { "type": "string", "nullable": true, "example": "r/technology", "description": "The same name in Reddit's display form." }, "subreddit_id": { "type": "string", "nullable": true, "example": "t5_2qh16", "description": "Reddit's `t5_` id for the community. Stable across a rename, which the name is not." }, "author": { "type": "string", "nullable": true, "example": "example_user", "description": "The posting account's username, without `u/`. Deleted accounts publish as Reddit's own placeholder rather than as null." }, "author_id": { "type": "string", "nullable": true, "example": "t2_abc123", "description": "Reddit's `t2_` id for the account. Survives a rename." }, "author_icon": { "type": "string", "nullable": true, "example": null, "description": "The author's avatar, when the card carried one. Null is common and means the fragment did not include it — not that the account has no avatar." }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-17T09:14:22.000+0000", "description": "**When the post was submitted, in Reddit's own ISO 8601 form** with milliseconds and a `+0000` offset. Republished verbatim rather than reformatted: rewriting a timestamp is a good way to introduce a timezone bug into data that did not have one." }, "score": { "type": "number", "nullable": true, "example": 1284, "description": "**Net score — upvotes minus downvotes, as Reddit displays it.** The breakdown does not exist anywhere in this payload: Reddit publishes the net figure and `upvote_ratio` and nothing else, so ups and downs cannot be recovered from here by anyone, including us." }, "upvote_ratio": { "type": "number", "nullable": true, "example": 0.94, "description": "The share of votes that were upvotes, 0-1. Together with `score` it is the whole of what Reddit says about voting on a post." }, "comment_count": { "type": "number", "nullable": true, "example": 213, "description": "How many comments the post has. **The comments themselves are not available on this API** — see the tag description." }, "award_count": { "type": "number", "nullable": true, "example": 0, "description": "How many awards the post carries. A count only; the award detail is not in a feed fragment." }, "domain": { "type": "string", "nullable": true, "example": "arstechnica.com", "description": "**The host `content_url` points at, and the field that says what kind of post this is at a glance**: an external host for a link post, `i.redd.it` / `v.redd.it` for uploaded media, `self.` for a text post." }, "content_url": { "type": "string", "nullable": true, "example": "https://arstechnica.com/example-article/", "description": "**What the post points at** — the outbound link on a link post, the media URL on an image or video one. Reddit does not separate those two, so neither does this; `domain` is how you tell which you have. For the post's own Reddit page, read `url`." }, "post_type": { "type": "string", "nullable": true, "example": "link", "description": "Reddit's own classification: `link`, `image`, `video`, `gallery`, `text` or `multi_media`. It is the cheapest way to predict whether `text` and `media` will be populated." }, "flair": { "type": "string", "nullable": true, "example": "Society", "description": "The post's flair label, when it has one. Most posts do not, and the flair element is present-but-empty on those — so null here means 'no flair' rather than 'not parsed'." }, "flair_url": { "type": "string", "nullable": true, "example": "/r/technology/?f=flair_name%3A%22Society%22", "description": "Reddit's own link to the community filtered by this flair. Useful as a facet; not a value to key on." }, "thumbnail": { "type": "string", "nullable": true, "example": "https://external-preview.redd.it/example.jpg", "description": "**The card thumbnail — anchored on Reddit's own thumbnail marker, not 'the first image in the card'.** That distinction is measured: on posts whose author has a custom avatar the first image is the avatar, and seven of the 24 posts in the reference capture are exactly that shape. Null on posts with no thumbnail." }, "media": { "$ref": "#/components/schemas/RedditPostMedia" }, "text": { "type": "string", "nullable": true, "example": null, "description": "**The post body, and only self posts have one.** Measured on the same 24-post fragment: null for every post. A link post's body IS empty — the link is the content — so null here is a fact about the post rather than a gap in the parse." }, "nsfw": { "type": "boolean", "nullable": true, "example": null, "description": "**Tri-state, and null does NOT mean 'safe'.** `` carries no NSFW attribute at all; the only signal in the markup rides on the media lightbox element, which appears on **image posts and nothing else** — measured across a 30-post capture, present on the 10 image posts and absent from every video, gallery, link and text post.\n\nSo this is `true`/`false` on an image post and **`null` (unknown) on every other kind**, which is most of a feed. Publishing null as `false` would be asserting something Reddit never said. **Do not use this field to build a safe-content filter** — it cannot support one." }, "spoiler": { "type": "boolean", "example": false, "description": "Whether the post is marked as a spoiler. A real boolean: Reddit sets the attribute only when true, so absence is a measured `false`." }, "locked": { "type": "boolean", "example": false, "description": "Whether commenting is locked. A real boolean, same as `spoiler`." }, "archived": { "type": "boolean", "example": false, "description": "Whether the post is archived (too old to vote or comment on). A real boolean, same as `spoiler`." }, "language": { "type": "string", "nullable": true, "example": "en", "description": "Reddit's own language tag for the post." }, "total_comments": { "type": "number", "nullable": true, "example": 226, "description": "**Reddit's own comment total for the post**, read from the comment tree rather than from the page. Published beside `comment_count`, which comes off the post element — the two are Reddit's own figures from two of its own surfaces and they do not always agree." }, "usage_note": { "type": "string", "nullable": true, "example": "Assembled from two requests: the comment-tree fragment for the canonical permalink and the comment total, then the post page for the record itself. Both are needed — the permalink's SLUG is load-bearing (the same post id without its slug answers 500 with an empty body), and post metadata exists nowhere but the page. `score` is live and drifts between consecutive fetches. `nsfw` is null unless the post is an image post: it is not an attribute on the post element and the only signal in the markup rides on an element image posts alone carry, so null means the page did not say rather than false.", "description": "How this record is assembled, and the two fields on it that are not what they look like — a live `score` and a tri-state `nsfw` — restated in every response." } }, "required": [ "id", "fullname", "permalink", "url", "title", "subreddit", "subreddit_prefixed", "subreddit_id", "author", "author_id", "author_icon", "created_at", "score", "upvote_ratio", "comment_count", "award_count", "domain", "content_url", "post_type", "flair", "flair_url", "thumbnail", "media", "text", "nsfw", "spoiler", "locked", "archived", "language", "total_comments", "usage_note" ], "description": "**One post's full record.** The same shape a feed row has, plus Reddit's own comment total.\n\n**`score` is live and drifts between consecutive fetches** — measured 3975 → 3979 → 3978 on three requests a minute apart. The page is not cached; treat the number as a reading rather than a value." }, "RedditUserProfileResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "abc123" }, "fullname": { "type": "string", "nullable": true, "example": "t2_abc123", "description": "Reddit's `t2_` id for the account, survives a rename. It appears nowhere in the page's visible text and is read out of the page's own telemetry payload, so null here means that payload was missing rather than that the account has no id." }, "name": { "type": "string", "nullable": true, "example": "spez" }, "prefixed_name": { "type": "string", "nullable": true, "example": "u/spez" }, "url": { "type": "string", "nullable": true, "example": "https://www.reddit.com/user/spez/" }, "description": { "type": "string", "nullable": true, "example": null }, "karma": { "type": "number", "nullable": true, "example": 940933, "description": "**Total karma, as Reddit displays it** — parsed from rendered text (`940,933`), because there is no attribute-carrying element for a profile anywhere on this page." }, "post_karma": { "type": "number", "nullable": true, "example": 184453, "description": "**Post karma, from the tooltip beside the total.** Null whenever Reddit renders the profile without that tooltip — which happens, and is not a parse failure. `karma` can be present while this is not." }, "comment_karma": { "type": "number", "nullable": true, "example": 756480, "description": "**Comment karma**, from the same tooltip as `post_karma`." }, "contributions": { "type": "number", "nullable": true, "example": 1204 }, "created_at": { "type": "string", "nullable": true, "example": "2005-06-06T00:00:00.000Z", "description": "**The account's cake day**, from the page's own `` element." }, "icon": { "type": "string", "nullable": true, "example": null }, "usage_note": { "type": "string", "nullable": true, "example": "Scraped from the profile page, which is the only place this data exists — there is no profile fragment endpoint and the page carries no Open Graph or JSON-LD. Karma is read from rendered text, so `karma` is the total Reddit displays and `post_karma` + `comment_karma` come from the tooltip beside it; any of the three may be null if Reddit renders the profile without that block. The page surface is materially less reliable than this site's fragments — pace requests and treat a 503 as retryable.", "description": "Where this record comes from, why any of the three karma figures can be null, and that this surface is the least reliable one on the plane — restated in every response." } }, "required": [ "id", "fullname", "name", "prefixed_name", "url", "description", "karma", "post_karma", "comment_karma", "contributions", "created_at", "icon", "usage_note" ], "description": "**A user's profile — and the only record on this plane read from a rendered page rather than from a data fragment.**\n\nThere is no attribute-carrying element for a profile: karma is text, the cake day is a ``, and identity comes out of the page's telemetry payload. So individual fields can be null on a page that rendered partially, and that is a page-surface fact rather than a statement about the account." }, "TiktokWebProfileResponse": { "type": "object", "nullable": true, "properties": { "user": { "$ref": "#/components/schemas/TiktokWebUser" }, "stats": { "$ref": "#/components/schemas/TiktokWebStats" } }, "required": [ "user", "stats" ] }, "TiktokWebUser": { "type": "object", "properties": { "unique_id": { "type": "string", "nullable": true, "example": "tiktok", "description": "The handle, without the leading @." }, "nickname": { "type": "string", "nullable": true, "example": "TikTok" }, "id": { "type": "string", "nullable": true, "description": "TikTok's internal user id, as a string." }, "sec_uid": { "type": "string", "nullable": true }, "verified": { "type": "boolean", "nullable": true, "example": true }, "signature": { "type": "string", "nullable": true, "description": "The bio text." }, "avatar_large": { "type": "string", "nullable": true } }, "required": [ "unique_id", "nickname", "id", "sec_uid", "verified", "signature", "avatar_large" ] }, "TiktokWebStats": { "type": "object", "properties": { "follower_count": { "type": "number", "nullable": true, "example": 95500000 }, "following_count": { "type": "number", "nullable": true }, "heart_count": { "type": "number", "nullable": true, "example": 463000000, "description": "Total likes received across all of the account's videos." }, "video_count": { "type": "number", "nullable": true, "example": 1499 } }, "required": [ "follower_count", "following_count", "heart_count", "video_count" ] }, "TiktokWebVideoResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "7106594312292453675" }, "desc": { "type": "string", "nullable": true, "description": "The video's caption." }, "create_time": { "type": "number", "nullable": true, "description": "Unix seconds." }, "author": { "$ref": "#/components/schemas/TiktokWebVideoAuthor" }, "stats": { "$ref": "#/components/schemas/TiktokWebVideoStats" }, "music": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "TikTok's own sound-track object, passed through unrenamed." }, "video": { "$ref": "#/components/schemas/TiktokWebVideoMedia" } }, "required": [ "id", "desc", "create_time", "author", "stats", "music", "video" ] }, "TiktokWebVideoAuthor": { "type": "object", "properties": { "unique_id": { "type": "string", "nullable": true, "example": "tiktok" }, "nickname": { "type": "string", "nullable": true } }, "required": [ "unique_id", "nickname" ] }, "TiktokWebVideoStats": { "type": "object", "properties": { "play_count": { "type": "number", "nullable": true, "example": 578100 }, "digg_count": { "type": "number", "nullable": true, "example": 98800 }, "comment_count": { "type": "number", "nullable": true }, "share_count": { "type": "number", "nullable": true } }, "required": [ "play_count", "digg_count", "comment_count", "share_count" ] }, "TiktokWebVideoMedia": { "type": "object", "properties": { "cover": { "type": "string", "nullable": true }, "duration": { "type": "number", "nullable": true, "description": "Seconds." } }, "required": [ "cover", "duration" ] }, "TiktokWebHashtagResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "229207", "description": "TikTok's numeric id for the hashtag. This is what `/tiktok/hashtag_videos` takes as `challenge_id`; nothing else produces it." }, "title": { "type": "string", "nullable": true, "example": "fyp", "description": "The tag itself, without the leading `#`." }, "description": { "type": "string", "nullable": true, "description": "TikTok's own blurb for the tag; usually empty." }, "is_commerce": { "type": "boolean", "nullable": true }, "cover": { "type": "string", "nullable": true, "description": "The tag's cover image, when it has one." }, "stats": { "$ref": "#/components/schemas/TiktokWebHashtagStats" }, "stats_v2": { "$ref": "#/components/schemas/TiktokWebHashtagStatsV2" } }, "required": [ "id", "title", "description", "is_commerce", "cover", "stats", "stats_v2" ] }, "TiktokWebHashtagStats": { "type": "object", "properties": { "video_count": { "type": "number", "nullable": true, "description": "TikTok's own `stats.videoCount`. Measured at 0 on a hashtag with billions of videos, so read `stats_v2` beside it before trusting it." }, "view_count": { "type": "number", "nullable": true, "example": 127180300000000 } }, "required": [ "video_count", "view_count" ] }, "TiktokWebHashtagStatsV2": { "type": "object", "properties": { "video_count": { "type": "string", "nullable": true, "example": "9261224100", "description": "The same count TikTok sends as a string, at full precision. Strings because these exceed a safe JSON integer." }, "view_count": { "type": "string", "nullable": true, "example": "127180314102636" } }, "required": [ "video_count", "view_count" ] }, "TiktokWebHashtagVideosResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/TiktokWebHashtagVideo" } }, "count": { "type": "number", "description": "`entries.length` — the size of the page you were handed, and never a count of the hashtag's catalogue. Nothing on this surface states one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "TikTok's own cursor for the next page, passed through verbatim. Send it back as `cursor`. It is a token, not a page number — nothing can be derived from its value, and each page has to be fetched in turn." }, "has_more": { "type": "boolean", "description": "TikTok's own flag. On the sibling `music_videos` surface it is measured to stay `true` forever past the end of a list, and how it behaves at the end of a hashtag walk has never been measured — so stop on an empty page (`count == 0`), not on this field." } }, "required": [ "entries", "count", "next_cursor", "has_more" ] }, "TiktokWebHashtagVideo": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "7497430262331182382" }, "desc": { "type": "string", "nullable": true, "description": "The video's caption." }, "create_time": { "type": "number", "nullable": true, "description": "Unix seconds." }, "author": { "$ref": "#/components/schemas/TiktokWebListAuthor" }, "stats": { "$ref": "#/components/schemas/TiktokWebVideoStats" }, "stats_v2": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "TikTok's own string-valued twin of `stats`, passed through unrenamed. It is the exact one where `stats` has been rounded — measured on the same item, `stats.collectCount` 192600 against `statsV2.collectCount` \"192559\" — and it carries fields `stats` has none of, such as saves and reposts." }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "Every tag on the video, as plain titles. Empty when it carries none." }, "video": { "$ref": "#/components/schemas/TiktokWebListVideoMedia" } }, "required": [ "id", "desc", "create_time", "author", "stats", "stats_v2", "hashtags", "video" ] }, "TiktokWebListAuthor": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "TikTok's internal user id, as a string." }, "unique_id": { "type": "string", "nullable": true, "example": "tiktok" }, "nickname": { "type": "string", "nullable": true }, "sec_uid": { "type": "string", "nullable": true }, "verified": { "type": "boolean", "nullable": true } }, "required": [ "id", "unique_id", "nickname", "sec_uid", "verified" ] }, "TiktokWebListVideoMedia": { "type": "object", "properties": { "cover": { "type": "string", "nullable": true }, "duration": { "type": "number", "nullable": true, "description": "Seconds." }, "ratio": { "type": "string", "nullable": true, "example": "540p", "description": "TikTok's own quality label for the item." } }, "required": [ "cover", "duration", "ratio" ] }, "TiktokWebMusicVideosResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/TiktokWebMusicVideo" } }, "count": { "type": "number", "description": "`entries.length` — the size of the page you were handed. There is no total on this surface, so it is never a count of how many videos use the sound. **`count == 0` is the end of the walk.**" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "TikTok's own cursor for the next page, passed through verbatim. Send it back as `cursor`. It is a token, not a page number — nothing can be derived from its value, and each page has to be fetched in turn." }, "has_more": { "type": "boolean", "description": "TikTok's own flag, and it LIES here: a sound with 6 videos answered `true` on its first page and on three consecutive empty pages after it. It is forwarded because TikTok sends it — do not loop on it." } }, "required": [ "entries", "count", "next_cursor", "has_more" ] }, "TiktokWebMusicVideo": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "7497430262331182382" }, "desc": { "type": "string", "nullable": true, "description": "The video's caption." }, "create_time": { "type": "number", "nullable": true, "description": "Unix seconds." }, "author": { "$ref": "#/components/schemas/TiktokWebListAuthor" }, "stats": { "$ref": "#/components/schemas/TiktokWebVideoStats" }, "stats_v2": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "TikTok's own string-valued twin of `stats`, passed through unrenamed. It is the exact one where `stats` has been rounded — measured on the same item, `stats.collectCount` 192600 against `statsV2.collectCount` \"192559\" — and it carries fields `stats` has none of, such as saves and reposts." }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "Every tag on the video, as plain titles. Empty when it carries none." }, "video": { "$ref": "#/components/schemas/TiktokWebListVideoMedia" }, "music": { "$ref": "#/components/schemas/TiktokWebListMusic" } }, "required": [ "id", "desc", "create_time", "author", "stats", "stats_v2", "hashtags", "video", "music" ] }, "TiktokWebListMusic": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "6704931455228725250", "description": "Pass this to `/tiktok/music_videos` as `music_id`." }, "title": { "type": "string", "nullable": true, "example": "I Want to Be Your Man" }, "author_name": { "type": "string", "nullable": true, "example": "Roger" } }, "required": [ "id", "title", "author_name" ] }, "Transcript": { "type": "object", "nullable": true, "properties": { "language": { "type": "string", "nullable": true, "description": "Detected ISO 639-1 code, or null when there is no speech." }, "language_probability": { "type": "number", "nullable": true }, "duration": { "type": "number", "description": "Media duration in seconds." }, "has_audio": { "type": "boolean", "description": "False for a silent creative, which returns an empty transcript rather than an error." }, "text": { "type": "string" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" }, "no_speech_prob": { "type": "number", "description": "Model probability that this segment contains no speech. A high value with low `avg_logprob` indicates unreliable text." }, "avg_logprob": { "type": "number" } }, "required": [ "id", "start", "end", "text", "no_speech_prob", "avg_logprob" ] } }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" }, "probability": { "type": "number" } }, "required": [ "word", "start", "end", "probability" ] }, "description": "Word-level timestamps in seconds. This is what makes a first-3-seconds hook extractable." }, "model": { "type": "string" }, "media": { "$ref": "#/components/schemas/MediaFacts" }, "timing": { "$ref": "#/components/schemas/MediaTiming" }, "limits": { "$ref": "#/components/schemas/MediaLimits" } }, "required": [ "language", "language_probability", "duration", "has_audio", "text", "segments", "words", "model", "media", "timing", "limits" ] }, "MediaFacts": { "type": "object", "properties": { "bytes": { "type": "number" }, "content_type": { "type": "string" }, "container": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "has_audio": { "type": "boolean" }, "has_video": { "type": "boolean" } }, "required": [ "bytes", "content_type", "container", "width", "height", "has_audio", "has_video" ], "description": "What the file turned out to be. The source URL is deliberately not echoed back — a signed CDN link is a credential." }, "MediaTiming": { "type": "object", "properties": { "total_seconds": { "type": "number" }, "compute_seconds": { "type": "number" } }, "required": [ "total_seconds", "compute_seconds" ], "description": "`compute_seconds` is the analysis alone; `total_seconds` includes the download." }, "MediaLimits": { "type": "object", "properties": { "max_duration_s": { "type": "number" }, "max_bytes": { "type": "number" } }, "required": [ "max_duration_s", "max_bytes" ], "description": "Maximum duration and file size applied to this request, for filtering future media before submission." }, "TranscribeRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 4096, "format": "uri", "example": "https://video.example.com/creative.mp4", "description": "Public http(s) URL of one video or audio file. Ad-library creative URLs expire — fetch the ad and analyse it in the same run." }, "proxy_tier": { "type": "string", "enum": [ "none", "datacenter", "residential" ], "default": "none", "example": "none", "description": "Connection tier used to download the media file. `none` uses a direct connection." }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "example": "en", "description": "Force a language instead of detecting it. Detection costs nothing extra, so set this only when you already know." } }, "required": [ "url" ] }, "SceneList": { "type": "object", "nullable": true, "properties": { "scene_count": { "type": "number" }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "start": { "type": "number" }, "end": { "type": "number" }, "duration": { "type": "number" }, "motion_score": { "type": "number", "nullable": true, "description": "Mean frame-to-frame change inside the scene, on the detector's own 0-255 scale." }, "motion": { "type": "string", "enum": [ "static", "moderate", "dynamic", "unknown" ], "description": "How much the picture moves inside the shot, bucketed from `motion_score`. Not camera framing — close-up/medium/wide needs a vision model and is not inferable from a cut list." } }, "required": [ "index", "start", "end", "duration", "motion_score", "motion" ] } }, "fps": { "type": "number" }, "duration": { "type": "number" }, "threshold": { "type": "number" }, "media": { "$ref": "#/components/schemas/MediaFacts" }, "timing": { "$ref": "#/components/schemas/MediaTiming" }, "limits": { "$ref": "#/components/schemas/MediaLimits" } }, "required": [ "scene_count", "scenes", "fps", "duration", "threshold", "media", "timing", "limits" ] }, "ScenesRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 4096, "format": "uri", "example": "https://video.example.com/creative.mp4", "description": "Public http(s) URL of one video or audio file. Ad-library creative URLs expire — fetch the ad and analyse it in the same run." }, "proxy_tier": { "type": "string", "enum": [ "none", "datacenter", "residential" ], "default": "none", "example": "none", "description": "Connection tier used to download the media file. `none` uses a direct connection." }, "threshold": { "type": "number", "minimum": 5, "maximum": 100, "default": 27, "example": 27, "description": "Cut sensitivity. Lower finds more cuts; 27 is the detector's default and suits fast-cut ad creative." } }, "required": [ "url" ] }, "Teardown": { "type": "object", "nullable": true, "properties": { "hook": { "type": "object", "properties": { "text": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "question", "problem", "claim", "social_proof", "demonstration", "offer", "other", "none" ] }, "source": { "type": "string", "enum": [ "spoken", "ad_copy", "none" ] } }, "required": [ "text", "type", "source" ], "description": "What the first 3 seconds do. `source` says whether it came from speech or from the published copy; `none` means the creative opens silent and the ad published no copy." }, "script_structure": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "hook", "problem", "solution", "proof", "offer", "cta", "other" ] }, "start": { "type": "number", "nullable": true }, "end": { "type": "number", "nullable": true }, "summary": { "type": "string" } }, "required": [ "stage", "start", "end", "summary" ] } }, "offer": { "type": "object", "properties": { "present": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "discount": { "type": "string", "nullable": true }, "urgency": { "type": "string", "nullable": true } }, "required": [ "present", "description", "discount", "urgency" ] }, "cta": { "type": "object", "properties": { "present": { "type": "boolean" }, "text": { "type": "string", "nullable": true }, "action": { "type": "string", "enum": [ "shop", "sign_up", "download", "learn_more", "book", "contact", "other", "none" ] } }, "required": [ "present", "text", "action" ] }, "claims": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "string", "enum": [ "spoken", "ad_copy" ] }, "type": { "type": "string", "enum": [ "performance", "price", "guarantee", "comparison", "testimonial", "other" ] } }, "required": [ "text", "source", "type" ] }, "description": "Claims supported by the supplied transcript or copy. `source` identifies the supporting input; text visible only on screen is excluded." }, "language": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "How much of the teardown the evidence actually supports. `low` on a creative with no reliable speech and no copy." }, "input": { "$ref": "#/components/schemas/TeardownInputFacts" } }, "required": [ "hook", "script_structure", "offer", "cta", "claims", "language", "confidence", "input" ] }, "TeardownInputFacts": { "type": "object", "properties": { "transcript_chars": { "type": "number" }, "segments_used": { "type": "number" }, "segments_dropped": { "type": "number", "description": "Segments excluded because they were marked as non-speech with low confidence." }, "scenes": { "type": "number" }, "hook_window_seconds": { "type": "number" } }, "required": [ "transcript_chars", "segments_used", "segments_dropped", "scenes", "hook_window_seconds" ], "description": "What the analysis was actually run on, so a thin teardown is explainable without re-running it." }, "TeardownRequest": { "type": "object", "properties": { "transcript": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 20000, "description": "The spoken words. An empty string is valid and produces a copy-only teardown." }, "language": { "type": "string", "nullable": true, "maxLength": 8 }, "segments": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 }, "text": { "type": "string", "maxLength": 2000 }, "no_speech_prob": { "type": "number", "minimum": 0, "maximum": 1, "description": "Value from the transcript response. Segments marked as non-speech with low confidence are excluded from analysis." }, "avg_logprob": { "type": "number" } }, "required": [ "start", "end", "text" ] }, "maxItems": 400, "description": "Timed segments from /v1/media/transcribe. Supplying them is what enables low-confidence filtering." }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string", "maxLength": 200 }, "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 } }, "required": [ "word", "start", "end" ] }, "maxItems": 4000, "description": "Word timings from /v1/media/transcribe. Supplying them is what makes the first-3-second hook exact rather than approximate." } }, "required": [ "text" ] }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 }, "motion": { "type": "string", "enum": [ "static", "moderate", "dynamic", "unknown" ] } }, "required": [ "start", "end" ] }, "maxItems": 200, "description": "Cut list from /v1/media/scenes." }, "ad": { "type": "object", "properties": { "advertiser": { "type": "string", "maxLength": 200 }, "platform": { "type": "string", "enum": [ "meta", "tiktok", "google", "linkedin", "other" ] }, "headline": { "type": "string", "maxLength": 1000 }, "body": { "type": "string", "maxLength": 5000 }, "cta_text": { "type": "string", "maxLength": 200 }, "landing_url": { "type": "string", "maxLength": 2000 } }, "default": {}, "description": "Whatever the ad library published. Everything is optional — an ad with no copy is analysed from its transcript alone." } }, "required": [ "transcript" ] }, "RedNoteFeedResponse": { "type": "object", "nullable": true, "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/RedNoteFeedCard" }, "description": "A random sample of the public explore feed. Repeated calls return different notes — this is not a page, and there is no cursor." }, "count": { "type": "number", "description": "`cards.length`." } }, "required": [ "cards", "count" ] }, "RedNoteFeedCard": { "type": "object", "properties": { "id": { "type": "string", "example": "64a1b2c3d4e5f60718293a4b", "description": "Pass this to `/v1/rednote/note` as `note_id`." }, "xsec_token": { "type": "string", "nullable": true, "description": "Pass with this card’s `id` to `/v1/rednote/note`." }, "type": { "type": "string", "nullable": true, "example": "video" }, "title": { "type": "string", "nullable": true }, "cover_url": { "type": "string", "nullable": true }, "video_duration_s": { "type": "number", "nullable": true }, "user": { "$ref": "#/components/schemas/RedNoteFeedUser" }, "liked_count": { "$ref": "#/components/schemas/RedNoteCount" } }, "required": [ "id", "xsec_token", "type", "title", "cover_url", "video_duration_s", "user", "liked_count" ] }, "RedNoteFeedUser": { "type": "object", "properties": { "nickname": { "type": "string", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "xsec_token": { "type": "string", "nullable": true } }, "required": [ "nickname", "user_id", "xsec_token" ] }, "RedNoteCount": { "type": "object", "nullable": true, "properties": { "raw": { "type": "string", "nullable": true, "example": "10万+" }, "value": { "type": "number", "nullable": true, "example": 100000 }, "approx": { "type": "boolean", "example": true, "description": "`true` when `raw` was a floor (\"N万+\"), not an exact count." } }, "required": [ "raw", "value", "approx" ] }, "RedNoteNoteResponse": { "type": "object", "nullable": true, "properties": { "note_id": { "type": "string", "example": "64a1b2c3d4e5f60718293a4b" }, "type": { "type": "string", "nullable": true, "example": "normal" }, "title": { "type": "string", "nullable": true }, "desc": { "type": "string", "nullable": true }, "time": { "type": "number", "nullable": true, "description": "Unix milliseconds." }, "last_update_time": { "type": "number", "nullable": true, "description": "Unix milliseconds." }, "user": { "$ref": "#/components/schemas/RedNoteNoteUser" }, "liked_count": { "$ref": "#/components/schemas/RedNoteCount" }, "collected_count": { "$ref": "#/components/schemas/RedNoteCount" }, "comment_count": { "$ref": "#/components/schemas/RedNoteCount" }, "share_count": { "$ref": "#/components/schemas/RedNoteCount" }, "image_list": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } }, "description": "RedNote's own image objects, passed through unrenamed." }, "video": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "RedNote's own video object when the note carries one." }, "tag_list": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } }, "description": "RedNote's own tag objects, passed through unrenamed." } }, "required": [ "note_id", "type", "title", "desc", "time", "last_update_time", "user", "liked_count", "collected_count", "comment_count", "share_count", "image_list", "video", "tag_list" ] }, "RedNoteNoteUser": { "type": "object", "properties": { "nickname": { "type": "string", "nullable": true }, "user_id": { "type": "string", "nullable": true }, "xsec_token": { "type": "string", "nullable": true } }, "required": [ "nickname", "user_id", "xsec_token" ] }, "RedNoteV2ProfileResponse": { "type": "object", "nullable": true, "properties": { "user_id": { "type": "string", "example": "5f1a2b3c4d5e6f708192a3b4" }, "nickname": { "type": "string", "example": "Ada" }, "red_id": { "type": "string", "nullable": true, "example": "5696227057", "description": "The short display handle. A DIFFERENT id space from `user_id` — it is not interchangeable with it." }, "gender": { "type": "number", "nullable": true, "description": "RedNote's own integer code, passed through unread: the mapping to a label has never been confirmed, so guessing one here would be invention." }, "ip_location": { "type": "string", "nullable": true, "example": "上海", "description": "The region RedNote itself displays on the profile." }, "desc": { "type": "string", "nullable": true, "description": "The bio text." }, "avatar_url": { "type": "string", "nullable": true }, "follower_count": { "$ref": "#/components/schemas/RedNoteV2Count" }, "following_count": { "$ref": "#/components/schemas/RedNoteV2Count" }, "likes_collected_count": { "allOf": [ { "$ref": "#/components/schemas/RedNoteV2Count" }, { "description": "Likes and saves combined, as RedNote itself reports it." } ] }, "tabs": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedNoteV2ProfileTabCard" } }, "description": "The profile's note tabs, in RedNote's own order — the first is the user's notes. **The others are usually empty, and that is the account's own privacy setting, not a gap here**: saved collections are private by default for anyone but their owner." } }, "required": [ "user_id", "nickname", "red_id", "gender", "ip_location", "desc", "avatar_url", "follower_count", "following_count", "likes_collected_count", "tabs" ] }, "RedNoteV2Count": { "type": "object", "nullable": true, "properties": { "raw": { "type": "string", "nullable": true, "example": "10万+" }, "value": { "type": "number", "nullable": true, "example": 100000 }, "approx": { "type": "boolean", "example": true, "description": "Whether the value is a lower bound rather than an exact count." } }, "required": [ "raw", "value", "approx" ] }, "RedNoteV2ProfileTabCard": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Usually `null`: RedNote does not put note ids on profile-tab cards the way it does on feed cards. This tab is for titles, covers and counts — use `/v1/rednote/feed` when you need an id to look a note up with." }, "xsec_token": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "cover_url": { "type": "string", "nullable": true }, "liked_count": { "$ref": "#/components/schemas/RedNoteV2Count" } }, "required": [ "id", "xsec_token", "title", "cover_url", "liked_count" ] }, "RedNoteV2ProductResponse": { "type": "object", "nullable": true, "properties": { "item_id": { "type": "string", "example": "64a1b2c3d4e5f60718293a4b" }, "name": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true, "example": 78.88, "description": "Displayed product price in Chinese yuan (CNY)." }, "sold_text": { "type": "string", "nullable": true, "example": "已售73", "description": "RedNote's own sales-count line for the item, kept as written — it is free text, not a number." }, "seller": { "$ref": "#/components/schemas/RedNoteV2Seller" }, "template": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional product data, such as images, variants, FAQs, and coupons. Fields vary by product." } }, "required": [ "item_id", "name", "price", "sold_text", "seller", "template" ] }, "RedNoteV2Seller": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "nullable": true }, "link": { "type": "string", "nullable": true }, "fans_text": { "type": "string", "nullable": true, "example": "粉丝数 4129", "description": "The shop's own follower line, kept as written rather than parsed into a number." }, "sales_text": { "type": "string", "nullable": true, "example": "已售2316", "description": "The shop's own sales line, kept as written." } }, "required": [ "name", "id", "logo_url", "link", "fans_text", "sales_text" ] }, "WeiboV2PostDetailResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "5327962377289859" }, "text": { "type": "string", "nullable": true, "description": "The post body, with Weibo's own inline HTML kept as sent." }, "text_length": { "type": "number", "nullable": true }, "created_at": { "type": "string", "nullable": true, "description": "Weibo's own timestamp string, passed through unparsed." }, "source": { "type": "string", "nullable": true, "description": "The client the post was published from." }, "pic_ids": { "type": "array", "items": { "type": "string" }, "description": "Image ids attached to the post; empty when there are none." }, "reposts_count": { "type": "number", "nullable": true }, "comments_count": { "type": "number", "nullable": true }, "attitudes_count": { "type": "number", "nullable": true }, "is_video": { "type": "boolean", "description": "`true` when the post carries a playable video stream. This is what a video lookup answers with — there is no separate video endpoint." }, "video_stream_url": { "type": "string", "nullable": true }, "video_stream_url_hd": { "type": "string", "nullable": true }, "video_duration_seconds": { "type": "number", "nullable": true, "description": "Seconds. Weibo rounds this differently on its own two routes, so treat it as approximate." }, "user": { "$ref": "#/components/schemas/WeiboV2User" } }, "required": [ "id", "text", "text_length", "created_at", "source", "pic_ids", "reposts_count", "comments_count", "attitudes_count", "is_video", "video_stream_url", "video_stream_url_hd", "video_duration_seconds", "user" ] }, "WeiboV2User": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "1699432410", "description": "Weibo's own user id, as a string." }, "screen_name": { "type": "string", "nullable": true, "example": "新华社" }, "profile_image_url": { "type": "string", "nullable": true }, "avatar_hd": { "type": "string", "nullable": true }, "verified": { "type": "boolean", "nullable": true }, "verified_reason": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "followers_count": { "type": "number", "nullable": true } }, "required": [ "id", "screen_name", "profile_image_url", "avatar_hd", "verified", "verified_reason", "location", "followers_count" ] }, "WeiboV2HotSearchResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboV2HotSearchEntry" }, "description": "The board as it stands right now. A snapshot, not a paged list: there is no cursor and no second page." }, "count": { "type": "number", "description": "`entries.length`." } }, "required": [ "entries", "count" ] }, "WeiboV2HotSearchEntry": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ranked", "pinned", "ad" ], "description": "`ranked` is an ordinary board entry, `pinned` the single fixed top entry, `ad` a paid placement. Paid and pinned entries carry no rank or heat — they are on the board for a reason other than volume." }, "rank": { "type": "number", "nullable": true, "example": 1 }, "word": { "type": "string", "example": "奥运会开幕式" }, "heat": { "type": "number", "nullable": true, "description": "Weibo's own heat score for the entry." }, "label": { "type": "string", "nullable": true, "example": "新", "description": "Weibo's own badge on the entry, when it carries one." } }, "required": [ "kind", "rank", "word", "heat", "label" ] }, "WeiboV2CommentsResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboV2Comment" } }, "count": { "type": "number", "description": "`entries.length`." }, "total_number": { "type": "number", "nullable": true, "description": "Weibo's own count of comments on the post." }, "next_cursor_hint": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "Weibo's own `max_id`, passed through UNVERIFIED: replaying it has never been measured to walk a second page here, so it is a hint, not a cursor. This endpoint returns the first page only." } }, "required": [ "entries", "count", "total_number", "next_cursor_hint" ] }, "WeiboV2Comment": { "type": "object", "properties": { "id": { "type": "string", "description": "The comment id, as a string." }, "text": { "type": "string", "nullable": true, "description": "The comment body with Weibo's inline HTML." }, "text_raw": { "type": "string", "nullable": true, "description": "The same body, plain." }, "created_at": { "type": "string", "nullable": true }, "like_count": { "type": "number", "nullable": true }, "floor_number": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "user": { "$ref": "#/components/schemas/WeiboV2User" } }, "required": [ "id", "text", "text_raw", "created_at", "like_count", "floor_number", "source", "user" ] }, "WeiboV2LikesResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboV2Like" } }, "count": { "type": "number", "description": "`entries.length`." }, "total_number": { "type": "number", "nullable": true, "description": "Weibo's own count of likes on the post." } }, "required": [ "entries", "count", "total_number" ] }, "WeiboV2Like": { "type": "object", "properties": { "attitude_type": { "type": "number", "nullable": true, "description": "Weibo's own attitude code, passed through unlabelled — only one value has ever been observed, so a mapping to a named reaction would be invented rather than measured." }, "user": { "$ref": "#/components/schemas/WeiboV2User" } }, "required": [ "attitude_type", "user" ] }, "WeiboV2ProfileResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "1699432410" }, "screen_name": { "type": "string", "example": "新华社" }, "description": { "type": "string", "nullable": true, "description": "The bio text." }, "location": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true, "description": "Weibo's own code, passed through unread." }, "verified": { "type": "boolean", "nullable": true }, "verified_type": { "type": "number", "nullable": true }, "verified_reason": { "type": "string", "nullable": true }, "followers_count": { "type": "number", "nullable": true }, "friends_count": { "type": "number", "nullable": true, "description": "Accounts this profile follows." }, "statuses_count": { "type": "number", "nullable": true }, "profile_image_url": { "type": "string", "nullable": true }, "avatar_hd": { "type": "string", "nullable": true }, "status_total_counter": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Weibo's own pre-formatted totals (e.g. \"9.46亿\"), kept verbatim rather than parsed into numbers." } }, "required": [ "id", "screen_name", "description", "location", "gender", "verified", "verified_type", "verified_reason", "followers_count", "friends_count", "statuses_count", "profile_image_url", "avatar_hd", "status_total_counter" ] }, "WeiboV2SearchTopicsResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboV2Topic" } }, "count": { "type": "number", "description": "`entries.length`." } }, "required": [ "entries", "count" ] }, "WeiboV2Topic": { "type": "object", "properties": { "title": { "type": "string", "example": "#奥运会#" }, "description": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "page_id": { "type": "string", "nullable": true, "description": "Weibo's own id for the topic page." } }, "required": [ "title", "description", "image", "page_id" ] }, "WeiboV2SearchUsersResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboV2SearchUser" } }, "count": { "type": "number", "description": "`entries.length`." } }, "required": [ "entries", "count" ] }, "WeiboV2SearchUser": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "screen_name": { "type": "string", "example": "新华社" }, "description": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "profile_image_url": { "type": "string", "nullable": true }, "verified": { "type": "boolean", "nullable": true }, "followers_count": { "type": "number", "nullable": true } }, "required": [ "id", "screen_name", "description", "location", "profile_image_url", "verified", "followers_count" ] }, "WeiboV2VideosUserResponse": { "type": "object", "nullable": true, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboV2UserVideo" } }, "count": { "type": "number", "description": "`entries.length`." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "Weibo's own cursor for the next page, passed through verbatim. Send it back as `cursor`; it is an opaque token, not a page number, and nothing else can be derived from it." } }, "required": [ "entries", "count", "next_cursor" ] }, "WeiboV2UserVideo": { "type": "object", "properties": { "mid": { "type": "string", "nullable": true, "description": "Pass this to `/weibo-v2/posts/detail` as `mid`." }, "mblogid": { "type": "string", "description": "Weibo's short id for the post, as it appears in its URL." }, "text_raw": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "comments_count": { "type": "number", "nullable": true }, "reposts_count": { "type": "number", "nullable": true }, "attitudes_count": { "type": "number", "nullable": true }, "video_stream_url": { "type": "string", "nullable": true }, "video_duration_seconds": { "type": "number", "nullable": true } }, "required": [ "mid", "mblogid", "text_raw", "created_at", "comments_count", "reposts_count", "attitudes_count", "video_stream_url", "video_duration_seconds" ] }, "OzonSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string", "nullable": true, "example": "iphone" }, "category": { "type": "string", "nullable": true, "example": "https://www.ozon.ru/category/smartfony-15502/apple-26303000/", "description": "The category Ozon resolved the query to, as an absolute URL." }, "category_path": { "type": "string", "nullable": true, "example": "/category/smartfony-15502/apple-26303000/", "description": "The same category as a path — pass this to /ozon/products/category." }, "pages_fetched": { "type": "number", "description": "Number of Ozon listing pages retrieved for this response." }, "next_page": { "type": "number", "nullable": true, "example": 4, "description": "Pass this as `page` to /products/category, together with `category_path`, to continue where this response stopped. Null means the listing is finished — so this, not the product count, is how to tell whether another call is worth making." }, "count": { "type": "number", "example": 24 }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/OzonProduct" } } }, "required": [ "query", "category", "category_path", "pages_fetched", "next_page", "count", "products" ] }, "OzonProduct": { "type": "object", "properties": { "sku": { "type": "number", "nullable": true, "example": 3755501937, "description": "Ozon's own numeric product id." }, "title": { "type": "string", "nullable": true, "example": "Apple Смартфон iPhone 17 Pro Max" }, "url": { "type": "string", "nullable": true, "example": "https://www.ozon.ru/product/apple-smartfon-iphone-3755501937/", "description": "Absolute product URL, with Ozon's per-response tracking token removed." }, "image": { "type": "string", "nullable": true, "example": "https://ir.ozone.ru/s3/multimedia-1-4/8542532020.jpg" }, "price": { "$ref": "#/components/schemas/OzonMoney" }, "original_price": { "allOf": [ { "$ref": "#/components/schemas/OzonMoney" }, { "description": "The pre-discount price. Null fields when the product is not discounted." } ] }, "discount_percent": { "type": "number", "nullable": true, "example": -82, "description": "Negative for a reduction, matching how Ozon signs it." }, "rating": { "type": "number", "nullable": true, "example": 4.7, "description": "0-5. Null when the product has no rating yet." }, "reviews_count": { "type": "number", "nullable": true, "example": 128 }, "is_adult": { "type": "boolean", "example": false } }, "required": [ "sku", "title", "url", "image", "price", "original_price", "discount_percent", "rating", "reviews_count", "is_adult" ] }, "OzonMoney": { "type": "object", "properties": { "amount": { "type": "number", "nullable": true, "example": 194632, "description": "The numeric value. Null when Ozon's display string could not be parsed — `raw` still carries what was served, so nothing is lost." }, "currency": { "type": "string", "nullable": true, "example": "RUB", "description": "ISO code inferred from the currency glyph." }, "raw": { "type": "string", "nullable": true, "example": "194 632 ₽", "description": "Exactly as Ozon rendered it. Note the thousands separator is a no-break space, not an ordinary one." } }, "required": [ "amount", "currency", "raw" ] }, "OzonCategoryResponse": { "type": "object", "nullable": true, "properties": { "category": { "type": "string", "nullable": true }, "category_path": { "type": "string", "nullable": true }, "pages_fetched": { "type": "number" }, "start_page": { "type": "number", "example": 1, "description": "The page this response started from." }, "next_page": { "type": "number", "nullable": true, "example": 7, "description": "Pass back as `page` to continue. Null when the listing is finished." }, "count": { "type": "number" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/OzonProduct" } } }, "required": [ "category", "category_path", "pages_fetched", "start_page", "next_page", "count", "products" ] }, "OzonProductDetail": { "type": "object", "nullable": true, "properties": { "sku": { "type": "number", "nullable": true, "example": 3755501937 }, "title": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "brand": { "type": "string", "nullable": true, "example": "Apple" }, "description": { "type": "string", "nullable": true, "description": "The seller's full product copy. Absent on some listings." }, "price": { "allOf": [ { "$ref": "#/components/schemas/OzonMoney" }, { "description": "The standard price, paid without an Ozon card." } ] }, "card_price": { "allOf": [ { "$ref": "#/components/schemas/OzonMoney" }, { "description": "The Ozon-card price. This is the figure the search and category listings show, so it is the one to compare a listing row against." } ] }, "original_price": { "allOf": [ { "$ref": "#/components/schemas/OzonMoney" }, { "description": "The pre-discount price. Null fields when not discounted." } ] }, "rating": { "type": "number", "nullable": true, "example": 4.7 }, "reviews_count": { "type": "number", "nullable": true, "example": 15 }, "in_stock": { "type": "boolean", "nullable": true, "description": "Null when the page states no availability at all." }, "images": { "type": "array", "items": { "type": "string" }, "description": "Every gallery image, in the order Ozon shows them." }, "characteristics": { "type": "array", "items": { "$ref": "#/components/schemas/OzonCharacteristic" } }, "breadcrumbs": { "type": "array", "items": { "$ref": "#/components/schemas/OzonBreadcrumb" } }, "category_path": { "type": "string", "nullable": true, "example": "/category/smartfony-15502/", "description": "The deepest category in the breadcrumb trail, ready to pass to /products/category." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/OzonVariant" } }, "seller_name": { "type": "string", "nullable": true, "example": "Мирный Атом" }, "seller_url": { "type": "string", "nullable": true }, "seller_id": { "type": "string", "nullable": true, "example": "4289687" } }, "required": [ "sku", "title", "url", "brand", "description", "price", "card_price", "original_price", "rating", "reviews_count", "in_stock", "images", "characteristics", "breadcrumbs", "category_path", "variants", "seller_name", "seller_url", "seller_id" ] }, "OzonCharacteristic": { "type": "object", "properties": { "name": { "type": "string", "example": "Диагональ экрана, дюймы" }, "value": { "type": "string", "example": "6.9" } }, "required": [ "name", "value" ] }, "OzonBreadcrumb": { "type": "object", "properties": { "name": { "type": "string", "example": "Смартфоны" }, "url": { "type": "string", "nullable": true, "example": "https://www.ozon.ru/category/smartfony-15502/" } }, "required": [ "name", "url" ] }, "OzonVariant": { "type": "object", "properties": { "aspect": { "type": "string", "example": "Встроенная память", "description": "What this variant varies on — colour, capacity, or condition. Without it a flat list of sibling SKUs loses which axis each is on." }, "sku": { "type": "number", "nullable": true, "example": 3755502198 }, "label": { "type": "string", "nullable": true, "example": "2 ТБ" }, "price": { "$ref": "#/components/schemas/OzonMoney" }, "url": { "type": "string", "nullable": true }, "in_stock": { "type": "boolean" }, "is_current": { "type": "boolean", "description": "True for the variant this product page is showing." } }, "required": [ "aspect", "sku", "label", "price", "url", "in_stock", "is_current" ] }, "WellfoundJobSearchResponse": { "type": "object", "nullable": true, "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/WellfoundJob" }, "description": "Matching job rows. Empty when the query matched nothing." }, "startups": { "type": "array", "items": { "$ref": "#/components/schemas/WellfoundStartup" }, "description": "Every distinct company seen across the pages walked, deduplicated. The same objects are also attached to their jobs, so this is a convenience index rather than extra data." }, "count": { "type": "integer", "minimum": 0, "example": 40, "description": "How many job rows are returned." }, "has_more": { "type": "boolean", "example": true, "description": "Whether more rows were available beyond the ones returned. False means the walk stopped because the source ran out — check `ended_at_source_limit` to tell that apart from simply having satisfied `count`." }, "ended_at_source_limit": { "type": "boolean", "example": false, "description": "True when Wellfound's own result set ran out before `count` was met. It is not an error and not a block: it means the site has no more rows for this query, so retrying or paging further returns nothing new. Wellfound signals this by silently serving page 1 again, which is why it has to be reported rather than inferred from a short list." }, "stop_reason": { "type": "string", "enum": [ "count_reached", "exhausted", "source_limit", "page_budget", "blocked" ], "example": "count_reached", "description": "Why paging stopped. `count_reached`: your `count` was satisfied and more rows exist. `exhausted`: a page produced nothing new. `source_limit`: Wellfound served page 1 again, its end-of-results signal. `page_budget`: our own page cap was hit before the source ran out. `blocked`: the walk was cut short upstream, so the result is partial and worth retrying." } }, "required": [ "jobs", "startups", "count", "has_more", "ended_at_source_limit" ] }, "WellfoundJob": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": "3061448" }, "title": { "type": "string", "nullable": true, "example": "Senior Software Engineer" }, "slug": { "type": "string", "nullable": true, "example": "senior-software-engineer", "description": "The slug half of the job URL. Pass it with `id` to the job detail endpoint to reproduce the exact URL a browser would request." }, "description": { "type": "string", "nullable": true, "description": "The full posting body, already on the search row — a search result here does not need a follow-up detail call to be readable." }, "compensation": { "type": "string", "nullable": true, "example": "$110k – $155k", "description": "A display string exactly as Wellfound renders it, including its en-dash and the k suffix. It is not parsed into numbers: the same field also carries equity ranges and free text, so a numeric reading would be wrong more often than it is useful. The job detail endpoint's `baseSalary` is the structured version." }, "jobType": { "type": "string", "nullable": true, "example": "full-time" }, "remote": { "type": "boolean", "nullable": true }, "remoteConfig": { "nullable": true, "description": "Wellfound's structured remote policy for the posting. Forwarded verbatim — its shape varies by posting and is not asserted here." }, "locationNames": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "San Francisco", "New York City" ] }, "acceptedRemoteLocationNames": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Where a remote hire may sit. Distinct from `locationNames`, which is where the role itself is anchored." }, "primaryRoleTitle": { "type": "string", "nullable": true, "example": "Software Engineer" }, "yearsExperienceMin": { "type": "number", "nullable": true, "example": 3 }, "yearsExperienceMax": { "type": "number", "nullable": true, "example": 7 }, "liveStartAt": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "nullable": true } ], "example": 1755216000, "description": "When the posting went live, as a unix timestamp." }, "atsSource": { "type": "string", "nullable": true, "example": "AtsIntegration::Greenhouse::Listing", "description": "Which applicant-tracking system the hiring company runs, as Wellfound names it. This is a free company-to-ATS index and is often the most valuable field on the row — it is carried through unchanged, name included." }, "startup": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "Anthropic" }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": "1234567" }, "slug": { "type": "string", "nullable": true, "example": "anthropic", "description": "Company slug, as used in Wellfound's own /company/ URLs." }, "logoUrl": { "type": "string", "nullable": true }, "highConcept": { "type": "string", "nullable": true, "example": "AI safety and research company", "description": "Wellfound's one-line pitch for the company." }, "companySize": { "type": "string", "nullable": true, "example": "SIZE_51_200" }, "badges": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "Wellfound's own company badges (funding stage, growth signals). Forwarded verbatim; the badge vocabulary is not a contract we own." } }, "required": [ "name" ], "additionalProperties": { "nullable": true }, "description": "The hiring company, attached where the page links the two. Null when Wellfound's own cache did not carry the company for this row; the posting is still real, so it is returned either way." } }, "required": [ "id" ], "additionalProperties": { "nullable": true } }, "WellfoundStartup": { "type": "object", "properties": { "name": { "type": "string", "example": "Anthropic" }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "example": "1234567" }, "slug": { "type": "string", "nullable": true, "example": "anthropic", "description": "Company slug, as used in Wellfound's own /company/ URLs." }, "logoUrl": { "type": "string", "nullable": true }, "highConcept": { "type": "string", "nullable": true, "example": "AI safety and research company", "description": "Wellfound's one-line pitch for the company." }, "companySize": { "type": "string", "nullable": true, "example": "SIZE_51_200" }, "badges": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "Wellfound's own company badges (funding stage, growth signals). Forwarded verbatim; the badge vocabulary is not a contract we own." } }, "required": [ "name" ], "additionalProperties": { "nullable": true } }, "WellfoundJobPosting": { "type": "object", "nullable": true, "properties": { "@type": { "type": "string", "enum": [ "JobPosting" ] }, "title": { "type": "string", "example": "Senior Software Engineer" }, "datePosted": { "type": "string", "nullable": true, "example": "2026-08-01" }, "hiringOrganization": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "Anthropic" } }, "required": [ "name" ], "additionalProperties": { "nullable": true } }, "baseSalary": { "type": "object", "nullable": true, "properties": { "currency": { "type": "string", "nullable": true, "example": "USD" }, "value": { "type": "object", "nullable": true, "properties": { "minValue": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "nullable": true } ] }, "maxValue": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "nullable": true } ] }, "unitText": { "type": "string", "nullable": true, "example": "YEAR", "description": "The period the amounts are quoted over — YEAR, MONTH or HOUR. Without it the numbers are not comparable between postings." }, "currency": { "type": "string", "nullable": true } }, "additionalProperties": { "nullable": true } } }, "additionalProperties": { "nullable": true }, "description": "Structured compensation, when the posting states it. Absent — not zero — when it does not." }, "description": { "type": "string", "nullable": true, "description": "The posting body as Wellfound publishes it, HTML markup included." }, "jobLocation": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } } }, { "nullable": true } ], "description": "A schema.org Place, or several. Absent on fully remote postings, which is meaningful rather than missing data." }, "employmentType": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ], "example": "FULL_TIME" }, "directApply": { "type": "boolean", "nullable": true, "description": "Whether the application is completed on Wellfound itself rather than handed off to the company's own ATS." } }, "required": [ "@type", "title" ], "additionalProperties": { "nullable": true } }, "WellfoundStartupsResponse": { "type": "object", "nullable": true, "properties": { "startups": { "type": "array", "items": { "$ref": "#/components/schemas/WellfoundStartup" }, "description": "The companies listed in the directory, deduplicated." }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/WellfoundJob" }, "description": "The highlighted postings the directory renders alongside its companies. Incidental to this endpoint — use the job search route when jobs are what you are after." }, "count": { "type": "integer", "minimum": 0, "example": 20, "description": "How many companies are returned." }, "has_more": { "type": "boolean", "example": true, "description": "Whether more rows were available beyond the ones returned. False means the walk stopped because the source ran out — check `ended_at_source_limit` to tell that apart from simply having satisfied `count`." }, "ended_at_source_limit": { "type": "boolean", "example": false, "description": "True when Wellfound's own result set ran out before `count` was met. It is not an error and not a block: it means the site has no more rows for this query, so retrying or paging further returns nothing new. Wellfound signals this by silently serving page 1 again, which is why it has to be reported rather than inferred from a short list." }, "stop_reason": { "type": "string", "enum": [ "count_reached", "exhausted", "source_limit", "page_budget", "blocked" ], "example": "count_reached", "description": "Why paging stopped. `count_reached`: your `count` was satisfied and more rows exist. `exhausted`: a page produced nothing new. `source_limit`: Wellfound served page 1 again, its end-of-results signal. `page_budget`: our own page cap was hit before the source ran out. `blocked`: the walk was cut short upstream, so the result is partial and worth retrying." } }, "required": [ "startups", "jobs", "count", "has_more", "ended_at_source_limit" ] }, "WellfoundCompanyResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "openai" }, "startup": { "type": "object", "nullable": true, "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ] }, "name": { "type": "string", "nullable": true, "example": "OpenAI" }, "slug": { "type": "string", "nullable": true }, "totalRaisedAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "nullable": true } ], "example": 11000120000, "description": "Lifetime capital raised, in whole currency units. Available from the overview page — unlike the per-round amounts." } }, "additionalProperties": { "nullable": true }, "description": "The company record, identical across sub-pages, lifted out so a caller does not have to pick a section to read it from." }, "hidden_sections": { "type": "array", "items": { "type": "string" }, "default": [], "example": [ "SALARIES" ], "description": "Sections this company has hidden on Wellfound. This is what makes an empty section interpretable: the company withheld it, rather than the fetch having failed." }, "sections": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WellfoundCompanySection" }, "description": "One entry per requested section, keyed by section name. Sections overlap by design — each sub-page carries the same company record plus whatever that tab adds." } }, "required": [ "slug", "sections" ] }, "WellfoundCompanySection": { "type": "object", "properties": { "startup": { "type": "object", "nullable": true, "properties": {}, "additionalProperties": { "nullable": true } }, "rounds": { "type": "array", "items": { "$ref": "#/components/schemas/WellfoundStartupRound" }, "default": [] }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/WellfoundStartupRole" }, "default": [] }, "people": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "default": [] }, "job_listings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "default": [] }, "perks": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true } }, "default": [] }, "hidden_sections": { "type": "array", "items": { "type": "string" }, "default": [] } }, "additionalProperties": { "nullable": true } }, "WellfoundStartupRound": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ] }, "roundType": { "type": "string", "nullable": true, "example": "Series B" }, "raisedAmount": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": "10000000000", "description": "Amount raised, as Wellfound stores it — a string of whole currency units. **Present only when the `funding` section was requested**; the overview page omits it." }, "valuation": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ] }, "closedAt": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "nullable": true } ], "example": 1675900800, "description": "Unix seconds, not milliseconds." }, "pressTitle": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true, "description": "The press coverage Wellfound sourced the round from. Funding section only." } }, "additionalProperties": { "nullable": true } }, "WellfoundStartupRole": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ] }, "title": { "type": "string", "nullable": true, "example": "CTO" }, "role": { "type": "string", "nullable": true, "example": "FOUNDER", "description": "Wellfound's own classification — FOUNDER, EMPLOYEE, etc." }, "roleDisplayName": { "type": "string", "nullable": true }, "tenureSeconds": { "type": "number", "nullable": true, "example": 337881449, "description": "How long this person has held the role, in seconds. Combined with the person's other roles this is a founder-mobility signal the job boards do not publish." }, "user": { "type": "object", "nullable": true, "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ] }, "name": { "type": "string", "nullable": true, "example": "Greg Brockman" }, "slug": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "htmlBio": { "type": "string", "nullable": true } }, "additionalProperties": { "nullable": true } } }, "additionalProperties": { "nullable": true } }, "ClutchDirectoryResponse": { "type": "object", "nullable": true, "properties": { "directory": { "type": "string", "example": "web-developers", "description": "The normalized directory path that was walked." }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ClutchProvider" }, "description": "Distinct providers, de-duplicated on provider id across every page walked and kept in Clutch's own ranking order." }, "count": { "type": "integer", "minimum": 0, "example": 80, "description": "How many providers are returned. Never more than `count`." }, "has_more": { "type": "boolean", "example": true, "description": "Whether paging stopped before exhaustion. This does not guarantee another provider exists; branch on `stop_reason`." }, "stop_reason": { "type": "string", "enum": [ "count_reached", "exhausted", "blocked", "page_budget" ], "example": "count_reached", "description": "Why paging stopped. `count_reached` — `count` was met; ask for more to continue. `exhausted` — the directory has no further providers. `page_budget` — the 12-page per-call cap was hit before `count`; resume with the response's `next_page` as the next call's `start_page`. `blocked` — cut short upstream, the only value worth retrying." }, "pages_walked": { "type": "integer", "minimum": 0, "example": 2, "description": "How many Clutch pages this call actually fetched. Useful for reasoning about cost: each page is paced 6 seconds apart." }, "start_page": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "example": 1, "description": "The page this walk started from, echoed back." }, "next_page": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true, "example": 13, "description": "Where to resume, or `null` when there is nothing to resume. Only set when `stop_reason` is `page_budget`. Pass it as `start_page` on the next call to continue past the per-call page cap — this is the only way to reach providers beyond roughly the first 600 of a directory." } }, "required": [ "directory", "providers", "count", "has_more", "stop_reason", "pages_walked", "start_page", "next_page" ] }, "ClutchProvider": { "type": "object", "properties": { "id": { "type": "string", "example": "1234567" }, "slug": { "type": "string", "nullable": true, "example": "lounge-lizard", "description": "Pass to the profile endpoint for the full record." }, "name": { "type": "string", "nullable": true, "example": "Lounge Lizard" }, "url": { "type": "string", "nullable": true, "example": "https://clutch.co/profile/lounge-lizard", "description": "The agency's page on Clutch, not the agency's own website." }, "rating": { "type": "number", "nullable": true, "example": 4.8 }, "review_count": { "type": "number", "nullable": true, "example": 43, "description": "Reviews behind this row's rating, as the listing states it. The profile endpoint returns two different review counts that disagree with each other — see `review_count_reported` there before treating any single number as authoritative." }, "best_rating": { "type": "number", "nullable": true, "example": 5, "description": "Top of the scale `rating` is on. Returned because it is published, not because it is always 5." }, "worst_rating": { "type": "number", "nullable": true, "example": 0.5 }, "position": { "type": "number", "nullable": true, "example": 3, "description": "Clutch's directory rank for this provider, preserved across de-duplication." }, "telephone": { "type": "string", "nullable": true, "example": "+1 631-581-1000" }, "address": { "$ref": "#/components/schemas/ClutchAddress" }, "min_project_size": { "type": "string", "nullable": true, "example": "$25,000+", "description": "A display string, kept as Clutch writes it — the `+` and the band boundaries are the information, and a numeric reading would discard both." }, "hourly_rate": { "type": "string", "nullable": true, "example": "$100 - $149 / hr", "description": "`\"Undisclosed\"` means the firm withheld its rate; null means no rate was read." }, "employees": { "type": "string", "nullable": true, "example": "50 - 249", "description": "A headcount band as displayed, not a number." }, "location": { "type": "string", "nullable": true, "example": "New York, NY", "description": "The headline location Clutch shows on the card. `address` is the structured version and the two can differ." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ClutchServiceShare" }, "description": "Percentage of the provider's work by service. Empty when Clutch provides no service mix." } }, "required": [ "id", "address", "services" ], "additionalProperties": { "nullable": true } }, "ClutchAddress": { "type": "object", "properties": { "street": { "type": "string", "nullable": true, "example": "1 Little W 12th St" }, "locality": { "type": "string", "nullable": true, "example": "New York" }, "region": { "type": "string", "nullable": true, "example": "NY" }, "postal_code": { "type": "string", "nullable": true, "example": "10014" }, "country": { "type": "string", "nullable": true, "example": "US" } }, "additionalProperties": { "nullable": true } }, "ClutchServiceShare": { "type": "object", "properties": { "share_pct": { "type": "integer", "nullable": true, "example": 45, "description": "Percentage of the firm's work in this line, as Clutch publishes it. The shares on a provider sum to 100 when Clutch renders a full mix, but that is Clutch's arithmetic and is not enforced here." }, "service": { "type": "string", "example": "Web Development" } }, "required": [ "service" ], "additionalProperties": { "nullable": true } }, "ClutchProfileResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "wpromote", "description": "Echoed back so a row can be matched to its request." }, "name": { "type": "string", "nullable": true, "example": "Wpromote" }, "description": { "type": "string", "nullable": true }, "website": { "nullable": true, "example": "https://www.wpromote.com", "description": "The agency's own site, taken from the schema.org `sameAs` property. That property is allowed to be a single URL or a list of them, so it is forwarded as published rather than forced into one shape." }, "clutch_url": { "type": "string", "nullable": true, "example": "https://clutch.co/profile/wpromote" }, "telephone": { "type": "string", "nullable": true }, "founded": { "type": "string", "nullable": true, "example": "2001", "description": "schema.org `foundingDate`. Often a bare year." }, "logo": { "nullable": true, "description": "schema.org `image` — a URL, an ImageObject, or a list. Forwarded verbatim; its shape is Clutch's choice per profile." }, "rating": { "type": "number", "nullable": true, "example": 4.7 }, "rating_scale": { "type": "object", "properties": { "best": { "type": "number", "nullable": true, "example": 5 }, "worst": { "type": "number", "nullable": true, "example": 0.5 } }, "additionalProperties": { "nullable": true }, "description": "The scale `rating` sits on. Clutch's worst is 0.5, not 0 or 1, so normalising a Clutch rating to a percentage without this is wrong." }, "review_count_reported": { "type": "integer", "nullable": true, "example": 3, "description": "Review count reported by Clutch's aggregate rating. It may differ from `reviews_embedded`." }, "reviews_embedded": { "type": "integer", "minimum": 0, "example": 9, "description": "Number of reviews in this response. `review_count_reported` is Clutch's aggregate count." }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ClutchReview" }, "description": "The reviews embedded in the page. Empty for a profile with none — never null. Reviews beyond this set live behind Clutch's own `/profile//review/facets` endpoint, which `review_nonce` exists to let you call." }, "address": { "$ref": "#/components/schemas/ClutchAddress" }, "offer_catalog": { "type": "array", "items": { "nullable": true }, "description": "schema.org `hasOfferCatalog.itemListElement`, forwarded verbatim. It is the profile-tier counterpart to a directory row's `services`, but without the percentage shares — the listing is the better source for the mix." }, "review_nonce": { "type": "string", "nullable": true, "example": "aXfQ2p7...", "description": "Single-use token from the rendered page for driving Clutch's own review paginator: `GET /profile//review/facets?&nonce=`. Not reusable across profiles and does not outlive the page it came from. `null` means the page rendered without one." } }, "required": [ "slug", "rating_scale", "reviews_embedded", "reviews", "address", "offer_catalog" ], "additionalProperties": { "nullable": true } }, "ClutchReview": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "example": "SEO & PPC Services for E-Commerce Retailer" }, "published_at": { "type": "string", "nullable": true, "example": "2026-03-11", "description": "As Clutch publishes it, not re-formatted." }, "author": { "type": "string", "nullable": true, "example": "Marketing Director, Retail Company", "description": "Clutch commonly publishes a role and company type rather than a person's name. Returned as written." }, "body": { "type": "string", "nullable": true }, "rating": { "type": "number", "nullable": true, "example": 5 } }, "additionalProperties": { "nullable": true } }, "ClutchSitemapResponse": { "anyOf": [ { "$ref": "#/components/schemas/ClutchSitemapIndexResponse" }, { "$ref": "#/components/schemas/ClutchSitemapUrlsResponse" }, { "nullable": true } ] }, "ClutchSitemapIndexResponse": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "profile", "directory" ], "example": "profile" }, "sitemaps": { "type": "array", "items": { "type": "string" }, "example": [ "https://clutch.co/sitemap-profile-1.xml" ], "description": "The numbered sitemaps Clutch publishes for this `kind`, filtered out of its root `/sitemap.xml`. Their trailing number is what to pass back as `index`." }, "count": { "type": "integer", "minimum": 0, "example": 45 } }, "required": [ "kind", "sitemaps", "count" ] }, "ClutchSitemapUrlsResponse": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "profile", "directory" ], "example": "profile" }, "index": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "example": 1 }, "urls": { "type": "array", "items": { "type": "string" }, "example": [ "https://clutch.co/profile/wpromote" ], "description": "Every `` in that sitemap. For `kind=profile` the last path segment is the `slug` the profile endpoint takes; for `kind=directory` the path minus its leading slash is the `directory` the directory endpoint takes." }, "count": { "type": "integer", "minimum": 0, "example": 5000 } }, "required": [ "kind", "index", "urls", "count" ] }, "IndeedSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string", "nullable": true, "example": "software engineer", "description": "The query Indeed says it ran, echoed from the page." }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "radius": { "type": "number", "nullable": true, "example": 25 }, "page_number": { "type": "number", "nullable": true, "example": 1, "description": "Page number. This search surface returns page 1 only." }, "search_uid": { "type": "string", "nullable": true, "description": "Identifier for this search execution. Identical requests can return different result sets." }, "search_timestamp": { "type": "number", "nullable": true }, "count": { "type": "integer", "minimum": 0, "example": 42, "description": "How many rows are in `results`, and nothing more. It is not a result total and there is no way to obtain one from this surface." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedSearchResult" }, "description": "Job rows on the available page. Identical requests can return a partly different set of current postings." }, "has_more": { "type": "boolean", "enum": [ false ], "example": false, "description": "Always `false` because this search surface returns one page. Vary `query`, `location`, `radius`, and filters to cover more jobs." }, "stop_reason": { "type": "string", "enum": [ "page_two_requires_signin", "no_results_blob" ], "example": "page_two_requires_signin", "description": "Why results ended: `page_two_requires_signin` means the first page was returned; `no_results_blob` means the query matched no jobs." }, "source_index_tier_counts": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedTierCount" }, "description": "Indeed's per-tier index counts for the query. Tiers overlap, so these values are neither a result total nor safe to add together." }, "reported_total_note": { "type": "string", "description": "The caveat above, carried in the payload so it survives into any client that renders these fields without reading the docs." } }, "required": [ "query", "location", "radius", "page_number", "search_uid", "search_timestamp", "count", "results", "has_more", "stop_reason", "source_index_tier_counts", "reported_total_note" ] }, "IndeedSearchResult": { "type": "object", "properties": { "job_key": { "type": "string", "example": "16dee99e6784de74", "description": "Indeed's `jobkey`, and the identity of the posting. Pass it to `/indeed/jobs/detail` for the full description and structured salary." }, "title": { "type": "string", "nullable": true, "example": "Senior Software Engineer" }, "display_title": { "type": "string", "nullable": true, "description": "The title as rendered on the card, which can differ from `title` when Indeed truncates or annotates it." }, "normalized_title": { "type": "string", "nullable": true, "example": "software engineer", "description": "Indeed's own normalisation of the title (`normTitle`) — the field it groups roles by, and the one to aggregate on rather than `title`." }, "company": { "$ref": "#/components/schemas/IndeedSearchCompany" }, "location": { "$ref": "#/components/schemas/IndeedSearchLocation" }, "salary": { "$ref": "#/components/schemas/IndeedSearchSalary" }, "job_types": { "type": "array", "items": { "type": "string" }, "example": [ "Full-time" ], "description": "Convenience view of the \"job-types\" taxonomy, which is the one almost every caller wants. Everything else stays in `attributes`." }, "attributes": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "job-types": [ "Full-time" ], "benefits": [ "401(k)" ] }, "description": "Indeed's `taxonomyAttributes`, flattened from its nested label/attributes form into taxonomy name -> values. Shift patterns, benefits and encouraged-to-apply tags all arrive here." }, "snippet_html": { "type": "string", "nullable": true, "description": "The truncated bullet list Indeed shows on the card, HTML included. This is not the posting — `/indeed/jobs/detail` returns the full description." }, "created_at": { "type": "string", "nullable": true, "example": "2026-08-01T09:14:00.000Z", "description": "When Indeed first indexed the posting." }, "created_at_ms": { "type": "number", "nullable": true, "description": "The same indexing time in epoch milliseconds." }, "published_at": { "type": "string", "nullable": true, "example": "2026-08-01T09:14:00.000Z", "description": "When the posting went live (`pubDate`)." }, "published_at_ms": { "type": "number", "nullable": true }, "posted_relative": { "type": "string", "nullable": true, "example": "3 days ago", "description": "Indeed's own relative phrasing, as shown on the card." }, "sponsored": { "type": "boolean", "example": true, "description": "Whether the employer paid for this placement. With `ad_bid` below, this answers \"who is buying visibility for this query, and at what rank\" — which no competitor's output supports." }, "package_tier": { "type": "string", "nullable": true, "example": "PREMIUM", "description": "Which advertising package the placement was bought under." }, "ad_id": { "type": "string", "nullable": true, "description": "Indeed's `adId` for a sponsored placement." }, "advertiser_id": { "type": "string", "nullable": true, "description": "Indeed's `advn` — the advertiser behind the placement." }, "ad_bid": { "type": "number", "nullable": true, "example": 195880, "description": "Advertising bid for this placement in Indeed's own units. `null` on organic rows." }, "ad_bid_position": { "type": "number", "nullable": true, "example": 2, "description": "Where that bid placed the row in the auction (`rankingScoresModel.bidPosition`)." }, "expected_apply": { "type": "number", "nullable": true, "description": "Indeed's `rankingScoresModel.eApply` score. Forwarded because it is part of the same ranking model; its exact semantics are Indeed's and have not been measured here, so do not read it as a probability." }, "expected_qualified": { "type": "number", "nullable": true, "description": "Indeed's `rankingScoresModel.eQualified`, same caveat." }, "organic_apply_start_count": { "type": "number", "nullable": true, "description": "How many applications Indeed counts as started on this posting. A demand signal on the employer's side of the market." }, "job_url": { "type": "string", "nullable": true, "example": "https://www.indeed.com/viewjob?jk=16dee99e6784de74" }, "apply_url": { "type": "string", "nullable": true, "description": "The employer's own application URL when the posting hands off to an external ATS (`thirdPartyApplyUrl`). Null when the application is completed on Indeed." }, "feed_id": { "type": "string", "nullable": true, "description": "Which Indeed ingestion feed the posting arrived on — with `source_id`, this says whether an employer posts directly or through an aggregator." }, "source_id": { "type": "string", "nullable": true } }, "required": [ "job_key", "title", "display_title", "normalized_title", "company", "location", "salary", "job_types", "attributes", "snippet_html", "created_at", "created_at_ms", "published_at", "published_at_ms", "posted_relative", "sponsored", "package_tier", "ad_id", "advertiser_id", "ad_bid", "ad_bid_position", "expected_apply", "expected_qualified", "organic_apply_start_count", "job_url", "apply_url", "feed_id", "source_id" ] }, "IndeedSearchCompany": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Stripe" }, "rating": { "type": "number", "nullable": true, "example": 3.9, "description": "Indeed's 1-5 employer rating. Null when unrated." }, "review_count": { "type": "number", "nullable": true, "example": 1204 }, "slug": { "type": "string", "nullable": true, "example": "Stripe", "description": "The company's /cmp/ slug, lifted out of the profile link on the row — pass it straight to `/indeed/company` for the full profile." }, "profile_url": { "type": "string", "nullable": true, "example": "https://www.indeed.com/cmp/Stripe" }, "encrypted_id": { "type": "string", "nullable": true, "description": "Indeed's own opaque company id (`companyIdEncrypted`). Stable across rows, which makes it a better join key than the display name." } }, "required": [ "name", "rating", "review_count", "slug", "profile_url", "encrypted_id" ] }, "IndeedSearchLocation": { "type": "object", "properties": { "formatted": { "type": "string", "nullable": true, "example": "San Francisco, CA 94103" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "state": { "type": "string", "nullable": true, "example": "CA" }, "country": { "type": "string", "nullable": true, "example": "US" } }, "required": [ "formatted", "city", "state", "country" ] }, "IndeedSearchSalary": { "type": "object", "nullable": true, "properties": { "min": { "type": "number", "nullable": true, "example": 145000 }, "max": { "type": "number", "nullable": true, "example": 210000 }, "period": { "type": "string", "nullable": true, "example": "YEARLY", "description": "The period the amounts are quoted over, from Indeed's `extractedSalary.type`. Without it the numbers are not comparable between rows." }, "text": { "type": "string", "nullable": true, "example": "$145,000 - $210,000 a year", "description": "The salary exactly as Indeed renders it on the card." }, "currency": { "type": "string", "nullable": true, "example": "USD" }, "source": { "type": "string", "nullable": true, "example": "EXTRACTION", "description": "Where Indeed got the figure — whether the employer stated it or Indeed estimated it. Its vocabulary is Indeed's, forwarded as-is." } }, "required": [ "min", "max", "period", "text", "currency", "source" ], "description": "Null when the posting states no pay. Indeed has already parsed the range into numbers, so unlike most job boards this needs no string handling on your side." }, "IndeedTierCount": { "type": "object", "properties": { "tier": { "type": "number", "nullable": true }, "type": { "type": "string", "nullable": true, "example": "NATIONWIDE" }, "job_count": { "type": "number", "nullable": true, "example": 13 } }, "required": [ "tier", "type", "job_count" ] }, "IndeedJobResponse": { "type": "object", "nullable": true, "properties": { "job_key": { "type": "string", "nullable": true, "example": "16dee99e6784de74" }, "url": { "type": "string", "nullable": true, "example": "https://www.indeed.com/viewjob?jk=16dee99e6784de74" }, "title": { "type": "string", "nullable": true, "example": "Senior Software Engineer" }, "description_html": { "type": "string", "nullable": true, "description": "**The whole posting**, as the employer wrote it, HTML markup included. The search row's `snippet_html` is a truncated bullet list; this is the document." }, "date_posted": { "type": "string", "nullable": true, "example": "2026-08-01" }, "valid_through": { "type": "string", "nullable": true, "example": "2026-09-30", "description": "When the posting expires, where the employer states it. This is the field that says whether a listing is still live without re-fetching it." }, "employment_type": { "type": "array", "items": { "type": "string" }, "example": [ "FULL_TIME" ], "description": "Always an array, because schema.org permits one value or several and Indeed uses both forms." }, "direct_apply": { "type": "boolean", "nullable": true, "description": "Whether the application is completed on Indeed itself rather than handed off to the employer's own ATS." }, "hiring_organization": { "$ref": "#/components/schemas/IndeedJobOrganization" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedJobLocation" }, "description": "Every `jobLocation` on the posting. Empty on fully remote roles, which is meaningful rather than missing." }, "salary": { "$ref": "#/components/schemas/IndeedJobSalary" }, "identifier": { "type": "string", "nullable": true, "description": "The employer's own requisition id, when the posting has one." }, "occupational_category": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true } }, "required": [ "job_key", "url", "title", "description_html", "date_posted", "valid_through", "employment_type", "direct_apply", "hiring_organization", "locations", "salary", "identifier", "occupational_category", "industry" ] }, "IndeedJobOrganization": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "example": "Stripe" }, "url": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true } }, "required": [ "name", "url", "logo" ] }, "IndeedJobLocation": { "type": "object", "properties": { "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "region": { "type": "string", "nullable": true, "example": "CA" }, "postal_code": { "type": "string", "nullable": true, "example": "94103" }, "country": { "type": "string", "nullable": true, "example": "US" }, "street_address": { "type": "string", "nullable": true } }, "required": [ "city", "region", "postal_code", "country", "street_address" ] }, "IndeedJobSalary": { "type": "object", "nullable": true, "properties": { "currency": { "type": "string", "nullable": true, "example": "USD" }, "min": { "type": "number", "nullable": true, "example": 145000 }, "max": { "type": "number", "nullable": true, "example": 210000 }, "period": { "type": "string", "nullable": true, "example": "YEAR", "description": "schema.org `unitText` — HOUR, DAY, WEEK, MONTH or YEAR. Without it the amounts are not comparable between postings." } }, "required": [ "currency", "min", "max", "period" ], "description": "schema.org `baseSalary`, structured. Null — not zero — when the posting states no pay." }, "IndeedCompanyResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "Stripe" }, "url": { "type": "string", "example": "https://www.indeed.com/cmp/Stripe" }, "name": { "type": "string", "nullable": true, "example": "Stripe" }, "rating": { "type": "number", "nullable": true, "example": 3.9 }, "review_count": { "type": "number", "nullable": true, "example": 1204 }, "happiness_score": { "type": "number", "nullable": true, "example": 64 }, "happiness_grade": { "type": "string", "nullable": true, "example": "B" }, "about": { "$ref": "#/components/schemas/IndeedCompanyAbout" }, "happiness": { "$ref": "#/components/schemas/IndeedCompanyHappiness" }, "review_ratings": { "$ref": "#/components/schemas/IndeedCompanyReviewRatings" }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedCompanyReview" }, "description": "**The reviews embedded in the profile — five of them**, regardless of how many `review_count` reports. Deep review pagination lives on a separate Indeed page that this API does not serve, so treat these as a sample, never as the review set." }, "job_titles": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedCompanyJobTitle" }, "description": "Roles the company hires for, with counts and ratings." }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedCompanyLocation" } }, "similar_companies": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedSimilarCompany" }, "description": "Indeed's own competitor set for this employer — a ready-made peer group for benchmarking, with each peer's rating and review volume." } }, "required": [ "slug", "url", "name", "rating", "review_count", "happiness_score", "happiness_grade", "about", "happiness", "review_ratings", "reviews", "job_titles", "locations", "similar_companies" ] }, "IndeedCompanyAbout": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true, "example": 2010 }, "industry": { "type": "string", "nullable": true, "example": "Financial Services" }, "revenue": { "type": "string", "nullable": true, "example": "$1B to $5B (USD)" }, "employee_range": { "type": "string", "nullable": true, "example": "5,001 to 10,000" }, "ceo_approval": { "type": "number", "nullable": true, "example": 77, "description": "Percentage of surveyed employees who approve of the CEO. Glassdoor-class employer-brand data, from a site whose existing actors do not expose it." }, "website_url": { "type": "string", "nullable": true, "example": "https://stripe.com" }, "headquarters": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "sectors": { "type": "array", "items": { "type": "string" }, "example": [ "Financial Services" ] } }, "required": [ "description", "founded", "industry", "revenue", "employee_range", "ceo_approval", "website_url", "headquarters", "sectors" ] }, "IndeedCompanyHappiness": { "type": "object", "nullable": true, "properties": { "composite_score": { "type": "number", "nullable": true, "example": 64 }, "response_count": { "type": "number", "nullable": true, "example": 1832 }, "ratings": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedHappinessRating" }, "description": "The 15 individual dimensions of Indeed's Work Happiness survey — compensation, belonging, flexibility, purpose, and so on, each with its own score and letter grade." } }, "required": [ "composite_score", "response_count", "ratings" ], "description": "Indeed's 15-dimension Work Happiness survey. Null when the company has too few responses for Indeed to publish one." }, "IndeedHappinessRating": { "type": "object", "properties": { "category": { "type": "string", "nullable": true, "example": "Compensation" }, "question_code": { "type": "string", "nullable": true, "example": "COMPENSATION" }, "score": { "type": "number", "nullable": true, "example": 71 }, "grade": { "type": "string", "nullable": true, "example": "B" }, "caption": { "type": "string", "nullable": true, "example": "People feel they are paid fairly for their work" } }, "required": [ "category", "question_code", "score", "grade", "caption" ] }, "IndeedCompanyReviewRatings": { "type": "object", "nullable": true, "properties": { "compensation_benefits": { "type": "number", "nullable": true, "example": 4.1 }, "culture": { "type": "number", "nullable": true, "example": 3.8 }, "job_security_advancement": { "type": "number", "nullable": true, "example": 3.4 }, "management": { "type": "number", "nullable": true, "example": 3.5 }, "work_life_balance": { "type": "number", "nullable": true, "example": 3.9 } }, "required": [ "compensation_benefits", "culture", "job_security_advancement", "management", "work_life_balance" ], "description": "The five category averages Indeed breaks its star rating into. Null when the company has no reviews." }, "IndeedCompanyReview": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "example": "Great place to grow" }, "text": { "type": "string", "nullable": true }, "rating": { "type": "number", "nullable": true, "example": 4 }, "submitted_at": { "type": "string", "nullable": true, "example": "2026-06-12" }, "current_employee": { "type": "boolean", "nullable": true }, "job_title": { "type": "string", "nullable": true, "example": "Software Engineer" }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA" } }, "required": [ "title", "text", "rating", "submitted_at", "current_employee", "job_title", "location" ] }, "IndeedCompanyJobTitle": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "example": "Software Engineer" }, "job_count": { "type": "number", "nullable": true, "example": 128 }, "rating": { "type": "number", "nullable": true, "example": 4.2 } }, "required": [ "title", "job_count", "rating" ] }, "IndeedCompanyLocation": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "rating": { "type": "number", "nullable": true, "example": 4 } }, "required": [ "name", "rating" ] }, "IndeedSimilarCompany": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Square" }, "rating": { "type": "number", "nullable": true, "example": 3.7 }, "review_count": { "type": "number", "nullable": true, "example": 2210 }, "salary_count": { "type": "number", "nullable": true, "example": 4820 }, "sectors": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "rating", "review_count", "salary_count", "sectors" ] }, "IndeedSalariesResponse": { "type": "object", "nullable": true, "properties": { "requested_title": { "type": "string", "nullable": true, "example": "software-engineer", "description": "Normalized title used for the salary search." }, "requested_location": { "type": "string", "nullable": true, "example": "San-Francisco--CA", "description": "Location used for the salary search, in Indeed's encoding. `null` for a national request." }, "title": { "type": "string", "nullable": true, "example": "Software Engineer", "description": "The title as Indeed displays it." }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "country": { "type": "string", "nullable": true, "example": "US" }, "national": { "$ref": "#/components/schemas/IndeedSalaryAggregate" }, "local": { "allOf": [ { "$ref": "#/components/schemas/IndeedSalaryAggregate" }, { "description": "The same for the requested location. Null on a national request." } ] }, "percentiles": { "$ref": "#/components/schemas/IndeedSalaryPercentiles" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedSalaryRegion" }, "description": "**All 51 US regions in one response** — every state plus DC, each with its own average and sample count. No per-state fan-out is needed, and no state request returns more than this already has." }, "top_paying_companies": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedTopPayingCompany" }, "description": "The employers paying most for this title (53 on the page measured), with each one's mean, sample count and employer rating." }, "top_paid_cities": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedTopPaidCity" }, "description": "City-level distributions, ranked by pay." }, "related_titles": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedRelatedTitle" }, "description": "Adjacent titles with their means — the cheapest way to price a career ladder without one request per rung." }, "compensations": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedCompensation" }, "description": "Non-salary compensation Indeed tracks for the title, such as cash bonuses, with the mean amount." }, "last_updated_at": { "type": "string", "nullable": true, "example": "2026-08-09T14:44:30.000Z", "description": "When Indeed last recomputed these aggregates." } }, "required": [ "requested_title", "requested_location", "title", "location", "country", "national", "local", "percentiles", "regions", "top_paying_companies", "top_paid_cities", "related_titles", "compensations", "last_updated_at" ] }, "IndeedSalaryAggregate": { "type": "object", "nullable": true, "properties": { "most_common": { "$ref": "#/components/schemas/IndeedSalaryDistribution" }, "by_period": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedSalaryDistribution" }, "description": "The same population expressed hourly, daily, weekly, monthly and yearly, so hourly and salaried roles can be compared without assuming an hours-per-year figure." } }, "required": [ "most_common", "by_period" ], "description": "The nationwide distribution for the title." }, "IndeedSalaryDistribution": { "type": "object", "nullable": true, "properties": { "period": { "type": "string", "nullable": true, "example": "YEARLY", "description": "HOURLY, DAILY, WEEKLY, MONTHLY or YEARLY." }, "median": { "type": "number", "nullable": true, "example": 135340 }, "mean": { "type": "number", "nullable": true, "example": 147195 }, "min": { "type": "number", "nullable": true, "example": 62000 }, "max": { "type": "number", "nullable": true, "example": 320000 }, "standard_deviation": { "type": "number", "nullable": true, "example": 62942 }, "sample_count": { "type": "number", "nullable": true, "example": 39565, "description": "How many reported salaries the figures rest on. Read this before the median: a distribution over 12 samples and one over 39,565 are not the same kind of number." } }, "required": [ "period", "median", "mean", "min", "max", "standard_deviation", "sample_count" ], "description": "Indeed's headline distribution for the title — the one its own page leads with." }, "IndeedSalaryPercentiles": { "type": "object", "nullable": true, "properties": { "percentile_10": { "type": "number", "nullable": true, "example": 80048 }, "median": { "type": "number", "nullable": true, "example": 135340 }, "percentile_90": { "type": "number", "nullable": true, "example": 228825 }, "currency": { "type": "string", "nullable": true, "example": "USD" }, "period": { "type": "string", "nullable": true, "example": "YEAR" } }, "required": [ "percentile_10", "median", "percentile_90", "currency", "period" ], "description": "The 10th/50th/90th percentile spread, taken from the schema.org `Occupation` markup on the page. This is the only place the tails of the distribution are published — the aggregates above give the centre, this gives the shape." }, "IndeedSalaryRegion": { "type": "object", "properties": { "region": { "type": "string", "example": "WA" }, "name": { "type": "string", "nullable": true, "example": "Washington" }, "yearly_avg_salary": { "type": "number", "nullable": true, "example": 114226 }, "sample_count": { "type": "number", "nullable": true, "example": 1290 }, "percent_change_from_base": { "type": "number", "nullable": true, "example": 12.4, "description": "How far this region sits from the national figure, as Indeed computes it." } }, "required": [ "region", "name", "yearly_avg_salary", "sample_count", "percent_change_from_base" ] }, "IndeedTopPayingCompany": { "type": "object", "properties": { "employer_key": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "Netflix" }, "rating": { "type": "number", "nullable": true, "example": 4.2 }, "review_count": { "type": "number", "nullable": true, "example": 812 }, "salary_mean": { "type": "number", "nullable": true, "example": 268400 }, "salary_count": { "type": "number", "nullable": true, "example": 214 }, "salary_period": { "type": "string", "nullable": true, "example": "YEARLY" } }, "required": [ "employer_key", "name", "rating", "review_count", "salary_mean", "salary_count", "salary_period" ] }, "IndeedTopPaidCity": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "San Jose, CA" }, "salary": { "$ref": "#/components/schemas/IndeedSalaryDistribution" } }, "required": [ "name", "salary" ] }, "IndeedRelatedTitle": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "example": "senior software engineer" }, "salary_mean": { "type": "number", "nullable": true, "example": 168200 } }, "required": [ "title", "salary_mean" ] }, "IndeedCompensation": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "example": "CASH_BONUS" }, "mean": { "type": "number", "nullable": true, "example": 5000 } }, "required": [ "type", "mean" ] }, "DiceSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string" }, "location": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true, "description": "The search page actually fetched. Null on the rare render with no results section at all." }, "current_page": { "type": "number", "nullable": true }, "total_pages": { "type": "number", "nullable": true }, "page_size": { "type": "number", "nullable": true }, "total_results_label": { "type": "string", "nullable": true, "example": "11568 results (695 new)", "description": "Dice's own headline string, kept verbatim rather than parsed into an int — the \"(N new)\" qualifier is undocumented anywhere Dice publishes." }, "count": { "type": "number", "description": "Rows actually in `results`, counted here rather than trusted from upstream." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DiceSearchResult" } }, "has_more": { "type": "boolean" }, "stop_reason": { "type": "string", "nullable": true, "example": "no_results_blob", "description": "Set only when `results` is empty: the page rendered but carried no results section." } }, "required": [ "query", "location", "url", "current_page", "total_pages", "page_size", "total_results_label", "count", "results", "has_more", "stop_reason" ] }, "DiceSearchResult": { "type": "object", "properties": { "job_id": { "type": "string", "example": "bba4ebb5-9b44-4f34-b325-7cf129466ac7", "description": "Hand this to /dice/job as `job_id` for the full posting." }, "title": { "type": "string", "nullable": true, "example": "Senior Software Engineer - Mission Systems Integration" }, "company_name": { "type": "string", "nullable": true, "example": "Redhorse Corporation" }, "company_profile_id": { "type": "string", "nullable": true, "description": "Dice's own company id — matches the tail of hiring_organization.url on the job detail." }, "employment_type": { "type": "string", "nullable": true, "example": "Full-time" }, "employer_type": { "type": "string", "nullable": true, "example": "Direct Hire" }, "posted_date": { "type": "string", "nullable": true, "example": "2026-09-01T05:13:12Z" }, "modified_date": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true, "description": "A truncated lead-in to the full description — not the whole posting." }, "salary": { "type": "string", "nullable": true, "example": "USD 190,000.00 - 300,000.00 per year", "description": "Dice's own free-text label, kept verbatim. Employers write this field with no fixed format (a range, an hourly rate, or literally \"Depends on Experience\"), so it is not parsed into numbers here." }, "location": { "$ref": "#/components/schemas/DiceSearchResultLocation" }, "is_remote": { "type": "boolean", "nullable": true }, "is_featured": { "type": "boolean", "nullable": true }, "easy_apply": { "type": "boolean", "nullable": true }, "workplace_types": { "type": "array", "items": { "type": "string" }, "example": [ "Remote" ] }, "url": { "type": "string", "nullable": true } }, "required": [ "job_id", "title", "company_name", "company_profile_id", "employment_type", "employer_type", "posted_date", "modified_date", "summary", "salary", "location", "is_remote", "is_featured", "easy_apply", "workplace_types", "url" ] }, "DiceSearchResultLocation": { "type": "object", "nullable": true, "properties": { "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true, "example": "NY", "description": "Dice's state abbreviation, kept separate from the full `state` name." }, "country": { "type": "string", "nullable": true }, "display_name": { "type": "string", "nullable": true, "example": "New York, New York, USA" } }, "required": [ "city", "state", "region", "country", "display_name" ] }, "DiceJobResponse": { "type": "object", "nullable": true, "properties": { "job_id": { "type": "string", "example": "bba4ebb5-9b44-4f34-b325-7cf129466ac7" }, "url": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true, "example": "Senior Software Engineer - Mission Systems Integration" }, "description_html": { "type": "string", "nullable": true, "description": "The whole posting, as the employer wrote it, HTML markup included." }, "date_posted": { "type": "string", "nullable": true }, "valid_through": { "type": "string", "nullable": true, "description": "When the posting expires, where Dice states it." }, "employment_type": { "type": "array", "items": { "type": "string" }, "example": [ "FULL_TIME" ], "description": "Always an array — schema.org permits one value or several." }, "hiring_organization": { "$ref": "#/components/schemas/DiceJobOrganization" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/DiceJobLocation" }, "description": "Empty for a fully remote posting, which carries no jobLocation at all." }, "location_type": { "type": "string", "nullable": true, "example": "TELECOMMUTE", "description": "schema.org `jobLocationType` — present and set to TELECOMMUTE on remote postings." }, "applicant_location": { "type": "string", "nullable": true, "example": "USA", "description": "The country a remote posting requires applicants to be in, where Dice states one." }, "salary": { "$ref": "#/components/schemas/DiceJobSalary" }, "identifier": { "type": "string", "nullable": true } }, "required": [ "job_id", "url", "title", "description_html", "date_posted", "valid_through", "employment_type", "hiring_organization", "locations", "location_type", "applicant_location", "salary", "identifier" ] }, "DiceJobOrganization": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "example": "Redhorse Corporation" }, "url": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true } }, "required": [ "name", "url", "logo" ] }, "DiceJobLocation": { "type": "object", "properties": { "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "street_address": { "type": "string", "nullable": true } }, "required": [ "city", "region", "postal_code", "country", "street_address" ] }, "DiceJobSalary": { "type": "object", "nullable": true, "properties": { "currency": { "type": "string", "nullable": true, "example": "USD" }, "min": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true }, "period": { "type": "string", "nullable": true, "example": "YEAR", "description": "schema.org `unitText` — HOUR, DAY, WEEK, MONTH or YEAR." } }, "required": [ "currency", "min", "max", "period" ], "description": "Null when the posting states no pay — a real, common answer, not a parse failure." }, "SeekSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string" }, "location": { "type": "string", "nullable": true }, "page": { "type": "integer" }, "echoed_page": { "type": "string", "nullable": true, "description": "Present only when the request carried an explicit `page` beyond 1 — confirms Seek's own query state matches what was requested." }, "url": { "type": "string", "nullable": true, "description": "The search page actually fetched. Null on the rare render with no results section at all." }, "total_count": { "type": "number", "nullable": true, "example": 8421, "description": "Seek's own reported total matches for the query." }, "page_size": { "type": "number", "nullable": true, "example": 32 }, "count": { "type": "number", "description": "Rows actually in `results`, counted here rather than trusted from upstream." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SeekSearchResult" } }, "has_more": { "type": "boolean" }, "stop_reason": { "type": "string", "nullable": true, "example": "no_results_blob", "description": "Set only when `results` is empty: the page rendered but carried no results section." }, "related_searches": { "type": "array", "items": { "$ref": "#/components/schemas/SeekRelatedSearch" }, "description": "Adjacent queries Seek suggests, each with its own result count." } }, "required": [ "query", "location", "page", "echoed_page", "url", "total_count", "page_size", "count", "results", "has_more", "stop_reason", "related_searches" ] }, "SeekSearchResult": { "type": "object", "properties": { "job_id": { "type": "string", "example": "94059954", "description": "Hand this to /seek/job as `job_id` for the full posting." }, "title": { "type": "string", "nullable": true, "example": "Founding Engineer" }, "teaser": { "type": "string", "nullable": true, "description": "The one-line pitch shown on the card, not the full posting." }, "bullet_points": { "type": "array", "items": { "type": "string" }, "example": [ "Six-figure ARR in months, top global hotel brands, new category" ], "description": "The employer's own highlight bullets, when the listing carries them." }, "advertiser": { "$ref": "#/components/schemas/SeekSearchAdvertiser" }, "logo_url": { "type": "string", "nullable": true }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/SeekSearchLocation" }, "description": "Usually one entry; Seek allows more for a multi-location posting." }, "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/SeekSearchClassification" } }, "display_type": { "type": "string", "nullable": true, "example": "promoted", "description": "Seek's own placement tier for the row — organic, promoted, or a paid variant." }, "is_featured": { "type": "boolean", "nullable": true }, "ad_type": { "type": "string", "nullable": true, "example": "SPONSORED", "description": "Seek's own ad classification for the row, from its placement metadata." }, "listed_at": { "type": "string", "nullable": true, "example": "2026-08-18T21:50:30.000Z" }, "listed_at_display": { "type": "string", "nullable": true, "example": "15d ago", "description": "Seek's own relative phrasing, as shown on the card." }, "role_id": { "type": "string", "nullable": true }, "salary_label": { "type": "string", "nullable": true, "example": "$12,000 – $17,000 per month", "description": "Seek's own free-text label, kept verbatim. Employers write this field with no fixed format, so it is not parsed into numbers here." }, "work_types": { "type": "array", "items": { "type": "string" }, "example": [ "Full time" ] }, "work_arrangement": { "type": "string", "nullable": true, "example": "Hybrid", "description": "Seek's own work-arrangement label, when the listing states one." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/SeekSearchTag" } } }, "required": [ "job_id", "title", "teaser", "bullet_points", "advertiser", "logo_url", "locations", "classifications", "display_type", "is_featured", "ad_type", "listed_at", "listed_at_display", "role_id", "salary_label", "work_types", "work_arrangement", "tags" ] }, "SeekSearchAdvertiser": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "Visaible", "description": "Seek's own `description` field on the advertiser — its display name." } }, "required": [ "id", "name" ] }, "SeekSearchLocation": { "type": "object", "properties": { "country_code": { "type": "string", "nullable": true, "example": "AU" }, "label": { "type": "string", "nullable": true, "example": "Sydney NSW" } }, "required": [ "country_code", "label" ] }, "SeekSearchClassification": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "Engineering - Software" }, "parent_id": { "type": "string", "nullable": true }, "parent_name": { "type": "string", "nullable": true, "example": "Information & Communication Technology" } }, "required": [ "id", "name", "parent_id", "parent_name" ] }, "SeekSearchTag": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "example": "URGENT" }, "label": { "type": "string", "nullable": true, "example": "Immediate start" } }, "required": [ "type", "label" ] }, "SeekRelatedSearch": { "type": "object", "properties": { "keywords": { "type": "string", "nullable": true, "example": "software developer" }, "total_jobs": { "type": "number", "nullable": true, "example": 441 } }, "required": [ "keywords", "total_jobs" ] }, "SeekJobResponse": { "type": "object", "nullable": true, "properties": { "job_id": { "type": "string", "example": "94059954" }, "url": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true, "example": "Founding Engineer" }, "status": { "type": "string", "nullable": true, "example": "Active" }, "is_expired": { "type": "boolean", "nullable": true }, "is_verified": { "type": "boolean", "nullable": true }, "is_link_out": { "type": "boolean", "nullable": true, "description": "Whether the application hands off to the employer's own site rather than Seek's." }, "abstract": { "type": "string", "nullable": true, "description": "The one-line pitch — not the full posting." }, "description_html": { "type": "string", "nullable": true, "description": "The whole posting, as the employer wrote it, HTML markup included." }, "listed_at": { "type": "string", "nullable": true, "example": "2026-08-18T21:50:30.957Z" }, "listed_at_display": { "type": "string", "nullable": true, "example": "15d ago" }, "expires_at": { "type": "string", "nullable": true }, "location_label": { "type": "string", "nullable": true, "example": "Sydney NSW" }, "structured_location": { "$ref": "#/components/schemas/SeekJobStructuredLocation" }, "salary_label": { "type": "string", "nullable": true, "example": "$12,000 – $17,000 per month", "description": "Seek's own free-text label, kept verbatim, same caveat as the search tier's." }, "work_types_label": { "type": "string", "nullable": true, "example": "Full time" }, "work_types": { "type": "array", "items": { "type": "string" }, "example": [ "FULL_TIME" ], "description": "The structured taxonomy codes behind `work_types_label`." }, "advertiser": { "$ref": "#/components/schemas/SeekJobAdvertiser" }, "classifications": { "type": "array", "items": { "type": "string" }, "example": [ "Engineering - Software (Information & Communication Technology)" ] }, "contact_matches": { "type": "array", "items": { "$ref": "#/components/schemas/SeekJobContactMatch" }, "description": "Direct contact details the employer embedded in the posting, when any." }, "phone_number": { "type": "string", "nullable": true }, "share_link": { "type": "string", "nullable": true }, "branding": { "$ref": "#/components/schemas/SeekJobBranding" } }, "required": [ "job_id", "url", "title", "status", "is_expired", "is_verified", "is_link_out", "abstract", "description_html", "listed_at", "listed_at_display", "expires_at", "location_label", "structured_location", "salary_label", "work_types_label", "work_types", "advertiser", "classifications", "contact_matches", "phone_number", "share_link", "branding" ] }, "SeekJobStructuredLocation": { "type": "object", "nullable": true, "properties": { "country": { "type": "string", "nullable": true, "example": "Australia" }, "country_code": { "type": "string", "nullable": true, "example": "AU" }, "suburb": { "type": "string", "nullable": true, "example": "Sydney" }, "region": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true, "example": "New South Wales" }, "postcode": { "type": "string", "nullable": true, "example": "2000" } }, "required": [ "country", "country_code", "suburb", "region", "state", "postcode" ] }, "SeekJobAdvertiser": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "Visaible" }, "is_verified": { "type": "boolean", "nullable": true }, "registered_at": { "type": "string", "nullable": true } }, "required": [ "id", "name", "is_verified", "registered_at" ] }, "SeekJobContactMatch": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "example": "Email" }, "value": { "type": "string", "nullable": true } }, "required": [ "type", "value" ] }, "SeekJobBranding": { "type": "object", "nullable": true, "properties": { "logo_url": { "type": "string", "nullable": true }, "cover_url": { "type": "string", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true }, "bullets": { "type": "array", "items": { "type": "string" } }, "questionnaire_questions": { "type": "array", "items": { "type": "string" }, "description": "Screening questions the employer attached to the application, when any." }, "video_url": { "type": "string", "nullable": true } }, "required": [ "logo_url", "cover_url", "thumbnail_url", "bullets", "questionnaire_questions", "video_url" ], "description": "Null for a plain-text listing with no employer branding package." }, "SeekCompanyResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "cisco-systems-432649" }, "url": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true, "description": "Seek's own numeric company id — the trailing digits of `slug`." }, "name": { "type": "string", "nullable": true, "example": "CommBank" }, "canonical_url": { "type": "string", "nullable": true }, "is_claimed": { "type": "boolean", "nullable": true }, "branding": { "$ref": "#/components/schemas/SeekCompanyBranding" }, "overview": { "$ref": "#/components/schemas/SeekCompanyOverview" }, "mission_statement": { "type": "array", "items": { "type": "string" } }, "custom_statement": { "$ref": "#/components/schemas/SeekCompanyStatement" }, "culture_and_values": { "$ref": "#/components/schemas/SeekCompanyCulture" }, "featured": { "$ref": "#/components/schemas/SeekCompanyFeatured" }, "perks_and_benefits": { "type": "array", "items": { "$ref": "#/components/schemas/SeekCompanyPerk" } }, "awards": { "type": "array", "items": { "$ref": "#/components/schemas/SeekCompanyAward" } }, "review_rating": { "$ref": "#/components/schemas/SeekCompanyReviewRating" } }, "required": [ "slug", "url", "id", "name", "canonical_url", "is_claimed", "branding", "overview", "mission_statement", "custom_statement", "culture_and_values", "featured", "perks_and_benefits", "awards", "review_rating" ] }, "SeekCompanyBranding": { "type": "object", "nullable": true, "properties": { "logo_url": { "type": "string", "nullable": true }, "cover_url": { "type": "string", "nullable": true } }, "required": [ "logo_url", "cover_url" ] }, "SeekCompanyOverview": { "type": "object", "nullable": true, "properties": { "website_url": { "type": "string", "nullable": true, "example": "https://www.commbank.com.au" }, "website_display_name": { "type": "string", "nullable": true, "example": "CommBank" }, "size": { "type": "string", "nullable": true, "example": "More than 10,000" }, "industry": { "type": "string", "nullable": true, "example": "Banking & Credit" }, "primary_location": { "type": "string", "nullable": true, "example": "Sydney, NSW" }, "specialities": { "type": "array", "items": { "type": "string" }, "example": [ "Banking", "Financial Services" ] }, "description": { "type": "array", "items": { "type": "string" }, "description": "The company's own about-us copy, one paragraph per entry." } }, "required": [ "website_url", "website_display_name", "size", "industry", "primary_location", "specialities", "description" ] }, "SeekCompanyStatement": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "description" ] }, "SeekCompanyCulture": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/SeekCompanyValue" } } }, "required": [ "title", "description", "image_url", "values" ] }, "SeekCompanyValue": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "title", "description" ] }, "SeekCompanyFeatured": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": "string", "nullable": true }, "video_url": { "type": "string", "nullable": true } }, "required": [ "title", "description", "image_url", "video_url" ] }, "SeekCompanyPerk": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "title", "description" ] }, "SeekCompanyAward": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "year": { "type": "number", "nullable": true }, "image_url": { "type": "string", "nullable": true } }, "required": [ "name", "year", "image_url" ] }, "SeekCompanyReviewRating": { "type": "object", "nullable": true, "properties": { "overall": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "perks_and_benefits": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "career_opportunity": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "diversity": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "executive_management": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "work_life_balance": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "work_environment": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "rating_1_star": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "rating_2_star": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "rating_3_star": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "rating_4_star": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "rating_5_star": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "recommended": { "allOf": [ { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, { "description": "Share of reviewers who would recommend the employer, as a `percentage`." } ] }, "salary_poor": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "salary_fair": { "$ref": "#/components/schemas/SeekReviewRatingMetric" }, "salary_generous": { "$ref": "#/components/schemas/SeekReviewRatingMetric" } }, "required": [ "overall", "perks_and_benefits", "career_opportunity", "diversity", "executive_management", "work_life_balance", "work_environment", "rating_1_star", "rating_2_star", "rating_3_star", "rating_4_star", "rating_5_star", "recommended", "salary_poor", "salary_fair", "salary_generous" ], "description": "Null when the company has too few reviews for Seek to publish one." }, "SeekReviewRatingMetric": { "type": "object", "nullable": true, "properties": { "rating": { "type": "number", "nullable": true, "description": "1-5 average. Null on a metric Seek reports only as a percentage." }, "percentage": { "type": "number", "nullable": true, "description": "0-100. Null on a metric Seek reports only as a rating." }, "count": { "type": "number", "nullable": true, "description": "Responses the figure rests on." } }, "required": [ "rating", "percentage", "count" ] }, "ZiprecruiterSearchResponse": { "type": "object", "nullable": true, "properties": { "location": { "type": "string", "nullable": true }, "page": { "type": "integer" }, "url": { "type": "string", "nullable": true, "description": "The search page actually fetched. Null on the rare render with no results section at all." }, "total_listings": { "type": "number", "nullable": true, "description": "Advertised number of listings. This may exceed the number available in `results`; use `count` for the returned row count." }, "count": { "type": "number", "description": "Number of rows in `results`." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ZiprecruiterJobResult" } }, "has_more": { "type": "boolean" }, "stop_reason": { "type": "string", "nullable": true, "example": "no_results_blob", "description": "Set only when `results` is empty: the page rendered but carried no results section." } }, "required": [ "location", "page", "url", "total_listings", "count", "results", "has_more", "stop_reason" ] }, "ZiprecruiterJobResult": { "type": "object", "properties": { "job_id": { "type": "string", "example": "sa0o0DJBHcxh_je9EJAcYQ", "description": "ZipRecruiter's own `listingKey` for the row." }, "title": { "type": "string", "nullable": true, "example": "LPN - Private Duty Nursing - Peds Vent" }, "short_description": { "type": "string", "nullable": true, "description": "A truncated lead-in to the full posting, not the whole text." }, "is_active": { "type": "boolean", "nullable": true }, "posted_at": { "type": "string", "nullable": true, "example": "2026-08-26T06:18:02Z" }, "posted_label": { "type": "string", "nullable": true, "example": "8 days ago", "description": "ZipRecruiter's own relative phrasing, as shown on the card." }, "updated_at": { "type": "string", "nullable": true }, "pay": { "$ref": "#/components/schemas/ZiprecruiterJobPay" }, "pay_label": { "type": "string", "nullable": true, "example": "$$30/hr", "description": "ZipRecruiter's own display string, when it renders one." }, "benefits": { "type": "array", "items": { "type": "string" }, "example": [ "BENEFIT_TYPE_NAME_MEDICAL", "BENEFIT_TYPE_NAME_DENTAL" ], "description": "ZipRecruiter's own enum values, kept verbatim." }, "employment_types": { "type": "array", "items": { "type": "string" }, "example": [ "EMPLOYMENT_TYPE_NAME_FULL_TIME" ] }, "location_types": { "type": "array", "items": { "type": "string" }, "example": [ "LOCATION_TYPE_NAME_IN_PERSON" ] }, "company": { "$ref": "#/components/schemas/ZiprecruiterJobCompany" }, "company_url": { "type": "string", "nullable": true, "example": "/co/Maxim-Healthcare-Services/Jobs", "description": "Employer path. Remove the `/co/` prefix and `/Jobs` suffix to obtain the `company` input for the company-jobs endpoint." }, "company_logo_url": { "type": "string", "nullable": true }, "location": { "$ref": "#/components/schemas/ZiprecruiterJobLocation" }, "apply_url": { "type": "string", "nullable": true, "description": "ZipRecruiter's own outbound apply redirect for the row." }, "canonical_url": { "type": "string", "nullable": true, "description": "ZipRecruiter's own relative URL for the row's job page." } }, "required": [ "job_id", "title", "short_description", "is_active", "posted_at", "posted_label", "updated_at", "pay", "pay_label", "benefits", "employment_types", "location_types", "company", "company_url", "company_logo_url", "location", "apply_url", "canonical_url" ] }, "ZiprecruiterJobPay": { "type": "object", "nullable": true, "properties": { "interval": { "type": "string", "nullable": true, "example": "PAY_INTERVAL_HOUR", "description": "ZipRecruiter's own enum, kept verbatim." }, "currency": { "type": "string", "nullable": true, "example": "PAY_CURRENCY_USD" }, "min": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true }, "min_annual": { "type": "number", "nullable": true, "description": "ZipRecruiter's own annualized estimate of `min`." }, "max_annual": { "type": "number", "nullable": true } }, "required": [ "interval", "currency", "min", "max", "min_annual", "max_annual" ], "description": "Null when ZipRecruiter's own record carries no pay figures at all — some rows carry only `currency` with no `min`/`max`." }, "ZiprecruiterJobCompany": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "Maxim Healthcare Services" } }, "required": [ "id", "name" ] }, "ZiprecruiterJobLocation": { "type": "object", "nullable": true, "properties": { "city": { "type": "string", "nullable": true, "example": "Miami" }, "state": { "type": "string", "nullable": true, "example": "Florida" }, "state_code": { "type": "string", "nullable": true, "example": "FL" }, "county": { "type": "string", "nullable": true, "example": "Miami-Dade" }, "postal_code": { "type": "string", "nullable": true, "example": "33176" }, "country": { "type": "string", "nullable": true, "example": "United States" }, "display_name": { "type": "string", "nullable": true, "example": "Miami, FL US 33176" } }, "required": [ "city", "state", "state_code", "county", "postal_code", "country", "display_name" ] }, "ZiprecruiterCompanyResponse": { "type": "object", "nullable": true, "properties": { "company": { "type": "string", "example": "Maxim-Healthcare-Services" }, "city": { "type": "string", "example": "Miami" }, "state": { "type": "string", "example": "FL" }, "url": { "type": "string", "nullable": true }, "total_listings": { "type": "number", "nullable": true }, "count": { "type": "number", "description": "Number of rows in `results`." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ZiprecruiterJobResult" } } }, "required": [ "company", "city", "state", "url", "total_listings", "count", "results" ] }, "GlassdoorJobsResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string", "nullable": true, "example": "software engineer" }, "loc_id": { "type": "number", "nullable": true, "example": 1147401, "description": "The location id the search ran against, echoed back." }, "count": { "type": "number", "example": 62, "description": "How many rows are in `jobs`. Counted from what you received, not copied from any figure Glassdoor prints on the page — its own headline (\"2,916 software engineer Jobs in San Francisco\") is a claim about its index, not about this response, and is not published here as a total." }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/GlassdoorJob" } } }, "required": [ "query", "loc_id", "count", "jobs" ] }, "GlassdoorJob": { "type": "object", "properties": { "title": { "type": "string", "example": "Senior Software Engineer", "description": "The posting's title (`jobTitleText`)." }, "normalized_title": { "type": "string", "nullable": true, "example": "software engineer", "description": "Glassdoor's own normalisation of the title (`normalizedJobTitle`) — the field it groups roles by, and the one to aggregate on rather than `title`." }, "occupations": { "type": "array", "items": { "type": "string" }, "example": [ "Software Engineer" ], "description": "Glassdoor's occupation tags for the row, flattened out of its nested `occupations` form." }, "occupation_group": { "type": "string", "nullable": true, "description": "Glassdoor's group-of-occupations label (`goc`) — a coarser bucket than `occupations`, and what its own faceting uses." }, "occupation_group_id": { "type": "string", "nullable": true }, "employer": { "$ref": "#/components/schemas/GlassdoorJobEmployer" }, "location": { "$ref": "#/components/schemas/GlassdoorJobLocation" }, "pay": { "$ref": "#/components/schemas/GlassdoorJobPay" }, "age_in_days": { "type": "number", "nullable": true, "example": 3, "description": "How long ago Glassdoor first saw the posting (`ageInDays`). `0` means today, so treat it as a number and not as a missing value." }, "easy_apply": { "type": "boolean", "nullable": true, "description": "Whether the posting can be applied to on Glassdoor itself." }, "expired": { "type": "boolean", "nullable": true }, "job_url": { "type": "string", "nullable": true, "example": "https://www.glassdoor.com/partner/jobListing.htm?jobListingId=1009292918313", "description": "Absolute URL of the posting on Glassdoor." }, "job_listing_id": { "type": "string", "nullable": true, "example": "1009292918313", "description": "Glassdoor's listing id, lifted from the `jobListingId=` parameter on the job link when the link carries one. It is the stable identity of the posting and the right key to de-duplicate on across searches." }, "is_sponsored_job": { "type": "boolean", "nullable": true, "example": true, "description": "Whether *this posting* was paid for (`isSponsoredJob`). Distinct from `is_sponsored_employer` below, and Glassdoor tracks the two separately." }, "is_sponsored_employer": { "type": "boolean", "nullable": true, "description": "Whether the *employer* is buying visibility on this query (`isSponsoredEmployer`), independently of whether this specific posting is a paid placement." }, "ad_order_id": { "type": "string", "nullable": true, "description": "Glassdoor's `adOrderId` for a paid placement — the advertising order the row was served under. Null on organic rows, which makes it the cleanest paid/organic split on this surface." }, "has_employer_spotlight": { "type": "boolean", "nullable": true, "description": "Whether the row carries Glassdoor's branded employer-spotlight treatment (`employerSpotlight`), which is bought separately again." } }, "required": [ "title", "normalized_title", "occupations", "occupation_group", "occupation_group_id", "employer", "location", "pay", "age_in_days", "easy_apply", "expired", "job_url", "job_listing_id", "is_sponsored_job", "is_sponsored_employer", "ad_order_id", "has_employer_spotlight" ] }, "GlassdoorJobEmployer": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "671932", "description": "Glassdoor's employer id, published as a string because it arrives as a number on some rows and a string on others. Pass it to `/glassdoor/overview` or `/glassdoor/reviews` — with the slug — for the employer's own tiers." }, "name": { "type": "string", "nullable": true, "example": "Stripe" }, "short_name": { "type": "string", "nullable": true, "description": "Glassdoor's abbreviated display name for the employer, when it has one that differs from `name`." }, "rating": { "type": "number", "nullable": true, "example": 3.9, "description": "The employer's overall 1-5 rating as carried on the search row. Null when the row does not state one — `/glassdoor/overview` is the authoritative source for it." }, "logo_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "short_name", "rating", "logo_url" ] }, "GlassdoorJobLocation": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "type": { "type": "string", "nullable": true, "example": "C", "description": "Glassdoor's `locationType` for the row — its `locT` codes." }, "loc_id": { "type": "number", "nullable": true, "example": 1147401, "description": "**The row's own Glassdoor location id.** This is the one reliable way to discover a `loc_id` for a place: run a search you already have an id for, and read the ids off the rows that come back." }, "country_id": { "type": "number", "nullable": true } }, "required": [ "name", "type", "loc_id", "country_id" ] }, "GlassdoorJobPay": { "type": "object", "nullable": true, "properties": { "p10": { "type": "number", "nullable": true, "example": 145000, "description": "10th percentile of the distribution for this listing." }, "p50": { "type": "number", "nullable": true, "example": 187000, "description": "Median." }, "p90": { "type": "number", "nullable": true, "example": 240000, "description": "90th percentile." }, "period": { "type": "string", "nullable": true, "example": "ANNUAL", "description": "The period the amounts are quoted over (`payPeriod`). Without it the numbers are not comparable between rows." }, "currency": { "type": "string", "nullable": true, "example": "USD" }, "source": { "type": "string", "nullable": true, "example": "EMPLOYER_ESTIMATED_SALARY", "description": "Where the figures came from — whether the employer stated the pay or Glassdoor estimated it. Glassdoor's own vocabulary, forwarded as-is, and worth reading before comparing two rows." } }, "required": [ "p10", "p50", "p90", "period", "currency", "source" ], "description": "**A salary distribution attached to this individual listing** (`payPeriodAdjustedPay`), not a range parsed out of the advert text. Null when the row carries no pay data at all." }, "GlassdoorReviewsResponse": { "type": "object", "nullable": true, "properties": { "employer_id": { "type": "string", "nullable": true, "example": "671932" }, "slug": { "type": "string", "nullable": true, "example": "Stripe" }, "count": { "type": "number", "example": 3, "description": "Number of reviews in `reviews`. Read `coverage` before comparing it with the employer's total review count." }, "coverage": { "type": "string", "example": "page one only: Glassdoor answers 401 'Authenticating' for _P2 and beyond without an account", "description": "Explains that `reviews` contains the first public page and cannot be paginated by this endpoint." }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/GlassdoorReview" } } }, "required": [ "employer_id", "slug", "count", "coverage", "reviews" ] }, "GlassdoorReview": { "type": "object", "properties": { "review_id": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true, "example": "Great people, fast pace", "description": "The review's headline." }, "pros": { "type": "string", "nullable": true }, "cons": { "type": "string", "nullable": true }, "advice": { "type": "string", "nullable": true, "description": "Advice to management. Optional on Glassdoor's own form, so null is common even on a complete review." }, "ratings": { "$ref": "#/components/schemas/GlassdoorReviewRatings" }, "sentiment": { "$ref": "#/components/schemas/GlassdoorReviewSentiment" }, "reviewer": { "$ref": "#/components/schemas/GlassdoorReviewer" }, "reviewed_at": { "type": "string", "nullable": true, "example": "2026-03-11T09:22:34.000Z", "description": "When the review was posted, in ISO 8601." }, "reviewed_at_raw": { "type": "string", "nullable": true, "description": "Glassdoor's own `reviewDateTime` string, kept alongside the parsed value so nothing is lost if our reading of its format is ever wrong." }, "helpful_count": { "type": "number", "nullable": true, "description": "`countHelpful`." }, "not_helpful_count": { "type": "number", "nullable": true, "description": "`countNotHelpful`." }, "featured": { "type": "boolean", "nullable": true, "description": "Whether Glassdoor is promoting this review on the employer's page. A featured review is not a random sample of opinion." }, "employer_responses": { "type": "array", "items": { "$ref": "#/components/schemas/GlassdoorEmployerResponse" }, "description": "The employer's public replies, if any. Empty array when there are none — never null." } }, "required": [ "review_id", "summary", "pros", "cons", "advice", "ratings", "sentiment", "reviewer", "reviewed_at", "reviewed_at_raw", "helpful_count", "not_helpful_count", "featured", "employer_responses" ] }, "GlassdoorReviewRatings": { "type": "object", "properties": { "overall": { "type": "number", "nullable": true, "example": 4, "description": "`ratingOverall`, 1-5." }, "career_opportunities": { "type": "number", "nullable": true, "description": "`ratingCareerOpportunities`, 1-5." }, "compensation_and_benefits": { "type": "number", "nullable": true, "description": "`ratingCompensationAndBenefits`, 1-5." }, "culture_and_values": { "type": "number", "nullable": true, "description": "`ratingCultureAndValues`, 1-5." }, "diversity_and_inclusion": { "type": "number", "nullable": true, "description": "`ratingDiversityAndInclusion`, 1-5." }, "senior_leadership": { "type": "number", "nullable": true, "description": "`ratingSeniorLeadership`, 1-5." }, "work_life_balance": { "type": "number", "nullable": true, "description": "`ratingWorkLifeBalance`, 1-5." } }, "required": [ "overall", "career_opportunities", "compensation_and_benefits", "culture_and_values", "diversity_and_inclusion", "senior_leadership", "work_life_balance" ], "description": "The seven 1-5 star dimensions. Deliberately not averaged: the whole value of this surface is that pay, culture, leadership and career growth are scored separately, and a single number throws that away." }, "GlassdoorReviewSentiment": { "type": "object", "properties": { "business_outlook": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": "POSITIVE", "description": "`ratingBusinessOutlook` — whether the reviewer expects the business to improve." }, "ceo_approval": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": "APPROVE", "description": "`ratingCeo` — whether the reviewer approves of the CEO." }, "recommend_to_friend": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": "POSITIVE", "description": "`ratingRecommendToFriend` — whether the reviewer would recommend working here." } }, "required": [ "business_outlook", "ceo_approval", "recommend_to_friend" ], "description": "The three approval dimensions, which are Glassdoor's own vocabulary rather than a score — so they are kept apart from `ratings` instead of being coerced into the same scale." }, "GlassdoorReviewer": { "type": "object", "properties": { "job_title": { "type": "string", "nullable": true, "example": "Software Engineer" }, "employment_status": { "type": "string", "nullable": true, "example": "REGULAR", "description": "Glassdoor's `employmentStatus` vocabulary — full-time, part-time, contract, intern. Forwarded as-is." }, "is_current_employee": { "type": "boolean", "nullable": true, "description": "`isCurrentJob`. A former employee's review and a current one's are not the same evidence, and Glassdoor labels them separately." }, "length_of_employment_years": { "type": "number", "nullable": true, "example": 2, "description": "`lengthOfEmployment`, in years." }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA", "description": "Where the reviewer worked. Flattened from Glassdoor's location object to its display name." } }, "required": [ "job_title", "employment_status", "is_current_employee", "length_of_employment_years", "location" ] }, "GlassdoorEmployerResponse": { "type": "object", "properties": { "text": { "type": "string", "nullable": true, "description": "The employer's reply to the review, as written." }, "responded_at": { "type": "string", "nullable": true, "example": "2026-03-11T09:22:34.000Z", "description": "When the employer replied, in ISO 8601." }, "author_title": { "type": "string", "nullable": true, "description": "The job title the responder signed with, when stated." } }, "required": [ "text", "responded_at", "author_title" ] }, "GlassdoorOverviewResponse": { "type": "object", "nullable": true, "properties": { "employer_id": { "type": "string", "nullable": true, "example": "671932" }, "slug": { "type": "string", "nullable": true, "example": "Stripe" }, "rating": { "$ref": "#/components/schemas/GlassdoorAggregateRating" }, "profile": { "$ref": "#/components/schemas/GlassdoorEmployerProfile" }, "ratings": { "$ref": "#/components/schemas/GlassdoorEmployerRatings" } }, "required": [ "employer_id", "slug", "rating", "profile", "ratings" ] }, "GlassdoorAggregateRating": { "type": "object", "nullable": true, "properties": { "value": { "type": "number", "nullable": true, "example": 3.7, "description": "The employer's overall rating, 1-5." }, "count": { "type": "number", "nullable": true, "example": 1361, "description": "Number of reviews used for the employer's aggregate rating. This can exceed the reviews returned by `/glassdoor/reviews`." }, "best": { "type": "number", "nullable": true, "example": 5 }, "worst": { "type": "number", "nullable": true, "example": 1 } }, "required": [ "value", "count", "best", "worst" ], "description": "Employer-wide aggregate rating and review count. Null when the page does not publish the aggregate." }, "GlassdoorEmployerProfile": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Stripe" }, "short_name": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true, "example": "www.stripe.com" }, "headquarters": { "type": "string", "nullable": true, "example": "South San Francisco, CA" }, "size": { "type": "string", "nullable": true, "example": "1001 to 5000 Employees", "description": "Glassdoor's employee-count band, as it renders it." }, "type": { "type": "string", "nullable": true, "example": "Company - Private", "description": "Public, private, subsidiary, non-profit — Glassdoor's own label." }, "revenue": { "type": "string", "nullable": true, "description": "Glassdoor's revenue band, as it renders it." }, "founded_year": { "type": "number", "nullable": true, "example": 2010 }, "industry": { "type": "string", "nullable": true, "example": "Financial Transaction Processing" }, "sector": { "type": "string", "nullable": true, "example": "Financial Services" }, "description": { "type": "string", "nullable": true, "description": "The employer's own description of itself." }, "mission": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "nullable": true }, "ceo_name": { "type": "string", "nullable": true, "example": "Patrick Collison" } }, "required": [ "name", "short_name", "website", "headquarters", "size", "type", "revenue", "founded_year", "industry", "sector", "description", "mission", "logo_url", "ceo_name" ], "description": "Employer facts. Individual fields may be null; a missing overview page returns `data: null`." }, "GlassdoorEmployerRatings": { "type": "object", "properties": { "overall": { "type": "number", "nullable": true }, "career_opportunities": { "type": "number", "nullable": true }, "compensation_and_benefits": { "type": "number", "nullable": true }, "culture_and_values": { "type": "number", "nullable": true }, "diversity_and_inclusion": { "type": "number", "nullable": true }, "senior_leadership": { "type": "number", "nullable": true }, "work_life_balance": { "type": "number", "nullable": true }, "recommend_to_friend_percent": { "type": "number", "nullable": true, "description": "Share of reviewers who would recommend the employer to a friend, as Glassdoor states it (a percentage, 0-100)." }, "ceo_approval_percent": { "type": "number", "nullable": true, "description": "Share of reviewers who approve of the CEO, 0-100." }, "business_outlook_percent": { "type": "number", "nullable": true, "description": "Share of reviewers with a positive six-month business outlook, 0-100." }, "review_count": { "type": "number", "nullable": true, "description": "Employer review count from the page state. Prefer `rating.count` when both values are present." } }, "required": [ "overall", "career_opportunities", "compensation_and_benefits", "culture_and_values", "diversity_and_inclusion", "senior_leadership", "work_life_balance", "recommend_to_friend_percent", "ceo_approval_percent", "business_outlook_percent", "review_count" ], "description": "The employer-wide equivalent of a review's rating vector, when the page state carries it. Same nullability caveat as `profile`." }, "GlassdoorSalariesResponse": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "nullable": true, "example": "software-engineer" }, "count": { "type": "number", "example": 5, "description": "How many distributions are in `pay`." }, "pay": { "type": "array", "items": { "$ref": "#/components/schemas/GlassdoorPayDistribution" } } }, "required": [ "title", "count", "pay" ] }, "GlassdoorPayDistribution": { "type": "object", "properties": { "job_title": { "type": "string", "nullable": true, "example": "Software Engineer" }, "employer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "Stripe" } }, "required": [ "id", "name" ], "description": "**The employer the distribution belongs to, when it belongs to one.** This is where Glassdoor's salary tier beats Indeed's: pay attached to a named company rather than only to a title. Null on the title-level aggregate rows." }, "currency": { "type": "string", "nullable": true, "example": "USD" }, "pay_period": { "type": "string", "nullable": true, "example": "ANNUAL", "description": "The period every amount on this row is quoted over. Read it before comparing rows — an hourly row and an annual one are both plain numbers here." }, "median_total_pay": { "type": "number", "nullable": true, "example": 187000, "description": "`totalPayStatistics.totalPayMedian`." }, "base_pay": { "type": "number", "nullable": true, "description": "The base component (`basePayAmount`), i.e. total pay minus the additional pay below." }, "additional_pay": { "type": "number", "nullable": true, "description": "Bonus, equity and the rest (`totalAdditionalPayAmount`). Splitting it from base is the thing most salary sources cannot do." }, "estimated_range": { "$ref": "#/components/schemas/GlassdoorPayRange" }, "percentiles": { "type": "array", "items": { "$ref": "#/components/schemas/GlassdoorPercentile" }, "description": "The distribution as Glassdoor published it, in its own order. Empty when the row carries no percentile breakdown." }, "p10": { "type": "number", "nullable": true, "description": "Convenience view of `percentiles`, matched on Glassdoor's own label. Null when the row's percentiles are unlabelled — this API will not guess which unlabelled number is which percentile." }, "p50": { "type": "number", "nullable": true }, "p90": { "type": "number", "nullable": true }, "annual_pay": { "type": "number", "nullable": true, "description": "The same pay expressed annually, when Glassdoor states it (`annualPay`)." }, "monthly_pay": { "type": "number", "nullable": true }, "hourly_pay": { "type": "number", "nullable": true } }, "required": [ "job_title", "employer", "currency", "pay_period", "median_total_pay", "base_pay", "additional_pay", "estimated_range", "percentiles", "p10", "p50", "p90", "annual_pay", "monthly_pay", "hourly_pay" ] }, "GlassdoorPayRange": { "type": "object", "nullable": true, "properties": { "min": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true } }, "required": [ "min", "max" ], "description": "Glassdoor's `estimatedPayRange`, when it states one." }, "GlassdoorPercentile": { "type": "object", "properties": { "label": { "type": "string", "nullable": true, "example": "P50", "description": "Glassdoor's own name for the percentile. Null when it published the value without one, in which case the array order is all there is." }, "value": { "type": "number", "nullable": true, "example": 187000 } }, "required": [ "label", "value" ] }, "YelpBusinessResponse": { "type": "object", "nullable": true, "properties": { "alias": { "type": "string", "nullable": true, "example": "tartine-bakery-san-francisco", "description": "The slug that was fetched, echoed back." }, "url": { "type": "string", "nullable": true, "example": "https://www.yelp.com/biz/tartine-bakery-san-francisco", "description": "The business's page on Yelp, built from `alias`." }, "name": { "type": "string", "example": "Tartine Bakery", "description": "The business name, from the page's `

`. This is the anchor everything else on the page is positioned against, so it is the one non-nullable field here: a page that is a business but carries no name means Yelp moved something, and that is reported as an error rather than as a business with eleven nulls.\n\nYelp redirects aliases freely, so this — not your `alias` — is the authority on which business you actually got." }, "rating": { "type": "number", "nullable": true, "example": 4.3, "description": "The star rating Yelp prints on the page, 1-5." }, "review_count_display": { "type": "string", "nullable": true, "example": "9.2k", "description": "A string, and an abbreviated one — literally \"9.2k\". Yelp prints the review count only in abbreviated form to a logged-out client, and publishes the exact figure nowhere on the page, so this is the raw label and not a number.\n\nIt is deliberately not parsed: expanding \"9.2k\" to 9200 would invent three digits of precision the site never gave, and a caller aggregating those would be summing noise. Parse it yourself if an approximation is useful to you — but do it knowingly." }, "phone": { "type": "string", "nullable": true, "example": "(415) 487-2600" }, "price_range": { "type": "string", "nullable": true, "example": "$$", "description": "Yelp's price band, as it renders it: `$` to `$$$$`." }, "categories": { "type": "array", "items": { "type": "string" }, "example": [ "Bakeries", "Desserts", "Cafes" ], "description": "The business's own Yelp categories. Empty array when the page lists none — never null." }, "address": { "$ref": "#/components/schemas/YelpPostalAddress" }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/YelpPhoto" }, "description": "Business photos from the page's schema.org `ItemList`, capped at 30 by the worker. Empty array when the page ships none." }, "reviews": { "nullable": true, "description": "Always `null`, and it is not a bug. See `reviews_note`. The field exists rather than being omitted so that the answer to \"where are the reviews\" is in the payload rather than only in these docs." }, "reviews_note": { "type": "string", "example": "Yelp renders its review list client-side; a server-fetched page carries only loading placeholders. Reviews are not available on this tier.", "description": "Why `reviews` is null, stated in the response body. Yelp renders its review list client-side: a server-fetched page carries `reviews-shimmer-` loading placeholders and no review prose at all. Measured on one business, same URL and same moment, browser versus HTTP client — name, rating, address, phone, hours, categories and ld+json reach both; review text reaches neither without rendering the page. No parameter on this endpoint can change that." } }, "required": [ "alias", "url", "name", "rating", "review_count_display", "phone", "price_range", "categories", "address", "photos", "reviews", "reviews_note" ] }, "YelpPostalAddress": { "type": "object", "nullable": true, "properties": { "street_address": { "type": "string", "nullable": true, "example": "600 Guerrero St" }, "locality": { "type": "string", "nullable": true, "example": "San Francisco", "description": "City — schema.org `addressLocality`." }, "region": { "type": "string", "nullable": true, "example": "CA", "description": "State or province — schema.org `addressRegion`." }, "postal_code": { "type": "string", "nullable": true, "example": "94110" }, "country": { "type": "string", "nullable": true, "example": "US" } }, "required": [ "street_address", "locality", "region", "postal_code", "country" ], "description": "The structured address, from the `PostalAddress` Yelp attaches to each photo in its schema.org `ItemList`. An odd home for it and the only one available — Yelp publishes no `LocalBusiness` block — but a structured address beats a street line scraped out of the markup. Null when the page carries no photo list." }, "YelpPhoto": { "type": "object", "properties": { "url": { "type": "string", "nullable": true, "example": "https://s3-media0.fl.yelpcdn.com/bphoto/AbCdEf/o.jpg", "description": "Full-size image (`contentUrl`)." }, "thumbnail_url": { "type": "string", "nullable": true }, "caption": { "type": "string", "nullable": true }, "uploaded_at": { "type": "string", "nullable": true, "example": "2024-05-14T00:00:00.000Z", "description": "When the photo was uploaded, in ISO 8601. Null when Yelp published no date or one we could not read — `uploaded_at_raw` keeps whatever it actually said." }, "uploaded_at_raw": { "type": "string", "nullable": true, "example": "2024-05-14", "description": "Yelp's own `uploadDate` string, kept alongside the parsed value so nothing is lost if our reading of its format is ever wrong." }, "author": { "type": "string", "nullable": true, "description": "The Yelp user who uploaded it, when the block names one." } }, "required": [ "url", "thumbnail_url", "caption", "uploaded_at", "uploaded_at_raw", "author" ] }, "YelpSearchResponse": { "type": "object", "nullable": true, "properties": { "find_desc": { "type": "string", "nullable": true, "example": "coffee" }, "find_loc": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "start": { "type": "number", "nullable": true, "example": 0, "description": "The offset this search ran at, echoed back." }, "pagination": { "$ref": "#/components/schemas/YelpPagination" }, "count": { "type": "number", "example": 12, "description": "How many rows are in this response across every section. Counted from what you received rather than copied from any figure Yelp prints — `pagination.total_results` is its claim about its index and is never used to compute this." }, "organic_count": { "type": "number", "example": 10, "description": "Rows not marked as ads." }, "ad_count": { "type": "number", "example": 2, "description": "Rows marked as ads, by the row's flag or its section's." }, "hydrated_count": { "type": "number", "example": 2, "description": "How many rows carry a `business` object. Expect this to equal `ad_count` and not `count`: Yelp hydrates organic rows client-side and serves that to neither the JSON nor the HTML. The number is here so the gap is measurable at a glance instead of being discovered by iterating." }, "hydration_note": { "type": "string", "example": "Organic rows carry a null searchResultBusiness: Yelp fills that in client-side and serves it to neither the JSON nor the HTML. Use the row's alias with /v1/yelp/business to fetch each business.", "description": "Why most rows have a null `business`, stated in the response body. Organic results carry `searchResultBusiness: null` in both Yelp's JSON and its server-rendered HTML — a property of Yelp, not a gap in the scraper. Each such row still carries `business_id` and `alias`, and the alias is the input to `/v1/yelp/business`." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/YelpSearchSection" }, "description": "Results in Yelp's own grouping. Ads and organic results arrive in separate sections and are published that way rather than merged, so that `is_ad_only` survives; every row also carries its own `is_ad`." } }, "required": [ "find_desc", "find_loc", "start", "pagination", "count", "organic_count", "ad_count", "hydrated_count", "hydration_note", "sections" ] }, "YelpPagination": { "type": "object", "nullable": true, "properties": { "total_results": { "type": "number", "nullable": true, "example": 240, "description": "How many results Yelp claims for the query. A claim about its own index, not a promise that all of them are reachable." }, "results_per_page": { "type": "number", "nullable": true, "example": 10, "description": "Yelp's page size — the step `start` moves in. Ten on every search measured." }, "start_result": { "type": "number", "nullable": true, "example": 0, "description": "The offset this response starts at, as Yelp reports it." } }, "required": [ "total_results", "results_per_page", "start_result" ], "description": "Yelp's own pagination block. Null when the response carried none — note that a genuinely empty search still returns one, so its absence means something changed rather than that nothing matched." }, "YelpSearchSection": { "type": "object", "properties": { "component_type": { "type": "string", "nullable": true, "example": "searchResultsFooter", "description": "Yelp's own name for the block of results." }, "is_ad_only": { "type": "boolean", "nullable": true, "example": true, "description": "Yelp's own `isAdOnly` flag for the section. The sections are kept apart rather than flattened into one list precisely so this survives." }, "count": { "type": "number", "example": 10, "description": "How many rows are in this section's `results`." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/YelpSearchResult" } } }, "required": [ "component_type", "is_ad_only", "count", "results" ] }, "YelpSearchResult": { "type": "object", "properties": { "business_id": { "type": "string", "nullable": true, "example": "kHFPKRnQPfBnBMr4XvQKcQ", "description": "Yelp's internal business id (`bizId`), published as a string. Present on unhydrated rows too, which is half of what makes them usable." }, "alias": { "type": "string", "nullable": true, "example": "kissaten-hifi-san-francisco", "description": "The slug to pass to `/v1/yelp/business`, and the other half of what makes an unhydrated row actionable. Taken from the row's own `alias` when Yelp hydrated it, and otherwise parsed out of `businessUrl` — `\"/biz/kissaten-hifi-san-francisco?osq=coffee\"` becomes `\"kissaten-hifi-san-francisco\"`. Null when the link is not a `/biz/` URL at all, which is what an ad redirect looks like." }, "url": { "type": "string", "nullable": true, "example": "https://www.yelp.com/biz/kissaten-hifi-san-francisco?osq=coffee", "description": "The row's link on Yelp, absolutised." }, "is_ad": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the row is a paid placement. Read from the row's own `isAd`; when the row does not say, a section Yelp marks `is_ad_only` settles it as `true`, and anything else is left `null` rather than assumed organic." }, "rank": { "type": "number", "nullable": true, "example": 3, "description": "Yelp's `ranking` for the row within the result set." }, "snippet": { "type": "string", "nullable": true, "description": "The review excerpt Yelp shows under the row, when it ships one. Flattened to text; this is the one field on the row whose upstream shape is not measured, so treat a null as 'not available' rather than as 'no reviews'." }, "is_hydrated": { "type": "boolean", "example": false, "description": "Whether Yelp attached any business data to this row. `false` means `business` is null because Yelp withheld it, not because the row is broken: organic rows are hydrated client-side, so a server-fetched search returns ten of them carrying an id and an alias and nothing else, while ads come filled in. Check this before reading `business`, and see `hydration_note`." }, "business": { "$ref": "#/components/schemas/YelpSearchBusiness" } }, "required": [ "business_id", "alias", "url", "is_ad", "rank", "snippet", "is_hydrated", "business" ] }, "YelpSearchBusiness": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "example": "Kissaten Hi-Fi" }, "alias": { "type": "string", "nullable": true, "example": "kissaten-hifi-san-francisco", "description": "The business's own slug as the row states it. The row-level `alias` is the one to use — it falls back to parsing `businessUrl` when this is absent, which is the usual case." }, "phone": { "type": "string", "nullable": true, "example": "(415) 555-0134" }, "rating": { "type": "number", "nullable": true, "example": 4.5 }, "review_count": { "type": "number", "nullable": true, "example": 312, "description": "An exact count, unlike the business tier's. Yelp's search JSON states `reviewCount` as a number, where a business page gives a logged-out client only an abbreviation (\"9.2k\"). Null when the row states it in a form that is not a number — see `review_count_display`." }, "review_count_display": { "type": "string", "nullable": true, "description": "The review count as a label, populated only when Yelp sent it as a string rather than a number. Present so an abbreviated value is never silently dropped, and never parsed into `review_count`." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/YelpSearchCategory" }, "description": "The row's Yelp categories. Empty array, never null." }, "formatted_address": { "type": "string", "nullable": true, "example": "600 Guerrero St, San Francisco, CA 94110", "description": "Yelp's single-line address for the row (`formattedAddress`). The search tier states it as text rather than as the structured `PostalAddress` the business tier carries." }, "neighborhoods": { "type": "array", "items": { "type": "string" }, "example": [ "Mission District" ] }, "price_range": { "type": "string", "nullable": true, "example": "$$" }, "service_area": { "type": "string", "nullable": true, "description": "Yelp's `serviceArea` for a business that travels to its customers rather than holding a storefront. Flattened to its display name; the field's full shape is not measured, so this is null more often than the underlying data is absent." }, "parent_business": { "type": "string", "nullable": true, "description": "The parent listing's display name where Yelp attaches one (`parentBusiness`) — a chain's franchise pages carry it." }, "alternate_names": { "type": "array", "items": { "type": "string" }, "description": "Other names Yelp holds for the business." }, "service_offerings_count": { "type": "number", "nullable": true, "description": "Yelp's `serviceOfferingsCount` for the row." } }, "required": [ "name", "alias", "phone", "rating", "review_count", "review_count_display", "categories", "formatted_address", "neighborhoods", "price_range", "service_area", "parent_business", "alternate_names", "service_offerings_count" ], "description": "The business data on the row, or `null` when Yelp did not hydrate it — which is the normal outcome for organic results. Use `alias` with `/v1/yelp/business` to fill one in." }, "YelpSearchCategory": { "type": "object", "properties": { "title": { "type": "string", "example": "Coffee & Tea" }, "url": { "type": "string", "nullable": true, "example": "https://www.yelp.com/search?cflt=coffee&find_loc=San+Francisco", "description": "Yelp's own link for the category, absolutised." } }, "required": [ "title", "url" ] }, "TripadvisorListResponse": { "type": "object", "nullable": true, "properties": { "geo_id": { "type": "number", "example": 60713, "description": "The geo you asked for, echoed back." }, "location_slug": { "type": "string", "example": "San_Francisco_California" }, "kind": { "type": "string", "enum": [ "hotels", "restaurants", "attractions" ], "example": "hotels" }, "offset": { "type": "number", "example": 0, "description": "The offset this page was read at, echoed back." }, "page_size": { "type": "number", "example": 30, "description": "TripAdvisor's page size — the step `offset` moves in. Thirty on every list page measured." }, "next_offset": { "type": "number", "nullable": true, "example": 30, "description": "The offset to ask for next, or `null` when this page was not full. Derived from row count, since TripAdvisor publishes no total: a full page suggests a next one exists but does not guarantee it, while `null` reliably means there is no more." }, "count": { "type": "number", "example": 30, "description": "How many rows are in this response. Counted from what you received, never copied from a figure TripAdvisor printed." }, "item_list_order": { "type": "string", "nullable": true, "example": "Descending", "description": "TripAdvisor's own `itemListOrder` for the page, when it states one. The site's default sort is its ranking, which is not a public formula — treat this as a label, not a sort key you could reproduce." }, "coverage": { "type": "string", "nullable": true, "example": "TripAdvisor publishes attractions as TouristAttraction, which carries only name and coordinates — no rating, review count, address or location id. Hotels and restaurants carry all of them.", "description": "States why rows are thin, when they are. Populated for `kind=attractions`, whose rows carry name and coordinates only; null for hotels and restaurants, which carry everything." }, "breadcrumbs": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/TripadvisorBreadcrumb" }, "description": "TripAdvisor's own breadcrumb trail for the page — the geographic hierarchy it filed this list under. Null when the page carried no `BreadcrumbList`." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TripadvisorListItem" }, "description": "The page's rows, in TripAdvisor's order. Empty array, never null." } }, "required": [ "geo_id", "location_slug", "kind", "offset", "page_size", "next_offset", "count", "item_list_order", "coverage", "breadcrumbs", "results" ] }, "TripadvisorBreadcrumb": { "type": "object", "properties": { "position": { "type": "number", "nullable": true, "example": 1 }, "name": { "type": "string", "nullable": true, "example": "United States" }, "url": { "type": "string", "nullable": true, "description": "The breadcrumb's link on TripAdvisor, absolutised." } }, "required": [ "position", "name", "url" ] }, "TripadvisorListItem": { "type": "object", "properties": { "position": { "type": "number", "nullable": true, "example": 1, "description": "The row's place in TripAdvisor's own ordering for this page, as it states it. Restarts per page, so row one of `offset=30` is position 1, not 31." }, "schema_type": { "type": "string", "nullable": true, "example": "Hotel", "description": "The schema.org type TripAdvisor published the row as — `Hotel`, `Restaurant` or `TouristAttraction`. It is the honest predictor of how much of the rest of this object is populated: a `TouristAttraction` carries a name and coordinates and little else." }, "name": { "type": "string", "nullable": true, "example": "InterContinental Mark Hopkins" }, "url": { "type": "string", "nullable": true, "example": "https://www.tripadvisor.com/HotelHighlight-g60713-d115623-Reviews-InterContinental_Mark_Hopkins-San_Francisco_California.html", "description": "TripAdvisor's own link for the row, absolutised. Note the prefix: hotels are linked from a list page as `HotelHighlight-`, not as the `Hotel_Review-` URL you would reach by clicking through the site." }, "geo_id": { "type": "string", "nullable": true, "example": "60713", "description": "The `g` id in the row's URL, as a string. Usually the geo you asked for, but not always — a hotel listed under one city can carry a neighbouring city's geo." }, "location_id": { "type": "string", "nullable": true, "example": "115623", "description": "The `d` id in the row's URL — TripAdvisor's id for this property, as a string. Not stated anywhere else in the page, so `null` when the URL was in an unexpected shape." }, "rating": { "type": "number", "nullable": true, "example": 4.5, "description": "The row's average rating — `aggregateRating.ratingValue`. Out of five; `rating_scale_max` carries the scale. Null on attractions, which publish no rating at all." }, "rating_scale_max": { "type": "number", "nullable": true, "example": 5, "description": "The top of the rating scale, as TripAdvisor's own `bestRating` states it — 5 here. Published rather than assumed because it is not 5 everywhere: Booking scores the same kind of hotel out of TEN, and a client that compares the two numbers without reading their scales is silently wrong by a factor of two. Null when the page states no `bestRating`." }, "review_count": { "type": "number", "nullable": true, "example": 3309, "description": "An exact count from `aggregateRating.reviewCount`, not an abbreviation. Null on attractions." }, "price_range": { "type": "string", "nullable": true, "example": "$$$", "description": "TripAdvisor's price band for the row, as it renders it." }, "telephone": { "type": "string", "nullable": true, "example": "+1 415-392-3434" }, "image": { "type": "string", "nullable": true, "description": "The row's lead photo, when the item carries one." }, "address": { "$ref": "#/components/schemas/TripadvisorPostalAddress" }, "geo": { "$ref": "#/components/schemas/TripadvisorGeo" } }, "required": [ "position", "schema_type", "name", "url", "geo_id", "location_id", "rating", "rating_scale_max", "review_count", "price_range", "telephone", "image", "address", "geo" ] }, "TripadvisorPostalAddress": { "type": "object", "nullable": true, "properties": { "street_address": { "type": "string", "nullable": true, "example": "999 California Street" }, "locality": { "type": "string", "nullable": true, "example": "San Francisco", "description": "City — schema.org `addressLocality`." }, "region": { "type": "string", "nullable": true, "example": "CA", "description": "State or province — schema.org `addressRegion`." }, "postal_code": { "type": "string", "nullable": true, "example": "94108" }, "country": { "type": "string", "nullable": true, "example": "US" } }, "required": [ "street_address", "locality", "region", "postal_code", "country" ], "description": "The structured address from the item's schema.org `PostalAddress`. Null when the item carries none — which is every attraction." }, "TripadvisorGeo": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number", "nullable": true, "example": 37.791553 }, "longitude": { "type": "number", "nullable": true, "example": -122.41039 } }, "required": [ "latitude", "longitude" ], "description": "Latitude and longitude from the item's `GeoCoordinates`. This is the one substantial field attractions DO carry." }, "TripadvisorDetailResponse": { "type": "object", "nullable": true, "properties": { "geo_id": { "type": "number", "example": 60713, "description": "Echoed back." }, "location_id": { "type": "number", "example": 115623, "description": "Echoed back." }, "kind": { "type": "string", "enum": [ "hotels", "restaurants" ], "example": "hotels" }, "url": { "type": "string", "nullable": true, "example": "https://www.tripadvisor.com/Hotel_Review-g60713-d115623-Reviews-Chancellor_Hotel_on_Union_Square-San_Francisco_California.html", "description": "The page TripAdvisor actually served, after any redirect." }, "schema_type": { "type": "string", "nullable": true, "example": "LodgingBusiness", "description": "The schema.org type this property published as — `LodgingBusiness` for hotels, `FoodEstablishment` for restaurants." }, "name": { "type": "string", "nullable": true, "example": "Chancellor Hotel on Union Square" }, "rating": { "type": "number", "nullable": true, "example": 4.5 }, "rating_scale_max": { "type": "number", "nullable": true, "example": 5, "description": "The top of the rating scale, from this page's own `bestRating` — never assumed 5, same reasoning as `TripadvisorListItem`." }, "review_count": { "type": "number", "nullable": true, "example": 3309 }, "price_range": { "type": "string", "nullable": true, "example": "$$$" }, "telephone": { "type": "string", "nullable": true, "example": "+1 415-392-3434", "description": "Measured across 10 live properties: present on 5/5 restaurants, 1/5 hotels. Null is a normal hotel page, not a missed field." }, "image": { "type": "string", "nullable": true }, "address": { "$ref": "#/components/schemas/TripadvisorPostalAddress" }, "geo": { "$ref": "#/components/schemas/TripadvisorGeo" }, "breadcrumbs": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/TripadvisorBreadcrumb" }, "description": "This property's breadcrumb trail. Null when the page carried no `BreadcrumbList`." } }, "required": [ "geo_id", "location_id", "kind", "url", "schema_type", "name", "rating", "rating_scale_max", "review_count", "price_range", "telephone", "image", "address", "geo", "breadcrumbs" ] }, "BookingHotelResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "nullable": true, "example": "luma-san-francisco", "description": "The slug that was fetched, echoed back." }, "country_code": { "type": "string", "nullable": true, "example": "us", "description": "The country code that was fetched, echoed back." }, "name": { "type": "string", "example": "LUMA Hotel San Francisco", "description": "Property name. This is the only non-nullable property-detail field." }, "url": { "type": "string", "nullable": true, "example": "https://www.booking.com/hotel/us/luma-san-francisco.html", "description": "The property's page on Booking, as its own block states it." }, "description": { "type": "string", "nullable": true, "description": "Booking's own description of the property." }, "image": { "type": "string", "nullable": true, "example": "https://cf.bstatic.com/xdata/images/hotel/max500/407321240.jpg", "description": "The property's lead photo." }, "price_range": { "type": "string", "nullable": true, "description": "schema.org `priceRange`. Frequently null — Booking prices a stay, not a hotel, so the property page often states no band at all. Use `/booking/search` with dates for real prices." }, "address": { "$ref": "#/components/schemas/BookingPostalAddress" }, "rating": { "type": "number", "nullable": true, "example": 9.1, "description": "Guest score out of `rating_scale_max`, which is 10." }, "rating_scale_max": { "type": "number", "nullable": true, "example": 10, "description": "The top of the rating scale — 10, from Booking's own `bestRating`. Published rather than assumed, and published on every response rather than only in these docs, because it is the field that stops `rating` being read on the wrong scale." }, "review_count": { "type": "number", "nullable": true, "example": 1019, "description": "Total number of reviews used for the guest score. This can exceed `review_sample_size`." }, "subscores": { "type": "array", "items": { "$ref": "#/components/schemas/BookingSubscore" }, "description": "The rating broken down — cleanliness, comfort, location, facilities, staff, value. Six on a typical property page, each out of ten. Empty array when the page shows none, never null." }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/BookingReview" }, "description": "Featured guest-review sample from the property page. This is not a complete review list and may be empty." }, "review_sample_size": { "type": "number", "example": 10, "description": "Number of reviews in the `reviews` sample." }, "reviews_note": { "type": "string", "example": "10 featured guest reviews, which is the curated sample Booking renders into the property page — not the full review list, and not the most recent N. The complete list is not reachable on this tier: the /reviewlist.html fragment endpoint answers 404 in every form tried, and the property page fetches no reviews over its API at all.", "description": "Explains that `reviews` contains the featured sample shown on the property page, not the complete review list." } }, "required": [ "slug", "country_code", "name", "url", "description", "image", "price_range", "address", "rating", "rating_scale_max", "review_count", "subscores", "reviews", "review_sample_size", "reviews_note" ] }, "BookingPostalAddress": { "type": "object", "nullable": true, "properties": { "street_address": { "type": "string", "nullable": true, "example": "100 Channel Street, San Francisco, CA 94158, United States", "description": "Booking writes the whole address into `streetAddress`, city and all — so this is usually a full one-line address rather than just a street." }, "locality": { "type": "string", "nullable": true, "description": "City, when Booking states it separately. Often null." }, "region": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "CA 94158" }, "country": { "type": "string", "nullable": true, "example": "US" } }, "required": [ "street_address", "locality", "region", "postal_code", "country" ], "description": "The structured address from the property's schema.org `PostalAddress`. Null when the block carried none." }, "BookingSubscore": { "type": "object", "properties": { "label": { "type": "string", "example": "Staff" }, "score": { "type": "number", "example": 9.3, "description": "Out of 10, like every guest score on Booking." } }, "required": [ "label", "score" ] }, "BookingReview": { "type": "object", "properties": { "author": { "type": "string", "nullable": true, "example": "Marta", "description": "The guest's first name as Booking prints it. Null when the review block carried no name." }, "country": { "type": "string", "nullable": true, "example": "Poland", "description": "The guest's country, read from the flag image beside their name." }, "text": { "type": "string", "example": "Great location, walkable to everything, and the staff were…", "description": "The review body, with Booking's typographic quotation marks stripped. Non-null by construction: a featured-review block with no text is not published as a review." } }, "required": [ "author", "country", "text" ] }, "BookingSearchResponse": { "type": "object", "nullable": true, "properties": { "destination": { "type": "string", "nullable": true, "example": "San Francisco" }, "checkin": { "type": "string", "nullable": true, "example": "2026-09-10", "description": "The arrival date this search ran with, or null." }, "checkout": { "type": "string", "nullable": true, "example": "2026-09-12" }, "adults": { "type": "number", "nullable": true, "example": 2 }, "rooms": { "type": "number", "nullable": true, "example": 1 }, "offset": { "type": "number", "nullable": true, "example": 0, "description": "The offset this page was read at, echoed back." }, "rows_per_page": { "type": "number", "nullable": true, "example": 25, "description": "The page size this search asked Booking for." }, "count": { "type": "number", "example": 25, "description": "How many properties are in this response. Counted from what you received, never copied from a figure Booking printed." }, "total_results": { "type": "number", "nullable": true, "example": 353, "description": "Total properties Booking reports for the destination. Use it with `offset` and `rows_per_page` to plan pagination." }, "results_per_page": { "type": "number", "nullable": true, "example": 25, "description": "The page size Booking says it applied (`nbResultsPerPage`), which is normally the `rows_per_page` you asked for. Both are published because a difference between them is worth seeing." }, "has_more": { "type": "boolean", "nullable": true, "example": true, "description": "Whether `offset + count` is less than `total_results`. Null when Booking provides no total." }, "exhausted": { "type": "boolean", "example": false, "description": "Whether pagination passed the end of the list and returned no rows." }, "priced_for_stay": { "type": "boolean", "example": false, "description": "Whether `checkin` and `checkout` were supplied. Dated searches include stay availability and prices; dateless searches do not." }, "pricing_note": { "type": "string", "example": "No dates were given, so no row carries a price. Booking returns availability and pricing only for a specific stay — a dateless search returns the properties and nothing about what they cost. Pass `checkin` and `checkout` to get prices. An absent `price` here is the question you asked, not missing data.", "description": "Explains whether prices are present based on the request's check-in and check-out dates." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BookingSearchResult" }, "description": "The page's properties, in Booking's own ranking — which includes its paid placements. Every row carries `is_ad`. Empty array, never null." } }, "required": [ "destination", "checkin", "checkout", "adults", "rooms", "offset", "rows_per_page", "count", "total_results", "results_per_page", "has_more", "exhausted", "priced_for_stay", "pricing_note", "results" ] }, "BookingSearchResult": { "type": "object", "properties": { "property_id": { "type": "string", "nullable": true, "example": "56066", "description": "Booking's internal id for the property, published as a string. Not accepted by any endpoint here — `slug` is what `/booking/hotel` takes — but it is the stable key across dated and dateless searches." }, "slug": { "type": "string", "nullable": true, "example": "club-quarters-san-francisco", "description": "The property's slug — Booking's `pageName`, and the input to `/booking/hotel`. Together with `country_code` it is everything needed to fetch the full property page, which is where the guest reviews and the subscore breakdown live." }, "country_code": { "type": "string", "nullable": true, "example": "us", "description": "The property's country, from its location. The second half of what `/booking/hotel` needs." }, "url": { "type": "string", "nullable": true, "example": "https://www.booking.com/hotel/us/club-quarters-san-francisco.html", "description": "The property's page on Booking, built from `country_code` and `slug`. Null when the row states no country, since a `/hotel//slug` path would be a link to nowhere." }, "name": { "type": "string", "nullable": true, "example": "Club Quarters Hotel" }, "description": { "type": "string", "nullable": true, "description": "Booking's one-paragraph blurb for the property." }, "star_rating": { "type": "number", "nullable": true, "example": 4, "description": "Property star classification out of `star_rating_scale_max`, which is 5." }, "star_rating_scale_max": { "type": "number", "example": 5, "description": "Always 5. Stated per row rather than left to the documentation, because the field beside it is out of ten." }, "review_score": { "type": "number", "nullable": true, "example": 8.2, "description": "Guest review score out of `review_score_scale_max`, which is 10." }, "review_score_scale_max": { "type": "number", "example": 10, "description": "Always 10." }, "review_count": { "type": "number", "nullable": true, "example": 5043, "description": "How many guest reviews the score is computed over — exact, from Booking's own JSON." }, "external_review_score": { "type": "number", "nullable": true, "example": 8.76, "description": "A score Booking sources from outside its own guests, when it holds one. Also out of ten, and computed over a different (usually much smaller) population — see `external_review_count`. Do not average it with `review_score`." }, "external_review_count": { "type": "number", "nullable": true, "example": 37 }, "photo_url": { "type": "string", "nullable": true, "example": "https://cf.bstatic.com/xdata/images/hotel/square600/282380075.webp", "description": "The property's lead photo, absolutised. Booking states these as relative paths (`/xdata/images/hotel/square600/…`) and serves them from `cf.bstatic.com`; the host is added here so the URL is usable as it stands." }, "destination_id": { "type": "number", "nullable": true, "example": 20015732, "description": "Booking's `ufi` — its internal id for the city or area the property sits in. Useful as a grouping key; no endpoint here takes one." }, "accommodation_type_id": { "type": "number", "nullable": true, "example": 204, "description": "Booking's own code for the kind of property (hotel, apartment, hostel…). Published as the opaque number it is — Booking publishes no public mapping for it, and inventing labels would be inventing meaning." }, "is_closed": { "type": "boolean", "nullable": true }, "is_sold_out": { "type": "boolean", "nullable": true, "description": "Whether the property has no availability for the search. Meaningful only on a dated search — see `priced_for_stay`." }, "is_sustainable": { "type": "boolean", "nullable": true, "description": "Booking's own sustainability flag for the property." }, "is_ad": { "type": "boolean", "nullable": true, "example": false, "description": "Whether this row bought its position. Booking marks its own paid placements (`showNativeAdLabel`), and a caller ranking properties needs to know which ones are ads. Null when the row says nothing either way, rather than assumed organic." }, "native_ad_id": { "type": "string", "nullable": true, "description": "Booking's id for the placement, when the row is an ad." }, "is_preferred": { "type": "boolean", "nullable": true, "description": "Booking's Preferred Partner programme — a commercial relationship that affects ranking, distinct from a paid ad slot." }, "is_preferred_plus": { "type": "boolean", "nullable": true }, "location": { "$ref": "#/components/schemas/BookingSearchLocation" }, "price": { "$ref": "#/components/schemas/BookingSearchPrice" } }, "required": [ "property_id", "slug", "country_code", "url", "name", "description", "star_rating", "star_rating_scale_max", "review_score", "review_score_scale_max", "review_count", "external_review_score", "external_review_count", "photo_url", "destination_id", "accommodation_type_id", "is_closed", "is_sold_out", "is_sustainable", "is_ad", "native_ad_id", "is_preferred", "is_preferred_plus", "location", "price" ] }, "BookingSearchLocation": { "type": "object", "nullable": true, "properties": { "address": { "type": "string", "nullable": true, "example": "424 Clay Street" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "country_code": { "type": "string", "nullable": true, "example": "us" }, "latitude": { "type": "number", "nullable": true, "example": 37.795 }, "longitude": { "type": "number", "nullable": true, "example": -122.4 }, "display_location": { "type": "string", "nullable": true, "example": "Financial District", "description": "The neighbourhood label Booking prints on the card — a different field from `city`, and the more useful one for a human." }, "distance_from_centre": { "type": "string", "nullable": true, "example": "0.6 miles from downtown", "description": "Booking's own `mainDistance`, as prose. A string because Booking states it as one, units and all; parsing it into a number would mean guessing at the unit and the reference point." }, "public_transport_distance": { "type": "string", "nullable": true, "description": "Booking's transit-proximity blurb, when it ships one." }, "is_centrally_located": { "type": "boolean", "nullable": true }, "is_within_best_location_score_area": { "type": "boolean", "nullable": true, "description": "Booking's own flag for the part of town its location scores favour." } }, "required": [ "address", "city", "country_code", "latitude", "longitude", "display_location", "distance_from_centre", "public_transport_distance", "is_centrally_located", "is_within_best_location_score_area" ], "description": "Where the property is. Booking splits this across two objects on the row — a structured address with coordinates, and the display copy about neighbourhood and distance — and they are merged here, because they answer one question." }, "BookingSearchPrice": { "type": "object", "nullable": true, "properties": { "per_night_display": { "type": "string", "nullable": true, "example": "$193", "description": "The average nightly price, as Booking formats it for display — currency symbol included, from `averagePricePerNight.amountRounded`. A string, because that is the form Booking states it in." }, "stay_total_display": { "type": "string", "nullable": true, "example": "$386", "description": "The total for the whole stay, formatted, from the first room offer's `finalPrice`." }, "stay_total_amount": { "type": "number", "nullable": true, "example": 386, "description": "The same total as a number, when Booking states one. Pair it with `currency` — it carries no currency of its own." }, "currency": { "type": "string", "nullable": true, "example": "USD" } }, "required": [ "per_night_display", "stay_total_display", "stay_total_amount", "currency" ], "description": "Stay price for the requested dates. Null on dateless searches; see `priced_for_stay` and `pricing_note`." }, "BuiltWithProfileResponse": { "type": "object", "nullable": true, "properties": { "domain": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "technology_spend_monthly_usd": { "type": "number", "nullable": true, "description": "BuiltWith's estimated minimum monthly spend across detected paid technologies.", "example": 46034 }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltWithTechnology" } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "technology_count": { "type": "integer", "minimum": 0 } }, "required": [ "name", "technology_count" ] } }, "counts": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "visible": { "type": "integer", "minimum": 0 }, "redacted": { "type": "integer", "minimum": 0 }, "current": { "type": "integer", "minimum": 0 }, "historical": { "type": "integer", "minimum": 0 } }, "required": [ "total", "visible", "redacted", "current", "historical" ] } }, "required": [ "domain", "url", "technology_spend_monthly_usd", "technologies", "categories", "counts" ] }, "BuiltWithTechnology": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The public technology name. Null with `redacted: true` means BuiltWith counts the detection but hides its name on the anonymous profile.", "example": "Google Analytics" }, "category": { "type": "string", "nullable": true }, "subcategories": { "type": "array", "items": { "type": "string" } }, "first_detected": { "type": "string", "nullable": true }, "last_detected": { "type": "string", "nullable": true }, "current": { "type": "boolean" }, "historical": { "type": "boolean" }, "free": { "type": "boolean" }, "premium": { "type": "boolean" }, "newly_detected": { "type": "boolean" }, "redacted": { "type": "boolean" }, "technology_url": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true } }, "required": [ "name", "category", "subcategories", "first_detected", "last_detected", "current", "historical", "free", "premium", "newly_detected", "redacted", "technology_url", "icon_url" ] }, "TrustpilotCompanyResponse": { "type": "object", "nullable": true, "properties": { "domain": { "type": "string", "example": "www.amazon.com", "description": "The domain you asked for, echoed back." }, "page": { "type": "number", "example": 1, "description": "The page you asked for, echoed back. Compare it with `pagination.current_page` to see which page Trustpilot actually served." }, "sort": { "type": "string", "nullable": true, "enum": [ "recency", "relevance", null ], "example": null, "description": "The sort you asked for, or null if you asked for none. See `effective_sort` for what the ordering actually is." }, "effective_sort": { "type": "string", "enum": [ "recency", "relevance" ], "example": "recency", "description": "What these reviews are actually ordered by. Trustpilot's default is `recency`, so this is `recency` whenever you sent no `sort` — a caller reading only `sort: null` cannot tell recency from unknown, which is the whole reason this field exists." }, "page_size": { "type": "number", "example": 20, "description": "Reviews per page, taken from Trustpilot's own `perPage` when the page states one and falling back to 20, which is what every page measured has stated." }, "total_pages": { "type": "number", "nullable": true, "example": 1498, "description": "How many pages of reviews there are, from Trustpilot's own count. One company measured 1,498. Computed over the FILTERED set — see `total_filtered_reviews`." }, "has_more": { "type": "boolean", "nullable": true, "example": true, "description": "Whether another page exists, computed as `page < total_pages` from Trustpilot's own page count rather than from 'this page came back full'. A full page is not evidence of a next one, and the last page of a 1,498-page company is usually short. Null when Trustpilot stated no page count." }, "business_unit": { "$ref": "#/components/schemas/TrustpilotBusinessUnit" }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotReview" }, "description": "This page's reviews, 20 to a page, in `effective_sort` order. Empty array — never null — for a company with none, which is a fact about the company rather than a failure." }, "count": { "type": "number", "example": 20, "description": "How many reviews are in this response. Counted from what you received, never copied from a figure Trustpilot printed." }, "pagination": { "$ref": "#/components/schemas/TrustpilotPagination" }, "review_statistics": { "$ref": "#/components/schemas/TrustpilotReviewStatistics" }, "total_reviews": { "type": "number", "nullable": true, "example": 45550, "description": "Every review the company has — the larger of the two totals, and the one you CANNOT page through. Measured 45,550 against 29,953 filtered on the same page. Both are published because publishing either alone would make the other look like a bug." }, "total_filtered_reviews": { "type": "number", "nullable": true, "example": 29953, "description": "Reviews matching Trustpilot's default language filter — the smaller total, and the one paging actually walks. It is what `pagination.total_count` counts and what `total_pages` is computed from, so it is the number to size a crawl with. The difference between this and `total_reviews` is reviews in other languages; `review_statistics.review_languages` breaks it down." } }, "required": [ "domain", "page", "sort", "effective_sort", "page_size", "total_pages", "has_more", "business_unit", "reviews", "count", "pagination", "review_statistics", "total_reviews", "total_filtered_reviews" ] }, "TrustpilotBusinessUnit": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "47b8e2f0000064000502b1c3", "description": "Trustpilot's internal id for the company, as a string. No endpoint here takes one — `identifying_name` is the key — but it is stable across renames of the domain." }, "identifying_name": { "type": "string", "nullable": true, "example": "www.amazon.com", "description": "The company's key on Trustpilot, and the exact string `/trustpilot/company` takes as `domain`. Usually a hostname, `www.` and all — but about 0.25% of keys carry a path as well (`rac.co.uk/insurance`), and that path is part of the key rather than decoration. This is the canonical spelling: if you asked under a different one, Trustpilot redirected you here." }, "display_name": { "type": "string", "nullable": true, "example": "Amazon" }, "url": { "type": "string", "nullable": true, "example": "https://www.trustpilot.com/review/www.amazon.com", "description": "The company's page on Trustpilot, built from `identifying_name`." }, "review_count": { "type": "number", "nullable": true, "example": 48410, "description": "The company's own headline review count, and it is a third number — not `total_reviews` and not `total_filtered_reviews`. Trustpilot states all three on one page (the capture in apps/worker/tests/test_trustpilot_parsers.py has 48,410 here against 45,550 and 29,953 below), so they are published separately rather than reconciled into a single figure this API cannot justify." }, "review_count_last_12_months": { "type": "number", "nullable": true, "example": 8925, "description": "Reviews in the last twelve months. The useful one for judging whether a rating is current or a decade of accumulated history." }, "country_code": { "type": "string", "nullable": true, "example": "GB" }, "is_claimed": { "type": "boolean", "nullable": true, "description": "Whether the company has claimed its profile. An unclaimed profile cannot reply to reviews, which is the context for a `reply_percentage` of zero." }, "is_closed": { "type": "boolean", "nullable": true }, "is_temporarily_closed": { "type": "boolean", "nullable": true }, "is_collecting_reviews": { "type": "boolean", "nullable": true, "description": "Whether Trustpilot is still accepting reviews for this company." }, "locations_count": { "type": "number", "nullable": true }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotCategoryTag" }, "description": "The categories Trustpilot files the company under. Each `id` is a category slug — the input to `/trustpilot/category` — so this is the second way to walk the site: from one company out to its peers. Empty array, never null." }, "contact_info": { "$ref": "#/components/schemas/TrustpilotContactInfo" }, "consumer_alerts": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } }, "description": "Trustpilot's own warnings about the company — the banners it puts on profiles it has taken action against. Empty for every company captured, which is why the alert objects inside are passed through exactly as Trustpilot ships them instead of being renamed into fields nobody has seen. `has_consumer_alerts` is the part you can rely on." }, "has_consumer_alerts": { "type": "boolean", "example": false, "description": "Whether Trustpilot has posted any alert on this company, computed from the array above. Published as its own boolean so the one fact that matters survives whatever shape the alerts themselves take." }, "breadcrumb": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "Trustpilot's own category trail for the company, republished unchanged. It was absent from every capture, so there is no measured field list to rename it into — and inventing one would publish a column of nulls and call it a schema. Use `categories` for the category ids." }, "activity": { "$ref": "#/components/schemas/TrustpilotActivity" } }, "required": [ "id", "identifying_name", "display_name", "url", "review_count", "review_count_last_12_months", "country_code", "is_claimed", "is_closed", "is_temporarily_closed", "is_collecting_reviews", "locations_count", "categories", "contact_info", "consumer_alerts", "has_consumer_alerts", "breadcrumb", "activity" ], "description": "The company's record — its key, its counts, its categories, its claim status and its reply behaviour. This is the anchor the rest of the response hangs off, so it is the one non-nullable object here." }, "TrustpilotCategoryTag": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "shoe_store", "description": "The category slug, which is what `/trustpilot/category` takes. Trustpilot spells the field `id` on a company record and `categoryId` on a search row; both arrive here as `id`." }, "name": { "type": "string", "nullable": true, "example": "Shoe Store", "description": "The category's display name. Null on a search result's `categories`, where Trustpilot states only the id and the primary flag — the id is still the slug, so the composition works either way." }, "is_primary": { "type": "boolean", "nullable": true, "example": false, "description": "Whether this is the category Trustpilot files the company under first. A company sits in several." } }, "required": [ "id", "name", "is_primary" ] }, "TrustpilotContactInfo": { "type": "object", "nullable": true, "properties": { "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "example": "GB" } }, "required": [ "email", "phone", "country" ], "description": "The contact details Trustpilot publishes. Trustpilot writes empty strings for details a company has not listed, and those arrive here as `null`; the whole object is null when it states none of them." }, "TrustpilotActivity": { "type": "object", "nullable": true, "properties": { "is_claimed": { "type": "boolean", "nullable": true, "description": "Whether the company has claimed its Trustpilot profile. Mirrors `is_claimed` on the business record itself." }, "claimed_date": { "type": "string", "nullable": true, "example": "2015-02-18T19:08:43.000Z", "description": "When they claimed it, as an ISO timestamp. Not rendered anywhere on Trustpilot's own page." }, "previously_claimed": { "type": "boolean", "nullable": true, "description": "Whether the profile was ever claimed and then let go." }, "is_using_paid_features": { "type": "boolean", "nullable": true }, "has_subscription": { "type": "boolean", "nullable": true, "description": "Whether the company pays Trustpilot. Worth reading beside `reply_behavior`: invitation-driven review collection is a paid feature, and it moves both the volume and the average rating." }, "reply_behavior": { "$ref": "#/components/schemas/TrustpilotReplyBehavior" } }, "required": [ "is_claimed", "claimed_date", "previously_claimed", "is_using_paid_features", "has_subscription", "reply_behavior" ], "description": "Claim status, claim date and reply behaviour — see `reply_behavior`, which is the part of this response Trustpilot's own page does not render at all." }, "TrustpilotReplyBehavior": { "type": "object", "nullable": true, "properties": { "reply_percentage": { "type": "number", "nullable": true, "example": 12, "description": "What share of its reviews the company answers. Trustpilot's own `replyPercentage`." }, "average_days_to_reply": { "type": "number", "nullable": true, "example": 3, "description": "How long it takes them, in days, on average." }, "negative_reviews_with_replies_count": { "type": "number", "nullable": true, "example": 41, "description": "How many negative reviews got an answer — the number that separates a company replying to its fans from one handling complaints." }, "last_reply_to_negative_review": { "type": "string", "nullable": true, "description": "When the company last answered a negative review, as an ISO timestamp. Null when it never has — which, next to a non-zero `negative_reviews_with_replies_count`, is Trustpilot stating it does not hold a date rather than a contradiction." } }, "required": [ "reply_percentage", "average_days_to_reply", "negative_reviews_with_replies_count", "last_reply_to_negative_review" ], "description": "How the company handles its reviews — the most distinctive data on Trustpilot, and nothing on their own page shows it. It rides inside the page's `__NEXT_DATA__` blob and costs nothing extra to read: reply rate, average days to reply, how many negative reviews were answered, and when the last one was.\n\nThis is a measurement of the COMPANY rather than of any review, and it is what turns a review dump into reputation analysis. Null when Trustpilot states none of the four." }, "TrustpilotReview": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "6a80e73565b884964e2bc035" }, "title": { "type": "string", "nullable": true, "example": "Don't lie !!" }, "text": { "type": "string", "nullable": true, "description": "The review body as written. Null when the reviewer left a rating and a title and no prose, which is common at both ends of the scale." }, "rating": { "type": "number", "nullable": true, "example": 1, "description": "The reviewer's stars, OUT OF FIVE — see `rating_scale_max`. The Booking endpoints in this catalogue score out of ten, so read the scale before comparing the two." }, "rating_scale_max": { "type": "number", "example": 5, "description": "Always 5 on Trustpilot. Stated on every review rather than left to the documentation, because a neighbouring endpoint's identical-looking `rating` is out of ten." }, "likes": { "type": "number", "nullable": true, "example": 0, "description": "How many readers marked the review useful." }, "source": { "type": "string", "nullable": true, "example": "Organic", "description": "How the review was collected, in Trustpilot's own words. `Organic` means the reviewer came on their own; an invited review was solicited by the company, which is a paid Trustpilot feature and skews positive. Read it together with `verification_source`." }, "language": { "type": "string", "nullable": true, "example": "en", "description": "The review's language. This is the axis the default filter works on — see `total_filtered_reviews` on the response." }, "location": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "Which of the company's locations the review is about, for companies with more than one. Null on every review captured, so it is republished exactly as Trustpilot ships it rather than renamed into fields nobody has seen." }, "dates": { "$ref": "#/components/schemas/TrustpilotReviewDates" }, "has_reply": { "type": "boolean", "example": false, "description": "Whether the company answered this review. Read from the presence of Trustpilot's reply block rather than from the fields inside it, so it stays trustworthy even if the reply's own shape changes. Every review in the capture had none, which is what makes the belt-and-braces worth the field." }, "reply": { "$ref": "#/components/schemas/TrustpilotReviewReply" }, "is_verified": { "type": "boolean", "nullable": true, "example": false, "description": "Whether Trustpilot verified the reviewer actually did business with the company. Lifted out of Trustpilot's `labels.verification` rather than left inside an opaque blob, because it is the field review-quality analysis turns on." }, "verification_source": { "type": "string", "nullable": true, "example": "invitation", "description": "How it was verified — `invitation` means the company asked this person for the review. A wall of verified, invited five-star reviews is a different signal from a wall of organic ones, and this is the field that tells them apart." }, "is_pending": { "type": "boolean", "nullable": true, "description": "Trustpilot is still processing the review." }, "is_filtered": { "type": "boolean", "nullable": true, "description": "Trustpilot's own `filtered` flag for the review. Its filtered set is what `total_filtered_reviews` counts." }, "consumer": { "$ref": "#/components/schemas/TrustpilotConsumer" } }, "required": [ "id", "title", "text", "rating", "rating_scale_max", "likes", "source", "language", "location", "dates", "has_reply", "reply", "is_verified", "verification_source", "is_pending", "is_filtered", "consumer" ] }, "TrustpilotReviewDates": { "type": "object", "nullable": true, "properties": { "experienced_date": { "type": "string", "nullable": true, "example": "2026-08-15T00:00:00.000Z", "description": "When the reviewer says the experience happened, which is not when they wrote about it. This is the date to use for anything about the business; `published_date` is about the review." }, "published_date": { "type": "string", "nullable": true, "example": "2026-08-16T00:24:53.000Z", "description": "When the review went up. This is what `sort=recency` — Trustpilot's default — orders by." }, "updated_date": { "type": "string", "nullable": true, "description": "When the reviewer last edited it, when they have." } }, "required": [ "experienced_date", "published_date", "updated_date" ], "description": "When it happened, when it was published and when it was last edited — three different dates, and the first two routinely differ." }, "TrustpilotReviewReply": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "nullable": true, "description": "What the company wrote back." }, "published_date": { "type": "string", "nullable": true, "description": "When they wrote it, as an ISO timestamp." } }, "required": [ "text", "published_date" ], "description": "The company's response, when there is one — often null. `has_reply` is the reliable signal; this is the content." }, "TrustpilotConsumer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "6379404e69c66a0012fb0e39" }, "display_name": { "type": "string", "nullable": true, "example": "Rosemary Hart" }, "review_count": { "type": "number", "nullable": true, "example": 5, "description": "How many reviews this person has written on Trustpilot, across all companies. The single most useful field for weighting a review: a reviewer with one is not a reviewer with two hundred." }, "country_code": { "type": "string", "nullable": true, "example": "GB" } }, "required": [ "id", "display_name", "review_count", "country_code" ], "description": "Who wrote it, and how many reviews they have written in total. Null when the review carried no reviewer record." }, "TrustpilotPagination": { "type": "object", "nullable": true, "properties": { "current_page": { "type": "number", "nullable": true, "example": 1, "description": "The page Trustpilot says it served, which is worth comparing with the `page` you asked for: an out-of-range page is answered with a page that exists rather than with an error." }, "per_page": { "type": "number", "nullable": true, "example": 20 }, "total_count": { "type": "number", "nullable": true, "example": 29953, "description": "How many reviews this pagination walks — the FILTERED total, not every review the company has. It equals `total_filtered_reviews`, and `total_pages` is computed from it. The larger `total_reviews` is not reachable by paging." }, "total_pages": { "type": "number", "nullable": true, "example": 1498 } }, "required": [ "current_page", "per_page", "total_count", "total_pages" ], "description": "Trustpilot's own pagination block. Null when the page carried none." }, "TrustpilotReviewStatistics": { "type": "object", "properties": { "rating_distribution": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotRatingBucket" }, "description": "How the company's reviews split across one to five stars — the shape behind the average, and the part an average cannot tell you. Empty array when the page states none, never null." }, "has_multiple_languages": { "type": "boolean", "nullable": true, "description": "Whether the company has reviews in more than one language. When it does, `total_reviews` and `total_filtered_reviews` will differ." }, "review_languages": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotReviewLanguage" }, "description": "Per-language review counts, including Trustpilot's own `all` row. This is where the gap between the two totals becomes legible." } }, "required": [ "rating_distribution", "has_multiple_languages", "review_languages" ], "description": "The star distribution and the per-language breakdown for the whole company, not for this page." }, "TrustpilotRatingBucket": { "type": "object", "properties": { "rating": { "type": "number", "nullable": true, "example": 1 }, "count": { "type": "number", "nullable": true, "example": 32298 } }, "required": [ "rating", "count" ] }, "TrustpilotReviewLanguage": { "type": "object", "properties": { "iso_code": { "type": "string", "nullable": true, "example": "all", "description": "The language, with `all` as Trustpilot's own row for the whole set." }, "review_count": { "type": "number", "nullable": true, "example": 45550 } }, "required": [ "iso_code", "review_count" ] }, "TrustpilotSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string", "example": "insurance", "description": "The query you asked for, echoed back." }, "page": { "type": "number", "example": 1, "description": "The page you asked for, echoed back." }, "page_size": { "type": "number", "example": 10, "description": "Results per page, and it is 10 — not 20. Search is the only listing on Trustpilot at this size; the company review list and the category directory are both 20. Taken from Trustpilot's own `pagination.pageSize` where the page states one, falling back to 10." }, "count": { "type": "number", "example": 10, "description": "How many companies are in this response. Counted from what you received, never copied from a figure Trustpilot printed — and summing it across pages overcounts, because search pages repeat companies. See `pages_overlap`." }, "total_pages": { "type": "number", "nullable": true, "example": 978, "description": "How many pages of results there are, from Trustpilot's own count. 978 on the measured query. This, not the raw `hasMore` flag, is what says whether a walk is finished." }, "total_results": { "type": "number", "nullable": true, "example": 9779, "description": "How many companies Trustpilot says match — 9,779 on the measured query. Size the walk from it, but expect the distinct companies you actually collect to come in under it, because pages overlap." }, "has_more": { "type": "boolean", "nullable": true, "example": true, "description": "Whether another page exists — computed here, and deliberately NOT Trustpilot's own `hasMore`. That flag was measured as `false` on page 1 of a search reporting 978 total pages, so whatever it tracks it is not pagination; republishing it would stop every caller after ten results. This is `pagination.current_page < total_pages`, and the raw flag is not published anywhere in this response. Null when Trustpilot stated no page count." }, "pages_overlap": { "type": "boolean", "example": true, "description": "Search pages repeat companies, and this says so rather than leaving it to be discovered as a count that does not add up. Measured: page 2 shared 2 of its 10 companies with page 1 (`goskippy.com`, `www.admiral.com`), compared by key. Search ranking is not a stable sequence — the company review list and the category directory both page with ZERO overlap, and search does not.\n\nSo a walk over more than one page must deduplicate on `business_unit_id`, and the sum of `count` across pages is an overcount rather than a total." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotSearchResult" }, "description": "This page's companies, 10 to a page, in Trustpilot's own relevance order. Every row carries `identifying_name`, which is what `/trustpilot/company` takes. Empty array — never null — for a query nothing matches, which is an answer rather than a failure." }, "search_mode": { "type": "string", "nullable": true, "example": "companies", "description": "Which search Trustpilot decided it was running. Reported as it arrives; no parameter here sets it." }, "suggested_categories": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotCategoryTag" }, "description": "Trustpilot's own guess at which categories the query belongs to, and each `id` is a slug `/trustpilot/category` takes. So a vague query turns into a directory to walk: search `insurance`, take a suggested category, list it twenty ranked companies at a time. Empty array, never null." }, "filters": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "The filter state Trustpilot says it applied to this search, republished unchanged. This endpoint exposes no filter parameters, and no capture has shown the block populated — so there is no measured field list to rename it into." }, "usage_note": { "type": "string", "example": "Each result's `identifying_name` is the exact value `/trustpilot/company` takes as `domain`. Pages can repeat companies — deduplicate on `business_unit_id` when walking more than one.", "description": "How to use these rows, stated in the response body — that each one feeds `/trustpilot/company` verbatim, and that a multi-page walk has to deduplicate. Both belong with the data rather than only in these docs." }, "pagination": { "$ref": "#/components/schemas/TrustpilotSearchPagination" } }, "required": [ "query", "page", "page_size", "count", "total_pages", "total_results", "has_more", "pages_overlap", "results", "search_mode", "suggested_categories", "filters", "usage_note", "pagination" ] }, "TrustpilotSearchResult": { "type": "object", "properties": { "business_unit_id": { "type": "string", "nullable": true, "example": "5060f52a00006400051bf99f", "description": "Trustpilot's internal id for the company — and the field to deduplicate a multi-page walk on. Search pages overlap: page 2 of a measured query repeated 2 of its 10 companies from page 1. This is the stable identity to compare, because it survives a company changing its domain." }, "identifying_name": { "type": "string", "nullable": true, "example": "rac.co.uk/insurance", "description": "The company's key, and the exact value `/trustpilot/company` takes as `domain`. That is what search is for: type a name, take this string, read the reviews. Nothing is constructed and nothing is guessed.\n\nThe example is not decorative. `rac.co.uk/insurance` is genuinely in the first page of results for `insurance`, and it is a different company from `rac.co.uk` — 18,579 reviews against 211,451. Pass this string through byte for byte; anything that trims it at the first `/` will fetch the wrong company and get a 200 for it." }, "display_name": { "type": "string", "nullable": true, "example": "RAC Car Insurance" }, "url": { "type": "string", "nullable": true, "example": "https://www.trustpilot.com/review/rac.co.uk/insurance", "description": "The company's page on Trustpilot, built from `identifying_name`. For the company's own site, see `contact.website`." }, "trust_score": { "type": "number", "nullable": true, "example": 4.4, "description": "Trustpilot's TrustScore for the company, out of five — the underlying number, to one decimal. Sort and compare on this; `stars` is its rounded display form." }, "stars": { "type": "number", "nullable": true, "example": 4.5, "description": "The star rating Trustpilot renders, out of five, rounded to the half star. Not a second opinion — a 4.4 `trust_score` displays as 4.5." }, "rating_scale_max": { "type": "number", "example": 5, "description": "Always 5, for both numbers above." }, "review_count": { "type": "number", "nullable": true, "example": 18579, "description": "How many reviews the score is computed over." }, "location": { "$ref": "#/components/schemas/TrustpilotSearchLocation" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotCategoryTag" }, "description": "The categories Trustpilot files the company under. Each `id` is a slug `/trustpilot/category` takes, so a search result branches sideways into a whole directory. Trustpilot states only the id and the primary flag on a search row, so `name` is null here. Empty array, never null." }, "is_claimed": { "type": "boolean", "nullable": true, "description": "Whether the company has claimed its Trustpilot profile. Fetch it with `/trustpilot/company` for the claim date and its reply behaviour." }, "is_recommended_in_categories": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "Trustpilot's own `isRecommendedInCategories` for the row, republished unchanged. It states which categories it promotes the company in, and no capture has shown its inner shape — renaming fields nobody has seen would mean inventing them." }, "logo_url": { "type": "string", "nullable": true, "example": "https://s3-eu-west-1.amazonaws.com/tpd/x/198x149.png", "description": "The company's logo. Trustpilot states these protocol-relative (`//s3-eu-west-1…`); the scheme is added here so the URL is usable as it stands." }, "contact": { "$ref": "#/components/schemas/TrustpilotSearchContact" } }, "required": [ "business_unit_id", "identifying_name", "display_name", "url", "trust_score", "stars", "rating_scale_max", "review_count", "location", "categories", "is_claimed", "is_recommended_in_categories", "logo_url", "contact" ] }, "TrustpilotSearchLocation": { "type": "object", "nullable": true, "properties": { "city": { "type": "string", "nullable": true, "example": "London" }, "country": { "type": "string", "nullable": true, "example": "GB", "description": "The company's country as the search row states it. The category listing states an `address` here instead — same site, different row." } }, "required": [ "city", "country" ], "description": "Where the company is, as the search row states it. Null when the row carries no location at all." }, "TrustpilotSearchContact": { "type": "object", "nullable": true, "properties": { "website": { "type": "string", "nullable": true, "example": "https://www.sterling-insurance.co.uk", "description": "The company's OWN website — not its Trustpilot page, which is `url`. The two are close enough to be confused and only this one leaves the site." }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "required": [ "website", "email", "phone" ], "description": "The company's own website, email and phone, on the search row itself — no second request. Null when Trustpilot states none of the three. (The category listing's `contact` was empty in every capture and is republished raw there; this one is real.)" }, "TrustpilotSearchPagination": { "type": "object", "nullable": true, "properties": { "current_page": { "type": "number", "nullable": true, "example": 1, "description": "The page Trustpilot says it served. `has_more` is computed from this and `total_pages`." }, "page_size": { "type": "number", "nullable": true, "example": 10, "description": "Trustpilot's own `pageSize` — 10 on search." }, "total_pages": { "type": "number", "nullable": true, "example": 978 }, "total_results": { "type": "number", "nullable": true, "example": 9779 } }, "required": [ "current_page", "page_size", "total_pages", "total_results" ], "description": "Trustpilot's own pagination block, minus its `hasMore` — see `has_more`. Null when the page carried none." }, "TrustpilotCategoryResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "bank", "description": "The category you asked for, echoed back." }, "page": { "type": "number", "example": 1, "description": "The page Trustpilot says it served, taken from the directory page's own `page` rather than from your request. Compare it with `requested_page`: they differ exactly when Trustpilot clamps a page past the end of the category, which it answers with a page that exists rather than with an error." }, "requested_page": { "type": "number", "example": 1, "description": "The page you asked for, echoed back." }, "page_clamped": { "type": "boolean", "example": false, "description": "Whether Trustpilot served a different page than the one you asked for, computed as `page !== requested_page`. It is how an out-of-range walk announces itself — the response is a full, valid directory page, just not the one requested, so a walk that only counted rows would loop over the last page forever." }, "country": { "type": "string", "nullable": true, "example": "US", "description": "The country filter this listing ran with, or null if you sent none." }, "count": { "type": "number", "example": 20, "description": "How many companies are in this response. Counted from what you received, never copied from a figure Trustpilot printed." }, "total_hits": { "type": "number", "nullable": true, "example": 1713, "description": "How many companies Trustpilot holds for this category — its own `totalHits`, 1,713 on the sampled category. Use it to size the walk rather than discovering the end by hitting it." }, "filters": { "$ref": "#/components/schemas/TrustpilotCategoryFilters" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotCategoryResult" }, "description": "The page's companies, in Trustpilot's own order. Every row carries `identifying_name`, which is what `/trustpilot/company` takes. Empty array, never null." }, "usage_note": { "type": "string", "example": "Each result's `identifying_name` is the exact value `/trustpilot/company` takes as `domain` — walk a category and fetch every company on it without constructing a URL.", "description": "How to use these rows, stated in the response body. The one thing a caller has to know about this endpoint is that its output feeds `/trustpilot/company` verbatim, and that belongs with the data rather than only in these docs." } }, "required": [ "slug", "page", "requested_page", "page_clamped", "country", "count", "total_hits", "filters", "results", "usage_note" ] }, "TrustpilotCategoryFilters": { "type": "object", "nullable": true, "properties": { "country": { "type": "string", "nullable": true, "example": "US" }, "sort": { "type": "string", "nullable": true, "example": "recommended", "description": "How Trustpilot ordered the directory. `recommended` is its default and it is not a public formula — read it as a label, not as a sort key you could reproduce. This endpoint exposes no sort parameter, because an unknown value on this site comes back 200 with the default ordering and nothing has been measured beyond it." } }, "required": [ "country", "sort" ], "description": "The filter state Trustpilot says it applied to this listing. Null when the page states none." }, "TrustpilotCategoryResult": { "type": "object", "properties": { "business_unit_id": { "type": "string", "nullable": true, "example": "5060f52a00006400051bf99f", "description": "Trustpilot's internal id for the company, as a string." }, "identifying_name": { "type": "string", "nullable": true, "example": "happen.com", "description": "The company's key, and the exact value `/trustpilot/company` takes as `domain`. This is what makes the two endpoints compose: walk a category, take this string, fetch the company's reviews. No URL is ever constructed and no slug is ever guessed — which matters on a site where the `www.` prefix is load-bearing and where ~0.25% of keys are a hostname PLUS a path (`rac.co.uk/insurance`, a different company from `rac.co.uk`). Pass it through unchanged." }, "display_name": { "type": "string", "nullable": true, "example": "Happen Bank" }, "url": { "type": "string", "nullable": true, "example": "https://www.trustpilot.com/review/happen.com", "description": "The company's Trustpilot page, built from `identifying_name`." }, "trust_score": { "type": "number", "nullable": true, "example": 4.7, "description": "Trustpilot's TrustScore for the company, out of five — the underlying number, to one decimal. This is the one to sort and compare on; `stars` is its rounded display form." }, "stars": { "type": "number", "nullable": true, "example": 4.5, "description": "The star rating Trustpilot renders, out of five, rounded to the half star. It is not a second opinion — the sampled row scores 4.7 and displays 4.5." }, "rating_scale_max": { "type": "number", "example": 5, "description": "Always 5, for both numbers above." }, "review_count": { "type": "number", "nullable": true, "example": 14357, "description": "How many reviews the score is computed over." }, "location": { "$ref": "#/components/schemas/TrustpilotCategoryLocation" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/TrustpilotCategoryTag" }, "description": "The company's other categories. Each `id` is a slug this endpoint takes, so a directory walk can branch sideways. Empty array, never null." }, "is_claimed": { "type": "boolean", "nullable": true, "description": "Whether the company has claimed its profile. Fetch it with `/trustpilot/company` for the claim date and its reply behaviour." }, "logo_url": { "type": "string", "nullable": true, "example": "https://s3-eu-west-1.amazonaws.com/tpd/x/198x149.png", "description": "The company's logo. Trustpilot states these protocol-relative (`//s3-eu-west-1…`); the scheme is added here so the URL is usable as it stands." }, "contact": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "The contact block Trustpilot puts on a directory row, republished unchanged. Absent from every row captured, so there is no measured field list to rename it into. `/trustpilot/company` returns a structured `contact_info` for any company here." } }, "required": [ "business_unit_id", "identifying_name", "display_name", "url", "trust_score", "stars", "rating_scale_max", "review_count", "location", "categories", "is_claimed", "logo_url", "contact" ] }, "TrustpilotCategoryLocation": { "type": "object", "nullable": true, "properties": { "address": { "type": "string", "nullable": true, "example": "88 Kearny Street" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" } }, "required": [ "address", "city" ], "description": "Where the company is, as the directory row states it. Null when the row carries no location at all." }, "TrustpilotDomainsResponse": { "type": "object", "nullable": true, "properties": { "domains": { "type": "array", "items": { "type": "string" }, "example": [ "www.budgetair.com", "happen.com" ], "description": "A window of company keys — each the exact value `/trustpilot/company` takes as `domain`. Mostly hostnames including `www.`; about 1 in 400 carries a path (`rac.co.uk/insurance`) and a few are internationalised (`kørkort.dk`). Names only, no score. Empty array past the end of the shard." }, "count": { "type": "number", "example": 1000, "description": "How many domains are in this response. Counted from what you received, never copied from a figure the worker printed." }, "shard": { "type": "number", "example": 0, "description": "The shard you asked for, echoed back." }, "shard_count": { "type": "number", "example": 18, "description": "How many shards the sitemap index lists, read from the live index rather than from a constant. Multiply by `shard_total` and you have the size of the whole job." }, "shard_total": { "type": "number", "example": 50000, "description": "How many domains are in THIS shard — the real number, counted from the shard itself. 50,000 for shards 0-16, and 24,063 for the last one, which is less than half full. Size a walk from this rather than assuming every shard is the same." }, "offset": { "type": "number", "example": 0, "description": "The offset this window was read at, echoed back." }, "limit": { "type": "number", "example": 1000, "description": "The window size you asked for, echoed back." }, "has_more": { "type": "boolean", "example": true, "description": "Whether this shard holds anything after this window, computed as `offset + count < shard_total` from the shard's own length. It says nothing about the shards after this one — walk those by incrementing `shard` up to `shard_count - 1`." }, "source_url": { "type": "string", "example": "https://sitemaps.trustpilot.com/domains0_en-us.xml", "description": "The sitemap this window came out of. Published so the claim is checkable: it is a public XML file on a host with no WAF in front of it, and you can open it yourself." }, "usage_note": { "type": "string", "example": "Each entry is the exact value `/trustpilot/company` takes as `domain`. These come from Trustpilot's public sitemap host, which needs no credential.", "description": "What these strings are for, stated in the response body. The one thing a caller has to know is that each entry feeds `/trustpilot/company` verbatim, and that belongs with the data rather than only in these docs." } }, "required": [ "domains", "count", "shard", "shard_count", "shard_total", "offset", "limit", "has_more", "source_url", "usage_note" ] }, "SimilarwebWebsiteResponse": { "type": "object", "nullable": true, "properties": { "domain": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "snapshot_date": { "type": "string", "nullable": true, "description": "The monthly data snapshot represented by the metrics.", "example": "2026-07-01T00:00:00+00:00" }, "category_id": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "preview_desktop_url": { "type": "string", "nullable": true }, "preview_mobile_url": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "company": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "year_founded": { "type": "number", "nullable": true }, "headquarters_country_code": { "type": "string", "nullable": true }, "headquarters_state_code": { "type": "string", "nullable": true }, "headquarters_city": { "type": "string", "nullable": true }, "employees_min": { "type": "number", "nullable": true }, "employees_max": { "type": "number", "nullable": true }, "revenue_min": { "type": "number", "nullable": true }, "revenue_max": { "type": "number", "nullable": true }, "revenue_currency": { "type": "string", "nullable": true }, "parent_domain": { "type": "string", "nullable": true } }, "required": [ "name", "year_founded", "headquarters_country_code", "headquarters_state_code", "headquarters_city", "employees_min", "employees_max", "revenue_min", "revenue_max", "revenue_currency", "parent_domain" ] }, "engagement": { "type": "object", "properties": { "visits": { "type": "number", "nullable": true, "description": "Estimated visits during the snapshot month.", "example": 197235347 }, "visits_change": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "pages_per_visit": { "type": "number", "nullable": true }, "average_visit_duration": { "type": "string", "nullable": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "nullable": true }, "value": { "type": "number", "nullable": true } }, "required": [ "date", "value" ] } } }, "required": [ "visits", "visits_change", "bounce_rate", "pages_per_visit", "average_visit_duration", "history" ] }, "rankings": { "type": "object", "properties": { "global": { "type": "object", "properties": { "rank": { "type": "number", "nullable": true }, "previous_rank": { "type": "number", "nullable": true }, "change": { "type": "number", "nullable": true } }, "required": [ "rank", "previous_rank", "change" ] }, "country": { "type": "object", "properties": { "rank": { "type": "number", "nullable": true }, "previous_rank": { "type": "number", "nullable": true }, "change": { "type": "number", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "country_slug": { "type": "string", "nullable": true } }, "required": [ "rank", "previous_rank", "change", "country_code", "country_slug" ] }, "category": { "type": "object", "properties": { "rank": { "type": "number", "nullable": true }, "previous_rank": { "type": "number", "nullable": true }, "change": { "type": "number", "nullable": true } }, "required": [ "rank", "previous_rank", "change" ] }, "global_history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "nullable": true }, "rank": { "type": "number", "nullable": true } }, "required": [ "date", "rank" ] } }, "country_history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "nullable": true }, "rank": { "type": "number", "nullable": true } }, "required": [ "date", "rank" ] } }, "category_history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "nullable": true }, "rank": { "type": "number", "nullable": true } }, "required": [ "date", "rank" ] } } }, "required": [ "global", "country", "category", "global_history", "country_history", "category_history" ] }, "top_countries": { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": "string", "nullable": true }, "country_slug": { "type": "string", "nullable": true }, "visits_share": { "type": "number", "nullable": true }, "visits_share_change": { "type": "number", "nullable": true } }, "required": [ "country_code", "country_slug", "visits_share", "visits_share_change" ] } }, "traffic_sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "nullable": true }, "rank": { "type": "number", "nullable": true }, "percentage": { "type": "number", "nullable": true } }, "required": [ "source", "rank", "percentage" ] } }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "category_id": { "type": "string", "nullable": true }, "category_rank": { "type": "number", "nullable": true }, "affinity": { "type": "number", "nullable": true } }, "required": [ "domain", "icon_url", "category_id", "category_rank", "affinity" ] } }, "demographics": { "type": "object", "properties": { "male_share": { "type": "number", "nullable": true }, "female_share": { "type": "number", "nullable": true }, "age_distribution": { "type": "array", "items": { "type": "object", "properties": { "min_age": { "type": "number", "nullable": true }, "max_age": { "type": "number", "nullable": true }, "share": { "type": "number", "nullable": true } }, "required": [ "min_age", "max_age", "share" ] } } }, "required": [ "male_share", "female_share", "age_distribution" ] }, "search": { "type": "object", "properties": { "organic_share": { "type": "number", "nullable": true }, "paid_share": { "type": "number", "nullable": true }, "keyword_count": { "type": "number", "nullable": true }, "top_keywords": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "cpc": { "type": "number", "nullable": true }, "volume": { "type": "number", "nullable": true } }, "required": [ "name", "cpc", "volume" ] } } }, "required": [ "organic_share", "paid_share", "keyword_count", "top_keywords" ] }, "social": { "type": "object", "properties": { "network_count": { "type": "number", "nullable": true }, "networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "visits_share": { "type": "number", "nullable": true }, "icon_url": { "type": "string", "nullable": true } }, "required": [ "name", "visits_share", "icon_url" ] } } }, "required": [ "network_count", "networks" ] }, "referrals": { "type": "object", "properties": { "incoming": { "type": "object", "properties": { "total_sites": { "type": "number", "nullable": true }, "sites": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "visits_share": { "type": "number", "nullable": true }, "locked": { "type": "boolean", "nullable": true } }, "required": [ "domain", "icon_url", "visits_share", "locked" ] } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "nullable": true }, "visits_share": { "type": "number", "nullable": true } }, "required": [ "category", "visits_share" ] } } }, "required": [ "total_sites", "sites", "categories" ] }, "outgoing": { "type": "object", "properties": { "total_sites": { "type": "number", "nullable": true }, "sites": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "visits_share": { "type": "number", "nullable": true }, "locked": { "type": "boolean", "nullable": true } }, "required": [ "domain", "icon_url", "visits_share", "locked" ] } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "nullable": true }, "visits_share": { "type": "number", "nullable": true } }, "required": [ "category", "visits_share" ] } } }, "required": [ "total_sites", "sites", "categories" ] } }, "required": [ "incoming", "outgoing" ] }, "technologies": { "type": "object", "properties": { "technology_count": { "type": "number", "nullable": true }, "category_count": { "type": "number", "nullable": true }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category_id": { "type": "string", "nullable": true }, "top_technology": { "type": "string", "nullable": true }, "top_technology_icon_url": { "type": "string", "nullable": true }, "technology_count": { "type": "number", "nullable": true } }, "required": [ "category_id", "top_technology", "top_technology_icon_url", "technology_count" ] } } }, "required": [ "technology_count", "category_count", "categories" ] }, "audience_interests": { "type": "object", "properties": { "websites": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "websites", "topics", "categories" ] } }, "required": [ "domain", "url", "snapshot_date", "category_id", "icon_url", "preview_desktop_url", "preview_mobile_url", "description", "company", "engagement", "rankings", "top_countries", "traffic_sources", "competitors", "demographics", "search", "social", "referrals", "technologies", "audience_interests" ] }, "SimilarwebTopWebsitesResponse": { "type": "object", "nullable": true, "properties": { "snapshot_date": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "global" ] }, "sites": { "type": "array", "items": { "$ref": "#/components/schemas/SimilarwebTopWebsite" } }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "snapshot_date", "scope", "sites", "count" ] }, "SimilarwebTopWebsite": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "domain": { "type": "string" }, "icon_url": { "type": "string", "nullable": true }, "rank_change": { "type": "number", "nullable": true }, "category_id": { "type": "string", "nullable": true }, "average_visit_duration": { "type": "string", "nullable": true }, "pages_per_visit": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "new_to_ranking": { "type": "boolean", "nullable": true } }, "required": [ "rank", "domain", "icon_url", "rank_change", "category_id", "average_visit_duration", "pages_per_visit", "bounce_rate", "new_to_ranking" ] }, "SemrushWebsiteResponse": { "type": "object", "nullable": true, "properties": { "requested_domain": { "type": "string", "example": "stripe.com", "description": "The domain this response was read for, echoed back after cleaning — so a caller who pasted a URL can see what it resolved to." }, "domain": { "type": "string", "example": "stripe.com", "description": "The domain Semrush's own page states it is about." }, "url": { "type": "string", "example": "https://www.semrush.com/website/stripe.com/overview/", "description": "The public Semrush page these figures come from. Open it and you see the same numbers, with no account." }, "as_of": { "type": "string", "nullable": true, "example": "2026-07-15", "description": "The month Semrush's figures describe. These are monthly estimates, not live counters — two calls a week apart return the same values." }, "updated_at": { "type": "string", "nullable": true, "example": "2026-08-12" }, "database": { "type": "string", "nullable": true, "example": "US", "description": "The Semrush database the country-scoped figures are measured in. It is always `US` on the free page — the exit country does not change it, and there is deliberately no parameter that pretends to." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushCategory" }, "description": "The industries Semrush files the domain under." }, "ranks": { "$ref": "#/components/schemas/SemrushRanks" }, "authority_score": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "description": "Semrush's 0-100 estimate of the domain's strength, from its backlink profile, organic traffic and link authenticity." } ] }, "engagement": { "$ref": "#/components/schemas/SemrushEngagement" }, "devices": { "$ref": "#/components/schemas/SemrushDevices" }, "countries": { "$ref": "#/components/schemas/SemrushCountries" }, "search_traffic": { "$ref": "#/components/schemas/SemrushSearchTraffic" }, "keywords": { "$ref": "#/components/schemas/SemrushKeywords" }, "backlinks": { "$ref": "#/components/schemas/SemrushBacklinks" }, "competitors": { "$ref": "#/components/schemas/SemrushCompetitors" }, "traffic_journey": { "$ref": "#/components/schemas/SemrushTrafficJourney" }, "ai_traffic": { "$ref": "#/components/schemas/SemrushAiTraffic" }, "related_domains": { "type": "array", "items": { "type": "string" }, "example": [ "stripeandstare.com", "stripersonline.com" ], "description": "The neighbouring domains Semrush links to alphabetically. Each is a valid `domain` for this endpoint." }, "unavailable_panels": { "type": "array", "items": { "type": "string" }, "example": [ "siteAudit" ], "description": "The panels Semrush itself marked as having no current data for this domain, under its own names. This is a gap in Semrush's index, not a gate and not a dropped field — it is stable across requests: openai.com returned the identical set as request 1 and as request 24 of one walk. `siteAudit` is in it for every domain, because it is a crawl of a site you own." }, "usage_note": { "type": "string", "example": "Every figure here is what Semrush serves an anonymous caller, and it is the full free page: 60 consecutive fetches on one identity returned identical values, so there is no view meter to spend. null means Semrush states no figure, never zero. unavailable_panels lists the panels Semrush marked as having no current data for this domain." } }, "required": [ "requested_domain", "domain", "url", "as_of", "updated_at", "database", "categories", "ranks", "authority_score", "engagement", "devices", "countries", "search_traffic", "keywords", "backlinks", "competitors", "traffic_journey", "ai_traffic", "related_domains", "unavailable_panels", "usage_note" ] }, "SemrushCategory": { "type": "object", "properties": { "slug": { "type": "string", "nullable": true, "example": "finance" }, "name": { "type": "string", "nullable": true, "example": "Finance" } }, "required": [ "slug", "name" ] }, "SemrushRanks": { "type": "object", "properties": { "global": { "$ref": "#/components/schemas/SemrushMetric" }, "country": { "$ref": "#/components/schemas/SemrushCountryRank" }, "category": { "$ref": "#/components/schemas/SemrushCategoryRank" } }, "required": [ "global", "country", "category" ] }, "SemrushMetric": { "type": "object", "properties": { "value": { "type": "number", "nullable": true, "example": 203227314, "description": "The figure Semrush states, or null when it states none. Never coerced to 0." }, "change_percent": { "type": "number", "nullable": true, "example": 0.1294, "description": "Semrush's own month-on-month change as a fraction (0.1294 = +12.94%)." }, "change_absolute": { "type": "number", "nullable": true, "example": -1, "description": "Semrush's own change in places, for the fields it reports that way instead — the three ranks. Negative means the rank number fell, which is an improvement." } }, "required": [ "value", "change_percent", "change_absolute" ], "description": "Position among all websites Semrush ranks worldwide." }, "SemrushCountryRank": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "example": "US", "description": "The Semrush database this rank is measured in." }, "name": { "type": "string", "nullable": true, "example": "United States" } }, "required": [ "code", "name" ] } ] }, "SemrushCategoryRank": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Finance" }, "slug": { "type": "string", "nullable": true, "example": "finance" } }, "required": [ "name", "slug" ] } ] }, "SemrushEngagement": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "visits": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "description": "Estimated total visits in the month." } ] }, "pages_per_visit": { "$ref": "#/components/schemas/SemrushMetric" }, "time_on_site_seconds": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "example": { "value": 498, "change_percent": null, "change_absolute": null }, "description": "Average session duration, in seconds." } ] }, "bounce_rate": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "description": "A fraction, not a percentage: 0.6072 is 60.72%." } ] }, "visits_history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushVisitsHistoryRow" }, "description": "Up to 3 months of total visits." } }, "required": [ "as_of", "visits", "pages_per_visit", "time_on_site_seconds", "bounce_rate", "visits_history" ] }, "SemrushVisitsHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-07-01" }, "visits": { "type": "number", "nullable": true } }, "required": [ "date", "visits" ] }, "SemrushDevices": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushDeviceHistoryRow" }, "description": "Up to 6 months of the desktop-versus-mobile split, newest first. Populated for some domains whose current headline `visits` is null, so it is worth reading even then." } }, "required": [ "as_of", "history" ] }, "SemrushDeviceHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-07-01" }, "visits": { "type": "number", "nullable": true }, "desktop_visits": { "type": "number", "nullable": true }, "mobile_visits": { "type": "number", "nullable": true } }, "required": [ "date", "visits", "desktop_visits", "mobile_visits" ] }, "SemrushCountries": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushCountryTraffic" }, "description": "The top 5 countries by traffic. Five is what the free page carries; there is no parameter that returns more." } }, "required": [ "as_of", "items" ] }, "SemrushCountryTraffic": { "type": "object", "properties": { "country": { "type": "string", "nullable": true, "example": "US" }, "country_name": { "type": "string", "nullable": true, "example": "United States" }, "traffic": { "type": "number", "nullable": true, "example": 57953085 }, "traffic_share": { "type": "number", "nullable": true, "example": 0.2852 }, "desktop_share": { "type": "number", "nullable": true, "example": 0.407 }, "mobile_share": { "type": "number", "nullable": true, "example": 0.593 } }, "required": [ "country", "country_name", "traffic", "traffic_share", "desktop_share", "mobile_share" ] }, "SemrushSearchTraffic": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "organic": { "$ref": "#/components/schemas/SemrushMetric" }, "paid": { "$ref": "#/components/schemas/SemrushMetric" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushSearchHistoryRow" }, "description": "Up to 6 months of organic and paid search traffic." } }, "required": [ "as_of", "organic", "paid", "history" ] }, "SemrushSearchHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-07-01" }, "organic": { "type": "number", "nullable": true }, "paid": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true } }, "required": [ "date", "organic", "paid", "total" ] }, "SemrushKeywords": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "database": { "type": "string", "nullable": true, "example": "US" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushKeyword" }, "description": "The top 5 organic keywords with position, monthly search volume and CPC. Five is what the free page carries." } }, "required": [ "as_of", "database", "items" ] }, "SemrushKeyword": { "type": "object", "properties": { "keyword": { "type": "string", "nullable": true, "example": "stripe" }, "position": { "type": "number", "nullable": true, "example": 1 }, "search_volume": { "type": "number", "nullable": true, "example": 673000 }, "cpc": { "type": "number", "nullable": true, "example": 2.99, "description": "Average cost per click in USD." }, "traffic_share": { "type": "number", "nullable": true, "example": 0.2723, "description": "The share of the domain's organic traffic this keyword brings, as a fraction." }, "intents": { "type": "string", "nullable": true, "example": "2", "description": "Semrush's own intent code for the keyword, republished as it arrives rather than decoded — no capture has pinned the mapping, and a guessed label is a wrong label that reads like a right one." } }, "required": [ "keyword", "position", "search_volume", "cpc", "traffic_share", "intents" ] }, "SemrushBacklinks": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "backlinks": { "allOf": [ { "$ref": "#/components/schemas/SemrushMetric" }, { "example": { "value": 151822916, "change_percent": -0.0933, "change_absolute": null } } ] }, "referring_domains": { "$ref": "#/components/schemas/SemrushMetric" }, "authority_score": { "$ref": "#/components/schemas/SemrushMetric" }, "google_penalty_risk": { "type": "string", "nullable": true, "example": "Low" }, "backlinks_history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushBacklinksHistoryRow" }, "description": "Up to 6 months of total backlinks." }, "referring_domains_history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushReferringDomainsHistoryRow" }, "description": "Up to 6 months of referring domains." } }, "required": [ "as_of", "backlinks", "referring_domains", "authority_score", "google_penalty_risk", "backlinks_history", "referring_domains_history" ] }, "SemrushBacklinksHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-07-01" }, "backlinks": { "type": "number", "nullable": true } }, "required": [ "date", "backlinks" ] }, "SemrushReferringDomainsHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-07-01" }, "referring_domains": { "type": "number", "nullable": true } }, "required": [ "date", "referring_domains" ] }, "SemrushCompetitors": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushCompetitorSummary" }, "description": "The 3 rivals the overview page names." } }, "required": [ "as_of", "items" ] }, "SemrushCompetitorSummary": { "type": "object", "properties": { "domain": { "type": "string", "nullable": true, "example": "gocardless.com" }, "relevance": { "type": "number", "nullable": true, "example": 0.16, "description": "Semrush's own similarity score, 0-1." }, "visits": { "type": "number", "nullable": true, "example": null, "description": "Frequently null on this panel — Semrush does not state it here for every rival. `/v1/semrush/competitors` returns it for all of them, along with authority score, bounce rate, time on site and all three ranks." } }, "required": [ "domain", "relevance", "visits" ] }, "SemrushTrafficJourney": { "type": "object", "properties": { "as_of": { "type": "string", "nullable": true }, "incoming": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushJourneyItem" }, "description": "The top 5 sources visitors arrive from, including `Direct` and search channels." }, "outgoing": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushJourneyItem" }, "description": "The top 5 destinations visitors leave for." } }, "required": [ "as_of", "incoming", "outgoing" ] }, "SemrushJourneyItem": { "type": "object", "properties": { "source": { "type": "string", "nullable": true, "example": "google.comGoogle organic", "description": "Semrush's own label. A channel is written ``; `Direct` is a bucket rather than a host." }, "domain": { "type": "string", "nullable": true, "example": "grok.com", "description": "Non-null only when the source has a Semrush page of its own, which is exactly when it is a valid `domain` for `/v1/semrush/website`. Published as its own field so a caller never has to parse `source`." }, "visits": { "type": "number", "nullable": true, "example": 45929701 }, "previous_visits": { "type": "number", "nullable": true, "example": 38183339 }, "share": { "type": "number", "nullable": true, "example": 0.44101063, "description": "A fraction of the domain's total traffic." } }, "required": [ "source", "domain", "visits", "previous_visits", "share" ] }, "SemrushAiTraffic": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushAiSource" }, "description": "Referral traffic from individual AI assistants, with 6 months of history each — ChatGPT, Claude, Gemini, Perplexity, Grok and coding agents. This is the newest thing on the page and it is free." }, "other_traffic": { "type": "number", "nullable": true, "example": 149279270 }, "other_share": { "type": "number", "nullable": true, "example": 0.93069 } }, "required": [ "items", "other_traffic", "other_share" ] }, "SemrushAiSource": { "type": "object", "properties": { "source": { "type": "string", "nullable": true, "example": "chatgpt.com" }, "name": { "type": "string", "nullable": true, "example": "ChatGPT" }, "traffic": { "type": "number", "nullable": true, "example": 798467 }, "share": { "type": "number", "nullable": true, "example": 0.00498 }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushAiHistoryRow" } } }, "required": [ "source", "name", "traffic", "share", "history" ] }, "SemrushAiHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true }, "value": { "type": "number", "nullable": true } }, "required": [ "date", "value" ] }, "SemrushCompetitorsResponse": { "type": "object", "nullable": true, "properties": { "requested_domain": { "type": "string", "example": "stripe.com" }, "domain": { "type": "string", "nullable": true, "example": "gocardless.com" }, "as_of": { "type": "string", "nullable": true, "example": "2026-07-15" }, "database": { "type": "string", "nullable": true, "example": "US" }, "visits": { "$ref": "#/components/schemas/SemrushMetric" }, "authority_score": { "$ref": "#/components/schemas/SemrushMetric" }, "bounce_rate": { "$ref": "#/components/schemas/SemrushMetric" }, "pages_per_visit": { "$ref": "#/components/schemas/SemrushMetric" }, "time_on_site_seconds": { "$ref": "#/components/schemas/SemrushMetric" }, "ranks": { "$ref": "#/components/schemas/SemrushRanks" }, "url": { "type": "string", "example": "https://www.semrush.com/website/stripe.com/competitors/", "description": "The public Semrush page these figures come from." }, "updated_at": { "type": "string", "nullable": true, "example": "2026-08-12" }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushCompetitorProfile" }, "description": "The rivals Semrush names, each with the subject's own metric set so the two are directly comparable. Empty array — never null — when Semrush names none." }, "count": { "type": "number", "example": 3, "description": "How many rivals are in this response. Counted from what you received, never copied from a figure Semrush stated. Measured between 3 and 7 depending on the domain." }, "usage_note": { "type": "string", "example": "This is not a longer version of the competitors block on /v1/semrush/website. That block gives a name, a relevance score and a visits figure that is frequently null; this gives each rival the full metric set, so the rivals are directly comparable with the subject." } }, "required": [ "requested_domain", "domain", "as_of", "database", "visits", "authority_score", "bounce_rate", "pages_per_visit", "time_on_site_seconds", "ranks", "url", "updated_at", "competitors", "count", "usage_note" ] }, "SemrushCompetitorProfile": { "type": "object", "properties": { "domain": { "type": "string", "nullable": true, "example": "gocardless.com" }, "as_of": { "type": "string", "nullable": true, "example": "2026-07-15" }, "database": { "type": "string", "nullable": true, "example": "US" }, "visits": { "$ref": "#/components/schemas/SemrushMetric" }, "authority_score": { "$ref": "#/components/schemas/SemrushMetric" }, "bounce_rate": { "$ref": "#/components/schemas/SemrushMetric" }, "pages_per_visit": { "$ref": "#/components/schemas/SemrushMetric" }, "time_on_site_seconds": { "$ref": "#/components/schemas/SemrushMetric" }, "ranks": { "$ref": "#/components/schemas/SemrushRanks" } }, "required": [ "domain", "as_of", "database", "visits", "authority_score", "bounce_rate", "pages_per_visit", "time_on_site_seconds", "ranks" ] }, "SemrushTrendingResponse": { "type": "object", "nullable": true, "properties": { "requested_country": { "type": "string", "example": "us" }, "requested_category": { "type": "string", "example": "finance" }, "country": { "type": "string", "nullable": true, "example": "us" }, "category": { "type": "string", "nullable": true, "example": "finance" }, "category_id": { "type": "number", "nullable": true, "example": 35, "description": "Semrush's own numeric id for the industry." }, "url": { "type": "string", "example": "https://www.semrush.com/trending-websites/us/finance" }, "as_of": { "type": "string", "nullable": true, "example": "2026-07-01" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushTrendingRow" }, "description": "The ranked domains, in Semrush's own order." }, "count": { "type": "number", "example": 100, "description": "How many rows are in this response — counted, never copied. It is 100 for every country and industry measured, and there is no page 2: `page`, `p`, `offset` and `limit` were each sent and each returned the same 100 domains in the same order." }, "total_traffic": { "type": "number", "nullable": true, "example": 4038663770, "description": "Total monthly visits across this country and industry." }, "total_traffic_change_percent": { "type": "number", "nullable": true, "example": 1.39 }, "total_traffic_history": { "type": "array", "items": { "$ref": "#/components/schemas/SemrushTrendingHistoryRow" }, "description": "12 months of that total." }, "available_countries": { "type": "array", "items": { "type": "string" }, "example": [ "ad", "ae", "af" ], "description": "Every country code this endpoint accepts, 240 of them, read off Semrush's own page rather than hardcoded — so it is current by construction. One call discovers the whole vocabulary." }, "available_categories": { "type": "array", "items": { "type": "string" }, "example": [ "accounting-and-auditing", "adult", "advertising-and-marketing" ], "description": "Every industry slug this endpoint accepts, 111 of them, on the same terms as `available_countries`." }, "usage_note": { "type": "string", "example": "A fixed top 100. There is no page 2: page, p, offset and limit were each sent and each returned the same 100 domains in the same order. available_countries and available_categories are Semrush's own vocabularies, read off the page, so the valid inputs are always current." } }, "required": [ "requested_country", "requested_category", "country", "category", "category_id", "url", "as_of", "items", "count", "total_traffic", "total_traffic_change_percent", "total_traffic_history", "available_countries", "available_categories", "usage_note" ] }, "SemrushTrendingRow": { "type": "object", "properties": { "rank": { "type": "number", "example": 1, "description": "Position in the ranking, counted from the order Semrush returned rather than read off a field." }, "domain": { "type": "string", "nullable": true, "example": "yahoo.com" }, "visits": { "type": "number", "nullable": true, "example": 1246948154 }, "desktop_visits": { "type": "number", "nullable": true }, "mobile_visits": { "type": "number", "nullable": true }, "desktop_share": { "type": "number", "nullable": true, "example": 42.1, "description": "A PERCENTAGE on this endpoint (42.1 means 42.1%), unlike the fractions on `/v1/semrush/website`. Republished in Semrush's own units rather than silently rescaled." }, "mobile_share": { "type": "number", "nullable": true }, "change_month_percent": { "type": "number", "nullable": true, "example": 9.225444, "description": "Month-on-month change, as a percentage." }, "change_year_percent": { "type": "number", "nullable": true, "example": -1.5 }, "top_traffic_source": { "type": "string", "nullable": true, "example": "direct", "description": "Semrush's own label — `direct`, `search`, `social`." } }, "required": [ "rank", "domain", "visits", "desktop_visits", "mobile_visits", "desktop_share", "mobile_share", "change_month_percent", "change_year_percent", "top_traffic_source" ] }, "SemrushTrendingHistoryRow": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2025-08-01" }, "traffic": { "type": "number", "nullable": true, "example": 250427787239 } }, "required": [ "date", "traffic" ] }, "G2CategoryResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "crm" }, "url": { "type": "string", "example": "https://www.g2.com/categories/crm" }, "page": { "type": "number", "example": 1 }, "page_size": { "type": "number", "example": 15, "description": "Fifteen, measured off G2's own `numberOfItems`." }, "name": { "type": "string", "nullable": true, "example": "Best CRM Software" }, "description": { "type": "string", "nullable": true, "description": "G2's own description of the category." }, "date_modified": { "type": "string", "nullable": true, "example": "2026-06-03T07:26:07-05:00", "description": "When G2 last revised the category page." }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/G2CategoryProduct" }, "description": "The products on this page, in G2's order. An empty array is a real answer; a category that does not exist returns `null` instead." }, "count": { "type": "number", "example": 15, "description": "How many products are in `products`. Fewer than `page_size` means this is the last page." }, "stated_count": { "type": "number", "nullable": true, "example": 15, "description": "G2's own count for this page. It agrees with `count` today; a difference would be the finding, which is why both are published." }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number", "nullable": true }, "name": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "position", "name", "url" ] }, "description": "The category's place in G2's taxonomy, root first — the parent categories a broader walk would start from." }, "related_categories": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true, "description": "Ready to pass straight back to this endpoint." } }, "required": [ "url", "slug" ] }, "description": "Sibling and parent categories G2 links from this one." }, "faq": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "nullable": true }, "answer": { "type": "string", "nullable": true } }, "required": [ "question", "answer" ] }, "description": "G2's own review-derived buying questions for this category — prose that appears nowhere else on the site." }, "usage_note": { "type": "string", "example": "Each product's slug is the exact value /v1/g2/reviews takes. Pages hold 15 products and do not overlap; G2 states no total, so walk until a page returns fewer than 15." } }, "required": [ "slug", "url", "page", "page_size", "name", "description", "date_modified", "products", "count", "stated_count", "breadcrumbs", "related_categories", "faq", "usage_note" ] }, "G2CategoryProduct": { "type": "object", "properties": { "position": { "type": "number", "nullable": true, "example": 1, "description": "1-based rank within this page, as G2 ordered it." }, "name": { "type": "string", "nullable": true, "example": "Pipedrive", "description": "The product's display name." }, "slug": { "type": "string", "nullable": true, "example": "pipedrive", "description": "The exact value `/v1/g2/reviews` takes. This is what makes the two endpoints compose: walk a category here, then pull any product's reviews there, without ever constructing a URL." }, "url": { "type": "string", "nullable": true, "example": "https://www.g2.com/products/pipedrive/reviews", "description": "The product's page on G2." }, "image": { "type": "string", "nullable": true, "example": "https://images.g2crowd.com/uploads/product/image/pipedrive.png", "description": "The product's logo, as G2 hosts it." }, "application_category": { "type": "string", "nullable": true, "example": "BusinessApplication", "description": "schema.org's coarse application category." }, "rating": { "type": "object", "nullable": true, "properties": { "value": { "type": "number", "nullable": true, "example": 8.7, "description": "The rating, on the scale `best_rating` names. Not rescaled." }, "best_rating": { "type": "number", "nullable": true, "example": 10, "description": "The top of the scale `value` is on — 10 for a product aggregate and 5 for an individual review, on the same page." }, "worst_rating": { "type": "number", "nullable": true, "example": 0, "description": "The bottom of the scale." }, "review_count": { "type": "number", "nullable": true, "example": 3118, "description": "How many reviews the rating is computed from, across the whole product — not how many are on this page." }, "rating_count": { "type": "number", "nullable": true, "example": 3118, "description": "How many ratings the average is computed from, where G2 states it separately from `review_count`." } }, "required": [ "value", "best_rating", "worst_rating", "review_count", "rating_count" ], "description": "The product's aggregate rating and review count across all of G2 — out of 5 on a category listing." }, "liked_for": { "type": "array", "items": { "type": "string" }, "example": [ "Ease of Use", "Features", "Lead Management" ], "description": "G2's own summary of what reviewers praise, which is published on the listing and not on the product's review pages. Empty when G2 states none." }, "disliked_for": { "type": "array", "items": { "type": "string" }, "example": [ "Learning Curve", "Expensive" ], "description": "The same for what reviewers complain about. Empty when G2 states none." }, "price": { "type": "object", "nullable": true, "properties": { "currency": { "type": "string", "nullable": true, "example": "USD" }, "low": { "type": "string", "nullable": true, "example": "25", "description": "Cheapest published plan. G2 states this as a string." }, "high": { "type": "string", "nullable": true, "example": "330", "description": "Dearest published plan." }, "offer_count": { "type": "number", "nullable": true, "example": 4, "description": "How many plans G2 lists." } }, "required": [ "currency", "low", "high", "offer_count" ], "description": "The product's published price band. Null for a product G2 lists no pricing for, which is common for enterprise software." } }, "required": [ "position", "name", "slug", "url", "image", "application_category", "rating", "liked_for", "disliked_for", "price" ] }, "G2ReviewsResponse": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string", "example": "pipedrive" }, "url": { "type": "string", "example": "https://www.g2.com/products/pipedrive/reviews" }, "page": { "type": "number", "example": 1, "description": "The page that was requested." }, "page_size": { "type": "number", "example": 10 }, "order": { "type": "string", "enum": [ "g2_default", "most_recent", "most_helpful", "highest_rated", "lowest_rated" ], "example": "g2_default" }, "product": { "$ref": "#/components/schemas/G2ReviewsProduct" }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/G2Review" }, "description": "This page's reviews, in G2's order. An empty array is a real answer; a product that does not exist returns `null` instead." }, "count": { "type": "number", "example": 10 }, "current_page": { "type": "number", "nullable": true, "example": 1, "description": "The page G2 says it served, read from its own pagination control. It differs from `page` exactly when G2 clamps an out-of-range request, which is the one case worth detecting." }, "next_page": { "type": "number", "nullable": true, "example": 2, "description": "The next page to ask for, or null on the last page." }, "has_more": { "type": "boolean", "example": true, "description": "Read from G2's own next control, not from this page being full. The last page of a product is usually full too." }, "ids_aligned": { "type": "boolean", "example": true, "description": "Whether every review on this page could be given its G2 id. False means the page's structured data and its markup disagreed about how many reviews it holds, so the ids are withheld — a mismatched id looks like an answer and a missing one does not." }, "usage_note": { "type": "string", "example": "review_body is G2's own reviewBody, which concatenates all three of the questions G2 asks; sections is the same prose split back into those questions. Deduplicate a walk on review id. rating.best_rating differs between the product aggregate (10) and an individual review (5) — both are G2's numbers and neither is rescaled." } }, "required": [ "slug", "url", "page", "page_size", "order", "product", "reviews", "count", "current_page", "next_page", "has_more", "ids_aligned", "usage_note" ] }, "G2ReviewsProduct": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Pipedrive" }, "categories": { "type": "array", "items": { "type": "string" }, "example": [ "CRM", "Email Marketing", "Sales Analytics" ], "description": "Every G2 category the product sits in. G2 states these as one comma-joined string; they are split here." }, "operating_system": { "type": "string", "nullable": true, "example": "Any" }, "rating": { "type": "object", "nullable": true, "properties": { "value": { "type": "number", "nullable": true, "example": 8.7, "description": "The rating, on the scale `best_rating` names. Not rescaled." }, "best_rating": { "type": "number", "nullable": true, "example": 10, "description": "The top of the scale `value` is on — 10 for a product aggregate and 5 for an individual review, on the same page." }, "worst_rating": { "type": "number", "nullable": true, "example": 0, "description": "The bottom of the scale." }, "review_count": { "type": "number", "nullable": true, "example": 3118, "description": "How many reviews the rating is computed from, across the whole product — not how many are on this page." }, "rating_count": { "type": "number", "nullable": true, "example": 3118, "description": "How many ratings the average is computed from, where G2 states it separately from `review_count`." } }, "required": [ "value", "best_rating", "worst_rating", "review_count", "rating_count" ], "description": "The product's aggregate across all of G2 — out of 10 here, which is a different scale from the per-review ratings on the same page." } }, "required": [ "name", "categories", "operating_system", "rating" ] }, "G2Review": { "type": "object", "properties": { "id": { "type": "number", "nullable": true, "example": 13260876, "description": "G2's survey-response id. Deduplicate a walk on this — it is the only stable key a review has. Null only when the page's structured data and its markup disagreed about how many reviews are on it, in which case the prose is published without an id rather than with someone else's." }, "url": { "type": "string", "nullable": true, "example": "https://www.g2.com/survey_responses/13260876", "description": "The review's permalink on G2." }, "title": { "type": "string", "nullable": true, "example": "Visual Pipelines, Helpful AI Setup, and Great Value", "description": "The reviewer's own headline." }, "review_body": { "type": "string", "nullable": true, "description": "G2's `reviewBody`: all three answers concatenated, with nothing marking the joins. Use `sections` to tell them apart." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/G2ReviewSection" }, "description": "The same prose split back into the three questions G2 asks — what the reviewer likes, what they dislike, and what problem the product solves. This is the part `review_body` throws away." }, "rating": { "type": "object", "nullable": true, "properties": { "value": { "type": "number", "nullable": true, "example": 8.7, "description": "The rating, on the scale `best_rating` names. Not rescaled." }, "best_rating": { "type": "number", "nullable": true, "example": 10, "description": "The top of the scale `value` is on — 10 for a product aggregate and 5 for an individual review, on the same page." }, "worst_rating": { "type": "number", "nullable": true, "example": 0, "description": "The bottom of the scale." }, "review_count": { "type": "number", "nullable": true, "example": 3118, "description": "How many reviews the rating is computed from, across the whole product — not how many are on this page." }, "rating_count": { "type": "number", "nullable": true, "example": 3118, "description": "How many ratings the average is computed from, where G2 states it separately from `review_count`." } }, "required": [ "value", "best_rating", "worst_rating", "review_count", "rating_count" ], "description": "This review's own rating — out of 5, not out of 10." }, "date_published": { "type": "string", "nullable": true, "example": "2026-08-13T04:22:22-05:00" }, "date_modified": { "type": "string", "nullable": true, "example": "2026-08-13T04:22:23-05:00" }, "reviewer": { "$ref": "#/components/schemas/G2Reviewer" }, "product_id": { "type": "number", "nullable": true, "example": 1619 }, "product_uuid": { "type": "string", "nullable": true, "example": "4020c23b-cfa1-43a6-a5d4-17eb3494c795" }, "vendor_id": { "type": "number", "nullable": true, "example": 1201 }, "video_review": { "type": "boolean", "nullable": true, "description": "Whether the reviewer submitted a video review." } }, "required": [ "id", "url", "title", "review_body", "sections", "rating", "date_published", "date_modified", "reviewer", "product_id", "product_uuid", "vendor_id", "video_review" ] }, "G2ReviewSection": { "type": "object", "properties": { "question": { "type": "string", "nullable": true, "example": "What do you like best about Pipedrive?", "description": "The question G2 put to the reviewer, verbatim." }, "answer": { "type": "string", "nullable": true, "example": "The pipelines give a great visual representation of ...", "description": "What the reviewer wrote in reply. G2's own disclosure line (“Review collected by and hosted on G2.com.”) is stripped, because it is not the reviewer's prose." } }, "required": [ "question", "answer" ] }, "G2Reviewer": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Gavin A.", "description": "As G2 publishes it — first name, surname initial." }, "job_title": { "type": "string", "nullable": true, "example": "Director", "description": "The reviewer's role. Not in G2's structured data; read from the page." }, "company_size": { "type": "string", "nullable": true, "example": "Small-Business (50 or fewer emp.)", "description": "The size band of the reviewer's employer — the field that makes these reviews segmentable. Also not in the structured data." }, "id": { "type": "number", "nullable": true, "example": 9033304, "description": "G2's reviewer id, for spotting repeat reviewers." }, "profile_url": { "type": "string", "nullable": true, "description": "The reviewer's G2 profile, where they have one." } }, "required": [ "name", "job_title", "company_size", "id", "profile_url" ] }, "TelegramChannelResponse": { "type": "object", "nullable": true, "properties": { "channel": { "type": "string", "example": "telegram", "description": "The username this page was read for, echoed back after cleaning — so a caller who pasted a link can see the name it resolved to." }, "url": { "type": "string", "example": "https://t.me/s/telegram", "description": "The preview page these messages came from, built from `channel`. Public: open it and you see the same posts." }, "title": { "type": "string", "example": "Telegram News", "description": "The channel's display title, which is not its username and can be changed at any time by its owner. `username` is the stable key." }, "username": { "type": "string", "nullable": true, "example": "telegram", "description": "The handle as Telegram itself states it on the page, without the `@`. Normally identical to `channel`; worth comparing if you asked under an old name." }, "description": { "type": "string", "nullable": true, "example": "The official Telegram on Telegram.", "description": "The channel's bio, with line breaks preserved. Null when it has none." }, "subscribers_display": { "type": "string", "nullable": true, "example": "9.82M", "description": "How many subscribers the channel has, as Telegram's own abbreviated string — a STRING, not a number. This is the same value as `counters.subscribers`, lifted out under a predictable name because it is the one counter almost every caller wants.\n\n`9.82M` is all Telegram publishes: there is no exact subscriber count anywhere the anonymous preview can reach. Expanding it to 9,820,000 would invent three digits the site never gave, so it is left as it arrived. Null when the channel states no subscriber counter." }, "counters": { "$ref": "#/components/schemas/TelegramChannelCounters" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/TelegramMessage" }, "description": "This page's posts, newest last, up to 20 of them. Empty array — never null — for a channel with no posts, or for a cursor past the end of the stream." }, "count": { "type": "number", "example": 20, "description": "How many messages are in this response. Counted from what you received, never copied from a figure the page printed." }, "page_size": { "type": "number", "example": 20, "description": "Messages per preview page: Telegram renders 20 and states no way to ask for more. A page with fewer than this is the boundary of the stream in the direction you are walking." }, "before": { "type": "number", "nullable": true, "example": null, "description": "The `before` cursor you sent, echoed back, or null." }, "after": { "type": "number", "nullable": true, "example": null, "description": "The `after` cursor you sent, echoed back, or null." }, "oldest_message_number": { "type": "number", "nullable": true, "example": 435, "description": "The lowest message number on this page — the oldest post you received. Null on an empty page." }, "newest_message_number": { "type": "number", "nullable": true, "example": 454, "description": "The highest message number on this page — the newest post you received. Store it between runs and pass it as `after` to collect only what has been posted since. Null on an empty page." }, "next_before": { "type": "number", "nullable": true, "example": 435, "description": "Send this back as `before` to get the next twenty older posts. It is `oldest_message_number`, and it is published as its own field because the value Telegram's cursor wants is the LOWEST number on the page you just read rather than the highest — the opposite of the usual intuition, and a fact you should never have to hold. Null when the page carried no posts to page from." }, "next_after": { "type": "number", "nullable": true, "example": 454, "description": "Send this back as `after` to get the next twenty newer posts. The mirror of `next_before`, and equal to `newest_message_number`." }, "exhausted": { "type": "boolean", "example": false, "description": "True when this page carried no messages at all, which is the only end-of-stream signal this site has. A channel is a stream: Telegram publishes no message total and no page count, so there is nothing to compare a position against.\n\nA SHORT page — fewer than 20 posts — is the boundary rather than the end: walking backwards, `before=5` returns ids 1-4 and the call after it is the empty one. Stop when this is true, or when `next_before` comes back null." } }, "required": [ "channel", "url", "title", "username", "description", "subscribers_display", "counters", "messages", "count", "page_size", "before", "after", "oldest_message_number", "newest_message_number", "next_before", "next_after", "exhausted" ] }, "TelegramChannelCounters": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "subscribers": "9.82M", "photos": "14", "videos": "225", "links": "372" }, "description": "Every counter the channel's header states, keyed by Telegram's own label — and WHICH KEYS EXIST VARIES PER CHANNEL. A channel that has never posted a video has no `videos` counter at all.\n\nThat is why this is an open map of strings rather than four fixed fields: a fixed schema would either drop a label Telegram invents next or publish a column of nulls for counters the channel does not have, and both would misreport the page. Read a key if it is there, and treat its absence as 'the channel states none' rather than as zero.\n\nValues are Telegram's abbreviated strings, unparsed, for the same reason `subscribers_display` is. Empty object — never null — when the header states no counters." }, "TelegramMessage": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "telegram/435", "description": "Telegram's own key for the post — `/`, the path of its permalink. Unique across the site; `message_number` is the half of it the cursors take." }, "message_number": { "type": "number", "nullable": true, "example": 435, "description": "The post's number inside its channel, and the value `before` and `after` take. Numbers count up from 1 at the beginning of the channel, so they order the stream as well as address it. Null only if Telegram stopped ending a post key with a number." }, "url": { "type": "string", "nullable": true, "example": "https://t.me/telegram/435", "description": "The post's permalink. Note that opening it anonymously shows the join page rather than the post — a single post is only readable through this endpoint by paging to it." }, "published_at": { "type": "string", "nullable": true, "example": "2026-04-09T07:01:44+00:00", "description": "When the post went up, as an ISO 8601 timestamp with an offset. Telegram states it in the markup as a machine-readable attribute, so this is its own value rather than a parse of the rendered '2 hours ago'." }, "views_display": { "type": "string", "nullable": true, "example": "1.56M", "description": "How many times the post was viewed, as Telegram's own abbreviated string — a STRING, not a number. `1.56M` means somewhere between 1,555,000 and 1,565,000, and Telegram publishes no exact figure anywhere a preview can reach. Expanding it here would invent three digits the site never gave, so the abbreviation is passed through and the interpretation is yours.\n\nNull on a post with no view counter, which is normal for very recent posts." }, "text": { "type": "string", "nullable": true, "example": "Hello world", "description": "The post's text, with its line breaks preserved. A Telegram post is often several lines and collapsing them would lose the author's structure, so `
` becomes a newline; HTML entities are decoded, including numeric ones such as `!`, which Telegram does write.\n\nNull — not an empty string — on a media post with no caption. Measured: a photo post carries no text node at all, and null is the honest report of that." }, "photo_url": { "type": "string", "nullable": true, "example": "https://cdn4.telesco.pe/file/photo.jpg", "description": "The post's image, on Telegram's own CDN. Null when the post carries no photo." }, "video_url": { "type": "string", "nullable": true, "example": "https://cdn4.telesco.pe/file/clip.mp4", "description": "The post's video, on Telegram's own CDN. Null when the post carries no video." }, "forwarded_from_name": { "type": "string", "nullable": true, "example": "Other Channel", "description": "The channel this post was forwarded from, when it was. The DISPLAY NAME as the preview renders it, which is not necessarily a username you can pass back to this endpoint — a channel's title and its handle are different things and the preview shows the title. Null on an original post." }, "reply_to_text": { "type": "string", "nullable": true, "example": "earlier post", "description": "The excerpt of the post being replied to, as the preview renders it — the quoted snippet, not the full original. Null when the post is not a reply." } }, "required": [ "id", "message_number", "url", "published_at", "views_display", "text", "photo_url", "video_url", "forwarded_from_name", "reply_to_text" ] }, "ZillowPropertyResponse": { "type": "object", "nullable": true, "properties": { "zpid": { "type": "string", "example": "2146999031", "description": "The id this home was read for, echoed back after cleaning — so a caller who pasted a URL can see the id it resolved to. This is the string form; `property.zpid` is Zillow's numeric copy." }, "url": { "type": "string", "example": "https://www.zillow.com/homedetails/2146999031_zpid/", "description": "The property's canonical page, built from the zpid. Public: open it and you see the same home. The address slug Zillow puts in its own links is decorative — this shorter form resolves to the same page." }, "property": { "$ref": "#/components/schemas/ZillowProperty" }, "attribution": { "$ref": "#/components/schemas/ZillowAttribution" }, "address": { "$ref": "#/components/schemas/ZillowAddress" }, "photos": { "type": "array", "items": { "type": "string" }, "example": [ "https://photos.zillowstatic.com/fp/abc-uncropped_scaled.jpg" ], "description": "Every photo of the home, largest available first, deduplicated — 61 on the sampled property. URLs only.\n\nZillow ships each photo as a tree of every generated size in both jpeg and webp; republishing that is tens of kilobytes of CDN plumbing per home, so the widest jpeg of each photo is picked and the rest dropped. Empty array — never null — on a listing with no photos." }, "photo_count": { "type": "number", "example": 61, "description": "How many photo URLs are in `photos`. Counted from what you received, never copied from a figure the page printed — `property.photo_count` is Zillow's own claim, and the two can differ when a photo arrives with no usable source." }, "reso_facts": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "The full RESO fact set for the home, republished whole and under Zillow's own key names — the one object in this response that is not renamed into this API's conventions.\n\nThat is deliberate. RESO is the real-estate industry's own interchange standard, its field names ARE the format (`bathroomsThreeQuarter`, `garageParkingCapacity`, `hasAttachedGarage`), and anything already built against an MLS feed reads them as they stand. Renaming them would break the portability that is the entire reason the object is worth having.\n\nIt is also flat and wide — around a hundred facts, of which any given listing carries a different subset — so imposing a fixed schema would mean either inventing fields nobody has seen or dropping the ones this API happened not to enumerate. Read a key if it is there.\n\nNull when the page carried no fact set." }, "price_history": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "Every price change and sale Zillow holds for the home — and it is `null` here. Use `/v1/zillow/history` to get it.\n\nNull is not 'this home has no price history'. This subtree, and the three below it, are genuinely not on the property page: the document carries `canShowPriceHistory` and `canShowTaxHistory` — permission flags saying the data exists — and not the data, and not even the string `priceHistory` anywhere in its 564,009 bytes. They are published as present keys with null values, rather than omitted, precisely so the two cases can be told apart: `null` means this response does not carry the subtree, and an empty array on `/v1/zillow/history` means Zillow has no such records.\n\n`/v1/zillow/history` takes the same `zpid` this endpoint does, and returns these four with named fields rather than as passthrough — there they have been measured. On the rare occasion a value does arrive here, it is Zillow's own rows republished unchanged." }, "tax_history": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "The home's assessed values and tax bills by year. Null here for the same reason as `price_history` — the page does not carry it — and `/v1/zillow/history` is where it lives. Null means 'not carried', never 'none exists'." }, "schools": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "The schools Zillow attaches to the home, with their ratings and distances. Null here, on the same terms as `price_history`; `/v1/zillow/history` returns them with named fields." }, "nearby_homes": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "Comparable homes near this one, each carrying a zpid `/v1/zillow/property` takes. Null here, on the same terms as `price_history`; `/v1/zillow/history` returns them narrowed to the fields that say which house it is and what it costs." } }, "required": [ "zpid", "url", "property", "attribution", "address", "photos", "photo_count", "reso_facts", "price_history", "tax_history", "schools", "nearby_homes" ] }, "ZillowProperty": { "type": "object", "properties": { "zpid": { "type": "number", "nullable": true, "example": 2146999031, "description": "Zillow's id for the home as Zillow types it — a number. The response's top-level `zpid` is the same id as a string, and that is the one to pass back to this endpoint." }, "home_status": { "type": "string", "nullable": true, "example": "FOR_SALE", "description": "Zillow's own status for the home: `FOR_SALE`, `SOLD`, `PENDING`, `OTHER` and friends. `attribution.true_status` carries the MLS's word for the same thing before Zillow mapped it." }, "home_type": { "type": "string", "nullable": true, "example": "SINGLE_FAMILY", "description": "The structure: `SINGLE_FAMILY`, `CONDO`, `TOWNHOUSE`, ..." }, "property_type": { "type": "string", "nullable": true, "example": "Single Family", "description": "Zillow's display-facing property type — the readable form of `home_type`." }, "listing_type": { "type": "string", "nullable": true, "example": "For Sale by Agent", "description": "How the home is being sold, as Zillow labels it." }, "listing_sub_type": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Zillow's flags for the kind of listing — new construction, foreclosure, for sale by owner and so on. Republished as it arrives: which flags exist varies with the listing, so a fixed object would publish nulls for the ones this home is not." }, "listing_provider": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "The syndication source Zillow credits for the listing, republished unchanged. `attribution` is the object with the agent and broker in it." }, "contingent_listing_type": { "type": "string", "nullable": true, "example": null, "description": "What the sale is contingent on, when it is. Null on a listing with no contingency." }, "foreclosure_types": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Zillow's foreclosure flags for the home, republished as they arrive. Every capture carried them empty." }, "is_preforeclosure_auction": { "type": "boolean", "nullable": true, "example": false }, "is_zillow_owned": { "type": "boolean", "nullable": true, "example": false, "description": "Whether Zillow itself is the seller." }, "is_showcase_listing": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the agent pays for Zillow's enhanced presentation." }, "is_undisclosed_address": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the address is withheld. When true, the address fields here and in `address` are partial by the seller's choice rather than by a gap in this response." }, "price": { "type": "number", "nullable": true, "example": 480000, "description": "The asking price for a live listing, or the sale price on a sold one, in `currency`. A plain number — the formatted string Zillow renders is not republished here, because a search row carries that as `price_display`." }, "currency": { "type": "string", "nullable": true, "example": "USD" }, "zestimate": { "type": "number", "nullable": true, "example": 468600, "description": "Zillow's own estimate of what the home is worth, which is a model output rather than a listed number and is stated for homes that are not for sale at all. Comparing it against `price` is the obvious use, and the gap is Zillow's opinion rather than a fact about the market." }, "rent_zestimate": { "type": "number", "nullable": true, "example": 1936, "description": "Zillow's estimated monthly rent for the home. Beside `price` it is a gross yield calculation with no third-party data needed." }, "last_sold_price": { "type": "number", "nullable": true, "example": 43000, "description": "What the home last sold for, which on the sampled property was 43,000 against a 480,000 asking price. Null when Zillow states no prior sale." }, "date_sold": { "type": "string", "nullable": true, "example": null, "description": "When the home last sold, as Zillow's own date string. `price_history` carries the full sequence of sales and price changes when it is present." }, "price_change": { "type": "number", "nullable": true, "example": -15000, "description": "The size of the most recent price change, signed — negative is a cut. Null on a listing that has not moved." }, "price_change_date": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "When the price last changed, in Zillow's machine form. Published exactly as it arrives rather than converted: nothing in the capture pinned its units, and a guess would be a wrong date that looks like a right one. Use `price_change_date_display` for the readable form." }, "price_change_date_display": { "type": "string", "nullable": true, "example": "8/1/2025", "description": "Zillow's own rendering of the same date, as a string — the half of the pair that needs no interpretation." }, "tax_annual_amount": { "type": "number", "nullable": true, "example": 3210, "description": "The annual property tax bill Zillow states for the home." }, "property_tax_rate": { "type": "number", "nullable": true, "example": 1.99, "description": "The tax rate as a percentage, as Zillow states it." }, "monthly_hoa_fee": { "type": "number", "nullable": true, "example": null, "description": "The monthly HOA fee. Null on a home with no association, which is different from a fee of zero." }, "bedrooms": { "type": "number", "nullable": true, "example": 3 }, "bathrooms": { "type": "number", "nullable": true, "example": 2, "description": "Total bathrooms. `reso_facts` breaks this down to the quarter — full, three-quarter, half and quarter baths are separate fields there." }, "living_area": { "type": "number", "nullable": true, "example": 1600, "description": "Interior area, in the unit `reso_facts` states — square feet on every US listing measured." }, "living_area_value": { "type": "number", "nullable": true, "example": 1600, "description": "Zillow's second copy of the same figure. Both are published because Zillow states both, and they have agreed on every capture." }, "lot_size": { "type": "number", "nullable": true, "example": 3125, "description": "Lot area, normally in square feet." }, "lot_area_value": { "type": "number", "nullable": true, "example": 0.07, "description": "The lot area in the unit named by `lot_area_units`, which is often acres where `lot_size` is square feet. Read the two together — the numbers are the same lot." }, "lot_area_units": { "type": "string", "nullable": true, "example": "Acres" }, "year_built": { "type": "number", "nullable": true, "example": 1911 }, "street_address": { "type": "string", "nullable": true, "example": "2114 S Trumbull Ave", "description": "The address as stated on the property record. The `address` object on the response carries the same lines plus the neighborhood, community and subdivision Zillow files the home under." }, "city": { "type": "string", "nullable": true, "example": "Chicago" }, "state": { "type": "string", "nullable": true, "example": "IL" }, "zipcode": { "type": "string", "nullable": true, "example": "60623" }, "country": { "type": "string", "nullable": true, "example": "USA" }, "county": { "type": "string", "nullable": true, "example": "Cook County", "description": "The county, which is stated here and nowhere else in this response — it is the join key for public tax and deed records." }, "latitude": { "type": "number", "nullable": true, "example": 41.84 }, "longitude": { "type": "number", "nullable": true, "example": -87.71 }, "time_zone": { "type": "string", "nullable": true, "example": "America/Chicago" }, "description": { "type": "string", "nullable": true, "example": "Beautifully updated brick two-flat ...", "description": "The listing's own description, as the agent wrote it, with its line breaks intact. Null on a listing that carries none, which is normal on sold and off-market records." }, "what_i_love": { "type": "string", "nullable": true, "example": null, "description": "The owner's own note about the home, when Zillow has one. Rare, and written by the seller rather than the agent." }, "mls_id": { "type": "string", "nullable": true, "example": "12345678", "description": "The MLS listing id, from Zillow's `mlsid` on the property record. `attribution.mls_id` is its other copy, stated beside the MLS's name — read that one if you need to know which MLS issued the id." }, "date_posted": { "type": "string", "nullable": true, "example": "2025-07-15", "description": "When the listing went up, as Zillow's own date string." }, "days_on_zillow": { "type": "number", "nullable": true, "example": 23, "description": "How long the listing has been live. Beside `page_view_count` it is the denominator: 197 views in 23 days is a different listing from 197 views in a day." }, "time_on_zillow": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "Zillow's finer-grained version of the same thing, republished as it arrives. `days_on_zillow` is the field to compute with." }, "page_view_count": { "type": "number", "nullable": true, "example": 197, "description": "How many times this listing's page has been viewed — one of three demand signals Zillow publishes to nobody. Nothing on the rendered page shows it, no MLS feed carries it, and it is per-listing rather than per-market: it says how much attention this specific home is getting.\n\nRead it against `days_on_zillow` (197 views over 23 days on the sampled home) and against `favorite_count`, which is the same audience one step further down the funnel." }, "favorite_count": { "type": "number", "nullable": true, "example": 20, "description": "How many people have saved the listing. The second demand signal, and a stronger one than a page view — a save is a logged-in action by someone who intends to come back. Its ratio to `page_view_count` (20 of 197 on the sampled home) is a conversion rate for the listing." }, "tour_view_count": { "type": "number", "nullable": true, "example": 0, "description": "How many times the home's 3D tour has been viewed. The third demand signal. Zero, rather than null, on a listing that has a tour nobody has opened; null when Zillow states no counter at all." }, "photo_count": { "type": "number", "nullable": true, "example": 61, "description": "Zillow's own count of the home's photos, which is its claim rather than a count of what arrived. The response's top-level `photo_count` is counted from the `photos` array actually returned; compare the two if the difference matters to you." }, "has_virtual_tour": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the listing carries an approved third-party virtual tour. `tour_view_count` is how many times it has been opened." } }, "required": [ "zpid", "home_status", "home_type", "property_type", "listing_type", "listing_sub_type", "listing_provider", "contingent_listing_type", "foreclosure_types", "is_preforeclosure_auction", "is_zillow_owned", "is_showcase_listing", "is_undisclosed_address", "price", "currency", "zestimate", "rent_zestimate", "last_sold_price", "date_sold", "price_change", "price_change_date", "price_change_date_display", "tax_annual_amount", "property_tax_rate", "monthly_hoa_fee", "bedrooms", "bathrooms", "living_area", "living_area_value", "lot_size", "lot_area_value", "lot_area_units", "year_built", "street_address", "city", "state", "zipcode", "country", "county", "latitude", "longitude", "time_zone", "description", "what_i_love", "mls_id", "date_posted", "days_on_zillow", "time_on_zillow", "page_view_count", "favorite_count", "tour_view_count", "photo_count", "has_virtual_tour" ], "description": "The home itself: price, structure, location, listing metadata and the three demand signals. Zillow's own property object runs to 99 keys, of which 54 describe the property — the rest is ad targeting, CTA configuration, experiment treatments and tour-scheduling state for a logged-in user, none of which means anything to a caller of this API and none of which is published." }, "ZillowAttribution": { "type": "object", "properties": { "agent_name": { "type": "string", "nullable": true, "example": "Luis Ortiz", "description": "The listing agent's name, and the start of the group that makes this endpoint worth calling. Nothing on the rendered Zillow page shows the fields in this object; they ride in the page's own data blob." }, "agent_email": { "type": "string", "nullable": true, "example": null, "description": "The listing agent's email address. Null when the listing does not carry one, which is common — an agent's phone is stated far more often than their email." }, "agent_phone": { "type": "string", "nullable": true, "example": "708-990-4079", "description": "The listing agent's phone number, as the listing states it — Zillow's own `agentPhoneNumber`, unformatted and unparsed. Digits, separators and extensions are the MLS's spelling rather than a normalised form, because normalising a phone number requires assuming a country and this field is what the agent typed." }, "broker_name": { "type": "string", "nullable": true, "example": "RE/MAX Partners", "description": "The brokerage the listing agent works for." }, "broker_phone": { "type": "string", "nullable": true, "example": null, "description": "The brokerage's own number, when the listing states one." }, "mls_id": { "type": "string", "nullable": true, "example": "12345678", "description": "The listing's id in its MLS, which is the key that joins this record to an MLS feed or a brokerage's own system. Note that `property.mls_id` is Zillow's other copy of this — the two agree on every capture, and both are published because Zillow states both." }, "mls_name": { "type": "string", "nullable": true, "example": "MRED as distributed by MLS GRID", "description": "Which MLS the listing came through, in that feed's own words. Worth reading alongside `mls_id`: an id is only unique inside the MLS that issued it." }, "listing_agreement": { "type": "string", "nullable": true, "example": null, "description": "The type of agreement the listing is held under, in the MLS's vocabulary (an exclusive right to sell, and so on)." }, "true_status": { "type": "string", "nullable": true, "example": null, "description": "The MLS's own status word for the listing, which is not always the same thing as `property.home_status` — Zillow maps a long tail of feed statuses onto its own small set, and this is the value before that mapping." }, "listing_attribution_contact": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Zillow's own attribution contact field, republished exactly as it arrives. It was empty on every capture, so there is no measured shape to rename it into — the named fields above are the ones to rely on." } }, "required": [ "agent_name", "agent_email", "agent_phone", "broker_name", "broker_phone", "mls_id", "mls_name", "listing_agreement", "true_status", "listing_attribution_contact" ], "description": "Who is selling the home and how to reach them — the listing agent's name, email and phone, the brokerage, and the MLS the listing came through. None of this is rendered on the Zillow page; it rides in the page's own data blob." }, "ZillowAddress": { "type": "object", "properties": { "street_address": { "type": "string", "nullable": true, "example": "2114 S Trumbull Ave", "description": "The street line, as Zillow files it." }, "city": { "type": "string", "nullable": true, "example": "Chicago" }, "state": { "type": "string", "nullable": true, "example": "IL" }, "zipcode": { "type": "string", "nullable": true, "example": "60623" }, "neighborhood": { "type": "string", "nullable": true, "example": null, "description": "Zillow's neighborhood for the home. Frequently null — it is stated for the areas Zillow has drawn a boundary around and omitted elsewhere, so null means 'Zillow names none' rather than 'no neighborhood'." }, "community": { "type": "string", "nullable": true, "example": null }, "subdivision": { "type": "string", "nullable": true, "example": null } }, "required": [ "street_address", "city", "state", "zipcode", "neighborhood", "community", "subdivision" ], "description": "The home's address, plus the neighborhood, community and subdivision Zillow files it under. The street lines repeat what `property` carries; the last three are stated only here." }, "ZillowHistoryResponse": { "type": "object", "nullable": true, "properties": { "requested_zpid": { "type": "string", "example": "2146999031", "description": "The id this history was read for, echoed back after cleaning — so a caller who pasted a URL can see the id it resolved to." }, "zpid": { "type": "number", "nullable": true, "example": 2146999031, "description": "The id Zillow answered with, as a number, straight out of the payload. Worth comparing against `requested_zpid` on a property that has been merged or re-keyed: they have matched on every measured call, and a disagreement would mean Zillow served a different home than the one asked for." }, "url": { "type": "string", "example": "https://www.zillow.com/homedetails/2146999031_zpid/", "description": "The property's canonical page, built from the id." }, "address": { "$ref": "#/components/schemas/ZillowShortAddress" }, "price_history": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ZillowPriceEvent" }, "description": "Every price event Zillow holds for the home — listings, price changes and sales, newest first, with the rate of each change.\n\nAn empty array means the property has no recorded price events, and that is a real answer. Measured: one San Francisco property returned 0 price events beside 25 tax rows, while a Chicago property returned 22. Do not read `[]` as a failure.\n\nAnd `[]` here is not the `null` `/v1/zillow/property` returns. That null means 'that response does not carry this field'; this empty array means 'Zillow has no such records for this home'. Null here is the rarer case where this payload itself omitted the subtree." }, "tax_history": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ZillowTaxEvent" }, "description": "The assessed value and tax bill by year, with the rate each moved. 26 rows on a measured Chicago property, 25 on a San Francisco one.\n\nEmpty array means the property has no recorded tax rows; null means this payload did not carry the subtree. See `price_history` for the same distinction stated in full." }, "schools": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ZillowSchool" }, "description": "The schools Zillow attaches to the home, with rating, grade range, distance and whether the home is assigned to them. Two to three rows on every property measured.\n\nEmpty array means Zillow lists none; null means this payload did not carry the subtree." }, "nearby_homes": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ZillowNearbyHome" }, "description": "Comparable homes near this one, each with the id that fetches it. Narrowed to the fields that say which house it is and what it costs — a nearby home arrives shaped like a whole property record, most of which is rendering state for a card.\n\nEmpty array means Zillow lists none; null means this payload did not carry the subtree. Read each row's `home_status` before comparing prices: the set mixes for-sale and sold homes." }, "graphql_errors": { "type": "array", "nullable": true, "items": { "nullable": true }, "example": [ { "message": "Failed to fetch visualizations" } ], "description": "Errors Zillow reported alongside the data — and a non-empty array here does NOT mean the response failed.\n\nThis is the field most likely to be misread, so it is worth being blunt: every measured response carried `[{\"message\": \"Failed to fetch visualizations\"}]` while also carrying 22 price events and 26 tax rows. GraphQL returns partial data beside partial errors as a matter of course, so treating any error as fatal would discard every response this endpoint has ever produced.\n\nIt is published so you can see what Zillow said, and it drives nothing: no status code, no suppression of the data. Judge the four subtrees on their own contents. A response that genuinely failed does not arrive here at all — it arrives as an error.\n\nRepublished exactly as Zillow ships it. Null when it reported none." }, "usage_note": { "type": "string", "example": "An empty list here means the property has no such records; /zillow/property returns null for these fields instead, meaning that response does not carry them. Each nearby home's zpid is the exact value /zillow/property takes.", "description": "The two things a caller of this endpoint has to know, carried in the body as well as in these docs: what an empty list means here against what null means on `/v1/zillow/property`, and that each nearby home's id feeds the property endpoint verbatim." } }, "required": [ "requested_zpid", "zpid", "url", "address", "price_history", "tax_history", "schools", "nearby_homes", "graphql_errors", "usage_note" ] }, "ZillowShortAddress": { "type": "object", "properties": { "street_address": { "type": "string", "nullable": true, "example": "2114 S Trumbull Ave" }, "city": { "type": "string", "nullable": true, "example": "Chicago" }, "state": { "type": "string", "nullable": true, "example": "IL" }, "zipcode": { "type": "string", "nullable": true, "example": "60623" } }, "required": [ "street_address", "city", "state", "zipcode" ], "description": "The address of the property this history belongs to, which is the check that it is the right one. It carries four lines rather than the seven `/v1/zillow/property` returns, because that is what this payload states — see `ZillowAddress` for the fuller form." }, "ZillowPriceEvent": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2025-08-01", "description": "The day the event happened, as Zillow's own date string." }, "time": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "Zillow's machine form of the same moment, republished rather than parsed — nothing in the capture pinned its units, and `date` is the half that needs no interpretation." }, "price": { "type": "number", "nullable": true, "example": 480000, "description": "The price at this event, in the property's currency." }, "event": { "type": "string", "nullable": true, "example": "Price change", "description": "What happened: `\"Listed for sale\"`, `\"Price change\"` and `\"Sold\"` are the values measured. Treated as an open string rather than an enum — Zillow files a long tail of MLS events through here, and refusing an unmeasured one would drop a real row." }, "price_change_rate": { "type": "number", "nullable": true, "example": -0.03, "description": "The change against the previous event, as a rate rather than a percentage — `-0.03` is a 3% cut. Zillow's own number." }, "source": { "type": "string", "nullable": true, "example": "MLS #12345678", "description": "Where Zillow got the event, in its own words." } }, "required": [ "date", "time", "price", "event", "price_change_rate", "source" ] }, "ZillowTaxEvent": { "type": "object", "properties": { "time": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "The tax year, in Zillow's machine form. Republished as it arrives for the same reason a price event's `time` is." }, "tax_paid": { "type": "number", "nullable": true, "example": 3210, "description": "The tax bill for that year." }, "value": { "type": "number", "nullable": true, "example": 162000, "description": "The assessed value for that year, which is not the market value and not the Zestimate. An assessment is what the county taxes the home on; comparing it against `property.zestimate` is a common and useful gap, but they are different measurements." }, "tax_increase_rate": { "type": "number", "nullable": true, "example": 0.041, "description": "How much the bill moved against the previous year, as a rate." }, "value_increase_rate": { "type": "number", "nullable": true, "example": 0.055, "description": "How much the assessment moved, as a rate." } }, "required": [ "time", "tax_paid", "value", "tax_increase_rate", "value_increase_rate" ] }, "ZillowSchool": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Marshall Elementary" }, "rating": { "type": "number", "nullable": true, "example": 3, "description": "The school's rating as Zillow states it, out of 10 — a GreatSchools figure rather than one of Zillow's own. Null when it states none, which is common for private schools." }, "level": { "type": "string", "nullable": true, "example": "Elementary", "description": "`Elementary`, `Middle`, `High`, or Zillow's own wording." }, "grades": { "type": "string", "nullable": true, "example": "PK-8", "description": "The grade range the school covers, as a string." }, "distance": { "type": "number", "nullable": true, "example": 0.4, "description": "Distance from the property, in miles." }, "assigned": { "type": "boolean", "nullable": true, "example": null, "description": "Whether this school is the one the property is assigned to, rather than merely near it — the distinction a buyer actually cares about. Frequently null: Zillow states it only where the district publishes attendance boundaries it trusts, and null means it does not say rather than 'not assigned'." }, "link": { "type": "string", "nullable": true, "example": "https://www.greatschools.org/example", "description": "Zillow's link to the school's profile." } }, "required": [ "name", "rating", "level", "grades", "distance", "assigned", "link" ] }, "ZillowNearbyHome": { "type": "object", "properties": { "zpid": { "type": "string", "nullable": true, "example": "2077663766", "description": "The nearby home's own id, and the exact value `/v1/zillow/property` takes. So a comparables set is not a dead end: every home here can be fetched in full, with its own listing agent and its own demand signals, without constructing a URL.\n\nPublished as a string, which is the form the property endpoint takes — Zillow types it as a number in this payload." }, "url": { "type": "string", "nullable": true, "example": "https://www.zillow.com/homedetails/2077663766_zpid/", "description": "The nearby home's page, made absolute. You do not need it to fetch the home: pass `zpid` to `/v1/zillow/property`." }, "price": { "type": "number", "nullable": true, "example": 415000 }, "currency": { "type": "string", "nullable": true, "example": "USD" }, "home_status": { "type": "string", "nullable": true, "example": "SOLD", "description": "Read this before treating the set as comparables. Zillow mixes for-sale, sold and off-market homes into `nearby_homes`, so a price here can be an asking price or a sale price depending on the row." }, "home_type": { "type": "string", "nullable": true, "example": "SINGLE_FAMILY" }, "bedrooms": { "type": "number", "nullable": true, "example": 3 }, "bathrooms": { "type": "number", "nullable": true, "example": 2 }, "living_area": { "type": "number", "nullable": true, "example": 1600 }, "living_area_value": { "type": "number", "nullable": true, "example": 1600 }, "lot_size": { "type": "number", "nullable": true, "example": 3125 }, "latitude": { "type": "number", "nullable": true, "example": 41.8442 }, "longitude": { "type": "number", "nullable": true, "example": -87.7128 }, "zestimate": { "type": "number", "nullable": true, "example": 402100, "description": "Zillow's estimate for the nearby home." }, "last_sold_price": { "type": "number", "nullable": true, "example": 380000 }, "address": { "allOf": [ { "$ref": "#/components/schemas/ZillowShortAddress" }, { "description": "The nearby home's address, as far as Zillow states it." } ] } }, "required": [ "zpid", "url", "price", "currency", "home_status", "home_type", "bedrooms", "bathrooms", "living_area", "living_area_value", "lot_size", "latitude", "longitude", "zestimate", "last_sold_price", "address" ] }, "ZillowSearchResponse": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "example": "san-francisco-ca", "description": "The region slug this page was read for, echoed back after cleaning — so a caller who pasted a URL can see the slug it resolved to." }, "status": { "type": "string", "example": "for_sale", "description": "The `status` filter this page was read under, echoed back." }, "page": { "type": "number", "example": 1, "description": "The page number this response is, echoed back." }, "url": { "type": "string", "example": "https://www.zillow.com/san-francisco-ca/", "description": "The Zillow page these results came from, built from `region`, `status` and `page`. Public: open it and you see the same listings." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ZillowSearchResult" }, "description": "This page's listings, up to 41 of them, in Zillow's own order. Empty array — never null — for a region with no matching listings." }, "count": { "type": "number", "example": 41, "description": "How many listings are in this response. Counted from what you received, never copied from a figure the page printed." }, "page_size": { "type": "number", "example": 41, "description": "41 listings a page — Zillow's own `resultsPerPage`, an odd number rather than a rounding of 40. Taken from the live page's own statement of it before falling back to 41, so an offset computed from this field stays right if Zillow changes it." }, "total_results": { "type": "number", "nullable": true, "example": 773, "description": "How many properties match — which is NOT how many you can reach. Read it with `total_pages` and `results_are_capped` before sizing a walk from it.\n\nMeasured on San Francisco: `for_sale` reports 773 matches over 19 pages (19 x 41 = 779, consistent), while `sold` reports 18,802 matches over 20 pages — 820 reachable. Dividing this number by `page_size` on a sold listing asks for page 459 of something that stops at 20." }, "total_pages": { "type": "number", "nullable": true, "example": 19, "description": "How many pages Zillow will actually hand over for this region — the number to walk by. Never more than 20. It comes from Zillow's own page count, so the last page is normally short rather than exactly full." }, "max_browsable_pages": { "type": "number", "example": 20, "description": "The ceiling Zillow puts on paging any region, regardless of how many properties match: 20 pages, or 820 listings. Published as its own field so a walk can be planned against it rather than discovering it by asking for a page that does not exist. `page` is refused above this number." }, "results_are_capped": { "type": "boolean", "nullable": true, "example": false, "description": "True when this region holds more matching properties than paging can reach — that is, when `total_results` exceeds `total_pages x page_size`.\n\nIt is `true` for San Francisco `sold` (18,802 matches, 820 reachable) and `false` for the same region `for_sale` (773 matches, 779 reachable). When it is true, what you are walking is a sample of the matching set rather than an enumeration of it, and no number of requests through this endpoint will change that — Zillow's public sitemaps are the surface that holds the whole population.\n\nNull when Zillow stated no page count to compare against." }, "has_more": { "type": "boolean", "nullable": true, "example": true, "description": "Whether a page after this one exists, computed as `page < total_pages` — from Zillow's own page count rather than from whether this page came back full. Null when Zillow stated no page count.\n\nIt says nothing about whether the region has been exhausted: see `results_are_capped` for that." }, "next_page": { "type": "number", "nullable": true, "example": 2, "description": "The page number to ask for next, or null when there is nothing left to ask for. Null at the last page Zillow states, and null at page 20 whatever Zillow states — so a loop that stops when this is null never asks for a page beyond the browse cap." }, "next_url": { "type": "string", "nullable": true, "example": "https://www.zillow.com/san-francisco-ca/2_p/", "description": "Zillow's own link to the next page, made absolute. It is the source of the `2_p` page shape this API builds its own URLs with, published so the paging shape never has to be guessed. You do not need it: send `next_page` back as `page`." }, "region_details": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Zillow's own metadata for the region — its map bounds and its region ids — republished exactly as it arrives. This is a different thing from `region`, which is the slug string you sent and page with: one is the key, this is what Zillow resolved the key to.\n\nCarries `regionBounds` (the north/south/east/west box Zillow drew around the region) and `regionInfo` (its `regionId` and type). Both are selected rather than required, so the object can be `{}` on a region page that states neither. Not renamed into fields, because no capture has pinned a stable shape for it." }, "query_state": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Zillow's internal search state for this page — the map bounds, filters and sort it resolved the region to — republished exactly as it arrives. It is the object Zillow's own front end round-trips through its URL, so it is the place to look for what a region actually resolved to. No capture pinned a stable field list, so it is not renamed into fields nobody has seen." }, "usage_note": { "type": "string", "example": "Each result's zpid is the exact value /zillow/property takes. total_results is how many properties match; total_pages is how many you can actually reach, and on sold listings they differ by more than 20x.", "description": "The two sentences a caller of this endpoint has to know, carried in the body as well as in these docs: each row's `zpid` feeds `/v1/zillow/property` verbatim, and `total_results` and `total_pages` are different questions." } }, "required": [ "region", "status", "page", "url", "results", "count", "page_size", "total_results", "total_pages", "max_browsable_pages", "results_are_capped", "has_more", "next_page", "next_url", "region_details", "query_state", "usage_note" ] }, "ZillowSearchResult": { "type": "object", "properties": { "zpid": { "type": "string", "nullable": true, "example": "2146999031", "description": "Zillow's id for the home, and the exact value `/v1/zillow/property` takes as its `zpid`. This is what makes the two endpoints compose: walk a region here, then pull each home's agent contact details and demand signals there, without ever constructing a URL.\n\nPublished as a string, which is the form the property endpoint takes. Null only if Zillow stopped keying a row by zpid — the whole page is refused upstream when no row on it carries one, because that is a renamed key rather than a region of anonymous listings." }, "url": { "type": "string", "nullable": true, "example": "https://www.zillow.com/homedetails/2146999031_zpid/", "description": "The home's page, made absolute — Zillow states it as a path. You do not need it to fetch the home: pass `zpid` to `/v1/zillow/property`." }, "price": { "type": "number", "nullable": true, "example": 480000, "description": "The listed price as a number, from Zillow's own `unformattedPrice` — the field to sort and filter on. `price_display` is the same number as Zillow renders it." }, "price_display": { "type": "string", "nullable": true, "example": "$480,000", "description": "Zillow's own formatted price string, including the `/mo` and `+` decorations it sometimes adds. A string — compute with `price`." }, "bedrooms": { "type": "number", "nullable": true, "example": 3 }, "bathrooms": { "type": "number", "nullable": true, "example": 2 }, "living_area": { "type": "number", "nullable": true, "example": 1600, "description": "Interior area in square feet, from the row's `area`." }, "address": { "type": "string", "nullable": true, "example": "2114 S Trumbull Ave, Chicago, IL 60623", "description": "The full one-line address as Zillow renders it in the results list. The four fields below are the same address split into parts." }, "street_address": { "type": "string", "nullable": true, "example": "2114 S Trumbull Ave" }, "city": { "type": "string", "nullable": true, "example": "Chicago" }, "state": { "type": "string", "nullable": true, "example": "IL" }, "zipcode": { "type": "string", "nullable": true, "example": "60623" }, "latitude": { "type": "number", "nullable": true, "example": 41.84, "description": "Lifted out of the row's `latLong` object so a result can be mapped without unpacking a nested pair." }, "longitude": { "type": "number", "nullable": true, "example": -87.71 }, "status_text": { "type": "string", "nullable": true, "example": "House for sale", "description": "Zillow's rendered status label for the row." }, "status_type": { "type": "string", "nullable": true, "example": "FOR_SALE", "description": "The machine form of the same status. Note that a `status=sold` search returns rows whose type says so — the parameter filters the listing, and this reports what Zillow says each row is." }, "marketing_status": { "type": "string", "nullable": true, "example": "For Sale", "description": "Zillow's simplified marketing status code for the row." }, "raw_home_status": { "type": "string", "nullable": true, "example": "ForSale", "description": "The unmapped status straight from the feed, before Zillow simplified it." }, "broker_name": { "type": "string", "nullable": true, "example": "RE/MAX Partners", "description": "The brokerage on the listing — the only piece of attribution a search row carries. The agent's name, email and phone are on the property record: fetch the row's `zpid` through `/v1/zillow/property` and read `attribution`." }, "image_url": { "type": "string", "nullable": true, "example": "https://photos.zillowstatic.com/fp/abc-p_e.jpg", "description": "The row's thumbnail. `/v1/zillow/property` returns every photo of the home at full width." }, "has_image": { "type": "boolean", "nullable": true, "example": true }, "is_zillow_owned": { "type": "boolean", "nullable": true, "example": false }, "has_open_house": { "type": "boolean", "nullable": true, "example": false }, "open_house_start": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "When the next open house starts, in Zillow's own machine form, republished rather than parsed — nothing in the capture pinned its units, and a guessed timestamp is a wrong date that reads like a right one. `open_house_description` is the readable half." }, "open_house_end": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "description": "When it ends, on the same terms as `open_house_start`." }, "open_house_description": { "type": "string", "nullable": true, "example": "Sat 1-3pm", "description": "Zillow's own rendering of the open-house window." }, "has_3d_model": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the home has a 3D tour. `property.tour_view_count` on the detail record is how many times it has been opened." }, "has_video": { "type": "boolean", "nullable": true, "example": false }, "is_featured_listing": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the row is a paid placement. Worth reading before treating the result order as a ranking." }, "is_undisclosed_address": { "type": "boolean", "nullable": true, "example": false }, "content_type": { "type": "string", "nullable": true, "example": "property", "description": "What kind of card the row is. Zillow mixes builder communities and other card types into a results list, and this is how it names them." } }, "required": [ "zpid", "url", "price", "price_display", "bedrooms", "bathrooms", "living_area", "address", "street_address", "city", "state", "zipcode", "latitude", "longitude", "status_text", "status_type", "marketing_status", "raw_home_status", "broker_name", "image_url", "has_image", "is_zillow_owned", "has_open_house", "open_house_start", "open_house_end", "open_house_description", "has_3d_model", "has_video", "is_featured_listing", "is_undisclosed_address", "content_type" ] }, "ZillowSitemapResponse": { "type": "object", "nullable": true, "properties": { "family": { "type": "string", "example": "for_sale_by_agent", "description": "The sitemap family this window came from, echoed back." }, "shard": { "type": "number", "example": 0, "description": "The shard index this window came from, echoed back." }, "offset": { "type": "number", "example": 0, "description": "The offset you asked for, echoed back." }, "limit": { "type": "number", "example": 1000, "description": "The window size you asked for, echoed back." }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/ZillowSitemapProperty" }, "description": "This window of properties, each a `zpid` and the URL it was read from. Empty array — never null — for a window past the end of the shard." }, "count": { "type": "number", "example": 1000, "description": "How many properties are in this window. Counted from what you received, never copied from a figure the worker printed." }, "shard_count": { "type": "number", "example": 34, "description": "How many shards this family has, read from the live index rather than from a constant. 34 for `for_sale_by_agent` and 255 for `recently_sold` when last read. Size a full walk from this, and expect it to move — Zillow adds shards as the market grows.\n\nIt is one lower than the index appears to list, because the `latest` sitemap that sits beside the numbered shards is a rolling window over the same properties and is filtered out. Without that, a property would come back under two different shard indexes and any count built from a walk would be inflated." }, "shard_total": { "type": "number", "example": 50000, "description": "How many properties this shard holds in total — the number to window against, and the one that says when a walk of this shard is done.\n\nEvery shard read so far held exactly 50,000, but only shard 0 of each family has been read, so do not multiply `shard_count` by 50,000 and treat the result as an exact family total. The Trustpilot index in this same catalogue is the reason for the caution: three of its shards held exactly 50,000 and the last held 24,063, so extrapolating from one shard overstated the total. Read the last shard if you need the real figure." }, "has_more": { "type": "boolean", "example": true, "description": "Whether this shard holds more properties after this window, computed as `offset + count < shard_total`. It says nothing about whether more SHARDS remain — compare `shard` against `shard_count` for that." }, "source_url": { "type": "string", "example": "https://www.zillow.com/xml/sitemaps/us/hdp/for-sale-by-agent/sitemap-0000.xml.gz", "description": "The sitemap file this window was read from. Public, and open in a browser: these need no credential of any kind." }, "usage_note": { "type": "string", "example": "Each zpid is the exact value /zillow/property takes. These come from Zillow's public sitemaps, which need no credential and, unlike property pages, no fresh identity per request.", "description": "The one thing a caller of this endpoint has to know, carried in the body as well as in these docs: each `zpid` feeds `/v1/zillow/property` verbatim." } }, "required": [ "family", "shard", "offset", "limit", "properties", "count", "shard_count", "shard_total", "has_more", "source_url", "usage_note" ] }, "ZillowSitemapProperty": { "type": "object", "properties": { "zpid": { "type": "string", "example": "2146999031", "description": "Zillow's id for the home, and the exact value `/v1/zillow/property` takes. Every entry has one: the sitemaps are keyed on it, and 50,000 of 50,000 URLs in a sampled shard carried one. A shard that arrives carrying none is refused upstream as a layout change rather than published as an empty family." }, "url": { "type": "string", "example": "https://www.zillow.com/homedetails/2114-S-Trumbull-Ave-Chicago-IL-60623/2146999031_zpid/", "description": "The property's page as the sitemap states it. It is kept because it carries the address slug, which at this stage is the only human-readable label a property has — nothing else about the home is known until you fetch it. You do not need it to do that: pass `zpid` to `/v1/zillow/property`." } }, "required": [ "zpid", "url" ] }, "RedfinSearchResponse": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "example": "/city/30818/TX/Austin", "description": "The region path this search was read for, echoed back after cleaning — so a caller who pasted a URL can see the path it resolved to." }, "url": { "type": "string", "example": "https://www.redfin.com/city/30818/TX/Austin", "description": "The region's Redfin page, built from `region`. Public: open it and you see the same listings." }, "region_id": { "type": "string", "nullable": true, "example": "30818", "description": "Redfin's internal id for the region, read off its page rather than derived from the URL. The two are not the same thing: `/zipcode/94110` has region id `39017`. Published so a caller can see which region actually answered." }, "region_type": { "type": "string", "nullable": true, "example": "6", "description": "Redfin's region-type code — `6` for a city, `2` for a zip code — read off the same page." }, "market": { "type": "string", "nullable": true, "example": "austin", "description": "Redfin's market slug for the region, read off the page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RedfinSearchResult" }, "description": "The region's for-sale listings, in Redfin's own order. Empty array — never null — for a region with nothing for sale. Sold listings are not offered here." }, "count": { "type": "number", "example": 350, "description": "How many listings are in this response. Counted from what you received, never copied from a figure Redfin stated." }, "requested_num_homes": { "type": "number", "example": 350, "description": "The `num_homes` this response was read for, echoed back." }, "max_num_homes": { "type": "number", "example": 1000, "description": "The largest `num_homes` this API will ask Redfin for. Published as its own field so a caller answering `results_may_be_capped` knows how much room is left." }, "results_may_be_capped": { "type": "boolean", "example": false, "description": "True when Redfin returned as many listings as were asked for, so the region may hold more. This is where a `has_more` would be on another site, and it is deliberately not one: there is no next page to fetch. Redfin ignores `page_number` — page 2 is a byte-identical response with 0 new properties — and ignores the sort order, so the answer to a capped response is one larger request, not another request. Raise `num_homes` toward 1000; if it is still true there, this region holds more than one call can return." }, "result_code": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": 0, "description": "Redfin's own statement of the outcome, republished. A non-zero code beside an empty `results` is Redfin refusing rather than a region with nothing for sale." }, "error_message": { "type": "string", "nullable": true, "example": "Success", "description": "Redfin's own message for `result_code`." }, "usage_note": { "type": "string", "example": "There is no page 2: Redfin ignores page_number and the sort order, so num_homes is the only lever — if results_may_be_capped is true, re-ask with a larger one. These are for-sale listings; sold listings are not offered. Each result's url is the exact value /redfin/property takes.", "description": "The three things a caller of this endpoint has to know, carried in the body as well as in these docs: there is no page 2, these are for-sale listings only, and each row's `url` feeds `/v1/redfin/property` verbatim." } }, "required": [ "region", "url", "region_id", "region_type", "market", "results", "count", "requested_num_homes", "max_num_homes", "results_may_be_capped", "result_code", "error_message", "usage_note" ] }, "RedfinSearchResult": { "type": "object", "properties": { "property_id": { "type": "string", "nullable": true, "example": "801881", "description": "Redfin's id for the home — the key that joins this row to anything else on the site. It is not what `/v1/redfin/property` takes: use `url` for that." }, "listing_id": { "type": "string", "nullable": true, "example": "184290163", "description": "Redfin's id for this listing of the home. A property relisted later keeps its `property_id` and gets a new one of these." }, "url": { "type": "string", "nullable": true, "example": "https://www.redfin.com/CA/San-Francisco/331-Bartlett-St-94110/home/801881", "description": "The home's page, and the exact value `/v1/redfin/property` takes. This is what makes the two endpoints compose: walk a region here, then pull schools, risk factors, parcel records and comparable sales there, without ever constructing a URL. The address slug in it is part of the key — it cannot be derived from `property_id`." }, "mls_number": { "type": "string", "nullable": true, "example": "424012345", "description": "The listing's MLS number, where Redfin states one." }, "mls_status": { "type": "string", "nullable": true, "example": "Active", "description": "The MLS status Redfin files the listing under — `Active`, `Coming Soon`, `Pending`. Every row here is a for-sale listing." }, "price": { "type": "number", "nullable": true, "example": 1095000, "description": "The listed price. Redfin ships this wrapped as `{value, level}` — `level` is its access tier for the field — and it arrives here unwrapped. Null means Redfin declined to state it, which is not the same as zero." }, "price_per_sqft": { "type": "number", "nullable": true, "example": 712 }, "beds": { "type": "number", "nullable": true, "example": 3 }, "baths": { "type": "number", "nullable": true, "example": 2 }, "sqft": { "type": "number", "nullable": true, "example": 1538, "description": "Interior area in square feet." }, "lot_size": { "type": "number", "nullable": true, "example": null, "description": "Lot area in square feet. Frequently null — it is one of the fields Redfin gates by access tier, and null is the honest rendering of `{level: 1}` with no value on it." }, "year_built": { "type": "number", "nullable": true, "example": 1900 }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": 6, "description": "Redfin's own property-type code, republished as it arrives. `ui_property_type` is the label beside it." }, "ui_property_type": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "nullable": true } ], "example": "PROPERTY_TYPE_HOUSE", "description": "Redfin's own label for the same type." }, "street": { "type": "string", "nullable": true, "example": "331 Bartlett St" }, "unit": { "type": "string", "nullable": true, "example": null }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "state": { "type": "string", "nullable": true, "example": "CA" }, "zip": { "type": "string", "nullable": true, "example": "94110" }, "country_code": { "type": "string", "nullable": true, "example": "US" }, "neighborhood": { "type": "string", "nullable": true, "example": "Mission District", "description": "The neighborhood Redfin files the home under." }, "latitude": { "type": "number", "nullable": true, "example": 37.7529, "description": "Lifted out of Redfin's nested `latLong` pair so a result can be mapped without unpacking." }, "longitude": { "type": "number", "nullable": true, "example": -122.4194 }, "days_on_market": { "type": "number", "nullable": true, "example": 14, "description": "Redfin's own `dom`." }, "time_on_redfin_ms": { "type": "number", "nullable": true, "example": 1209600000, "description": "How long the listing has been on Redfin, in milliseconds, as Redfin states it." }, "time_zone": { "type": "string", "nullable": true, "example": "US/Pacific" }, "description": { "type": "string", "nullable": true, "example": "Beautifully updated Edwardian in the heart of the Mission.", "description": "The listing agent's own prose, in the search response. Most sources make this a per-property follow-up call; Redfin puts it on every row, so a region's full agent copy costs one request." }, "listing_tags": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Redfin's own marketing tags for the listing, republished whole — no capture has pinned a stable field list for them." }, "key_facts": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Redfin's own key-facts rows for the listing, republished whole, on the same terms as `listing_tags`." }, "hoa": { "type": "number", "nullable": true, "example": 450, "description": "Monthly HOA dues where the listing states them." }, "is_new_construction": { "type": "boolean", "nullable": true, "example": false }, "has_3d_tour": { "type": "boolean", "nullable": true, "example": true }, "has_video_tour": { "type": "boolean", "nullable": true, "example": false }, "photo_count": { "type": "number", "nullable": true, "example": 42, "description": "How many photos Redfin says the listing has. The photos themselves are on `/v1/redfin/property`." } }, "required": [ "property_id", "listing_id", "url", "mls_number", "mls_status", "price", "price_per_sqft", "beds", "baths", "sqft", "lot_size", "year_built", "property_type", "ui_property_type", "street", "unit", "city", "state", "zip", "country_code", "neighborhood", "latitude", "longitude", "days_on_market", "time_on_redfin_ms", "time_zone", "description", "listing_tags", "key_facts", "hoa", "is_new_construction", "has_3d_tour", "has_video_tour", "photo_count" ] }, "RedfinPropertyResponse": { "type": "object", "nullable": true, "properties": { "requested_url": { "type": "string", "example": "/CA/San-Francisco/331-Bartlett-St-94110/home/801881", "description": "The property path this response was read for, echoed back after cleaning — so a caller who pasted a URL can see the path it resolved to." }, "url": { "type": "string", "example": "https://www.redfin.com/CA/San-Francisco/331-Bartlett-St-94110/home/801881", "description": "The home's Redfin page, built from `requested_url`." }, "above_the_fold": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Price, address, beds, baths, area and listing status — Redfin's own `aboveTheFold` payload, republished whole. Its endpoint answers 403 when called directly; this is lifted from the property page's own request cache instead." }, "below_the_fold": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "The long-form record: property history, public records, listing details and amenities — Redfin's own `belowTheFold` payload, on the same terms as `above_the_fold`." }, "main_house_info": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Redfin's own `mainHouseInfoPanelInfo` payload — the agent and brokerage attribution panel — on the same terms." }, "schools": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Assigned and nearby schools with their ratings, from the page's `schoolsAndDistrictsInfo` entry." }, "risk_factors": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Flood, fire, heat and wind risk scores for the property, from the page's `riskFactorData` entry." }, "around_this_home": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Redfin's neighborhood context for the address." }, "similar_listings": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Redfin's own comparables for this home. Each carries a Redfin path of its own, which `/v1/redfin/property` takes." }, "nearby_listings": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "The newest listings near the address." }, "nearby_open_houses": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Open houses scheduled nearby." }, "parcel_info": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "The county parcel record Redfin matched to the address — lot, APN and assessment data." }, "avm_history": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "The history of Redfin's own value estimate for the home." }, "activity": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Redfin's per-listing activity data — views, favorites and tour requests, where the page carries them." }, "usage_note": { "type": "string", "example": "Each section is published under its own name and in Redfin's own shape, lifted from the property page's request cache because Redfin's detail endpoints answer 403 when called directly. A null section means the page did not carry it.", "description": "What a caller of this endpoint has to know, carried in the body as well as in these docs: every section is Redfin's own shape under its own name, and a null section means the page did not carry it." } }, "required": [ "requested_url", "url", "above_the_fold", "below_the_fold", "main_house_info", "schools", "risk_factors", "around_this_home", "similar_listings", "nearby_listings", "nearby_open_houses", "parcel_info", "avm_history", "activity", "usage_note" ] }, "YandexSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string" }, "region_id": { "type": "number", "nullable": true }, "page": { "type": "number" }, "max_page": { "type": "number" }, "page_exists": { "type": "boolean", "description": "False means this query has fewer pages than you asked for. It is a real answer, not a failure — Yandex serves a 404 shell past the end of the result set." }, "count": { "type": "number", "description": "Rows returned, adverts included." }, "organic_count": { "type": "number" }, "advert_count": { "type": "number" }, "results_found_text": { "type": "string", "nullable": true, "description": "Yandex's own phrase, verbatim and unparsed, e.g. `stripe payments — Яндекс: нашлось 28 тыс. результатов`. It is approximate and it moves: three fetches of one query said 26, 28 and 29 thousand. A parsed integer would look authoritative and be none of those things." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/YandexSearchResult" } }, "usage_note": { "type": "string" } }, "required": [ "query", "region_id", "page", "max_page", "page_exists", "count", "organic_count", "advert_count", "results_found_text", "results", "usage_note" ] }, "YandexSearchResult": { "type": "object", "properties": { "position": { "type": "number", "description": "Absolute rank across pages, adverts included — page 1's first row is position 11. This is the position on the page as rendered, which is what a rank-tracking caller means." }, "is_advert": { "type": "boolean", "description": "Yandex does not label these. A paid result is an ordinary result row with the same classes; the discriminator used is that every organic result names its destination in its own feedback payload and an advert does not, sending the click through a counter instead." }, "title": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true, "description": "The destination Yandex names for the result, not the counter redirect its link points at. Null on adverts, whose destination Yandex does not state." }, "displayed_path": { "type": "string", "nullable": true, "description": "The breadcrumb shown under the title, e.g. `stripe.com › payments`." }, "snippet": { "type": "string", "nullable": true }, "sitelinks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "title", "url" ] } } }, "required": [ "position", "is_advert", "title", "url", "displayed_path", "snippet", "sitelinks" ] }, "YandexMapsSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string" }, "page": { "type": "number" }, "results_per_page": { "type": "number" }, "language": { "type": "string" }, "count": { "type": "number" }, "total_result_count_estimate": { "type": "number", "nullable": true, "description": "An estimate, and it grows as you page. One six-page walk of the same query reported 89, 114, 169, 227, 284 and 338, and returned 150 rows of which 100 were distinct. Do not compute a page count from it, and de-duplicate on `id`." }, "corrected_query": { "type": "string", "nullable": true }, "request_id": { "type": "string", "nullable": true }, "display_type": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/YandexPlace" } }, "usage_note": { "type": "string" } }, "required": [ "query", "page", "results_per_page", "language", "count", "total_result_count_estimate", "corrected_query", "request_id", "display_type", "results", "usage_note" ] }, "YandexPlace": { "type": "object", "properties": { "id": { "type": "string", "description": "Yandex's organization id. What /v1/yandex/maps/place and /reviews take." }, "type": { "type": "string", "nullable": true, "description": "`business` for an organization, `toponym` for an address or a street. A toponym carries no rating, no phone numbers and no url." }, "title": { "type": "string", "nullable": true }, "short_title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "full_address": { "type": "string", "nullable": true }, "composite_address": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "postal_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "uri": { "type": "string", "nullable": true, "description": "Yandex's own object uri, e.g. `ymapsbm1://org?oid=1018907821`." }, "url": { "type": "string", "nullable": true, "description": "The organization's page. Accepted verbatim by /v1/yandex/maps/place and /v1/yandex/maps/reviews, so the endpoints compose without building a URL." }, "seoname": { "type": "string", "nullable": true }, "kind": { "type": "string", "nullable": true, "description": "Toponyms only: `house`, `street`, `locality`, ..." }, "geo_id": { "type": "number", "nullable": true }, "categories": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "phones": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "websites": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "social_links": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "business_links": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "rating": { "type": "object", "nullable": true, "properties": { "value": { "type": "number", "nullable": true }, "ratings": { "type": "number", "nullable": true, "description": "How many people rated it — always larger than `reviews`." }, "reviews": { "type": "number", "nullable": true, "description": "How many wrote text. This is the number /reviews pages through." } }, "required": [ "value", "ratings", "reviews" ] }, "working_time_text": { "type": "string", "nullable": true }, "working_status": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "status": { "type": "string", "nullable": true }, "features": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Amenities as Yandex states them — average bill, delivery, card payment, cuisine type. Republished in Yandex's own shape." }, "chain": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "metro": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "photo_count": { "type": "number", "nullable": true }, "is_advert": { "type": "boolean", "description": "A paid placement inside the map results. Same array and same shape as an organic row, exactly as on the web SERP." } }, "required": [ "id", "type", "title", "short_title", "description", "address", "full_address", "composite_address", "postal_code", "country", "latitude", "longitude", "uri", "url", "seoname", "kind", "geo_id", "categories", "phones", "websites", "social_links", "business_links", "rating", "working_time_text", "working_status", "status", "features", "chain", "metro", "photo_count", "is_advert" ] }, "YandexMapsPlaceResponse": { "allOf": [ { "$ref": "#/components/schemas/YandexPlace" }, { "type": "object", "nullable": true, "properties": { "requested_place": { "type": "string" }, "usage_note": { "type": "string" } }, "required": [ "requested_place", "usage_note" ] } ] }, "YandexMapsReviewsResponse": { "type": "object", "nullable": true, "properties": { "place_id": { "type": "string" }, "sort": { "type": "string" }, "language": { "type": "string" }, "count": { "type": "number" }, "total_reviews": { "type": "number", "nullable": true }, "total_pages": { "type": "number", "nullable": true }, "page": { "type": "number", "nullable": true }, "page_size": { "type": "number", "nullable": true }, "reviews_remaining": { "type": "number", "nullable": true }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/YandexReview" } }, "aspects": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] }, "usage_note": { "type": "string" } }, "required": [ "place_id", "sort", "language", "count", "total_reviews", "total_pages", "page", "page_size", "reviews_remaining", "reviews", "aspects", "usage_note" ] }, "YandexReview": { "type": "object", "properties": { "review_id": { "type": "string", "nullable": true }, "business_id": { "type": "string", "nullable": true }, "rating": { "type": "number", "nullable": true }, "text": { "type": "string", "nullable": true }, "text_language": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true }, "pinned": { "type": "boolean", "nullable": true }, "author_name": { "type": "string", "nullable": true }, "author_public_id": { "type": "string", "nullable": true }, "author_level": { "type": "string", "nullable": true }, "author_avatar_url_template": { "type": "string", "nullable": true, "description": "A template with a literal `{size}` in it, not a fetchable URL." }, "likes": { "type": "number", "nullable": true }, "dislikes": { "type": "number", "nullable": true }, "photos": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ] } }, "required": [ "review_id", "business_id", "rating", "text", "text_language", "updated_at", "pinned", "author_name", "author_public_id", "author_level", "author_avatar_url_template", "likes", "dislikes", "photos" ] }, "SkyscannerRouteResponse": { "type": "object", "nullable": true, "properties": { "requested_origin": { "type": "string", "example": "lond", "description": "The `origin` code this was read for, echoed back. Not always the same as `origin.sky_code`: Skyscanner canonicalises an airport to its city, so asking for `lhr` returns `LOND`." }, "requested_destination": { "type": "string", "example": "nyca" }, "url": { "type": "string", "example": "https://www.skyscanner.net/routes/lond/nyca", "description": "The Skyscanner page this was read from. Public, and allowed by Skyscanner's robots.txt — open it and you see the same fares." }, "origin": { "$ref": "#/components/schemas/SkyscannerPlace" }, "destination": { "$ref": "#/components/schemas/SkyscannerPlace" }, "title": { "type": "string", "nullable": true, "example": "£146 Cheap Flights from London (LOND) to New York (NYCA) | Skyscanner", "description": "The page's own title, which states the headline fare as prose." }, "cheapest_price": { "type": "number", "nullable": true, "example": 146, "description": "The headline fare, as a number. Taken from the page's schema.org `AggregateOffer`, which is the only place it appears as a number — the title states it as localised prose and Skyscanner's own fact bag states it pre-formatted with a currency symbol." }, "currency": { "type": "string", "nullable": true, "example": "GBP", "description": "The currency every price on this response is in, as schema.org states it. `skyscanner.net` is the UK storefront and serves GBP regardless of where the request comes from, so this is stated rather than assumed." }, "offer_name": { "type": "string", "nullable": true, "example": "Cheap Flights from London to New York" }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerDeal" }, "description": "The quoted fares, in Skyscanner's own order. Empty array — never null — when the page carried a headline fare but no quotes." }, "deals_count": { "type": "number", "example": 16, "description": "Counted from what you received, never copied from the source." }, "cheapest_by_month": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerMonthPrice" }, "description": "The cheapest fare Skyscanner has for each of the coming months, 12 of them measured on every page that carried any. A month with no fare is omitted rather than published at zero." }, "nearby_airports": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerNearbyAirport" }, "description": "Airports serving the destination, with the cheapest fare into each. Each `sky_code` here is a valid input to `/v1/skyscanner/route`." }, "airlines_direct": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerAirline" }, "description": "Every airline Skyscanner lists as flying this route directly." }, "popular_airlines": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerAirline" }, "description": "The shortlist Skyscanner promotes. A different list from `airlines_direct`, not a slice of it — they ship as the same component under two different config names." }, "faqs": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerFaq" }, "description": "Skyscanner's own route-specific Q&A, stripped of markup." }, "facts": { "$ref": "#/components/schemas/SkyscannerFacts" }, "usage_note": { "type": "string", "description": "What a caller has to know to read this response correctly, restated on every one of them." } }, "required": [ "requested_origin", "requested_destination", "url", "origin", "destination", "title", "cheapest_price", "currency", "offer_name", "deals", "deals_count", "cheapest_by_month", "nearby_airports", "airlines_direct", "popular_airlines", "faqs", "facts", "usage_note" ] }, "SkyscannerPlace": { "type": "object", "nullable": true, "properties": { "sky_code": { "type": "string", "nullable": true, "example": "LOND", "description": "Skyscanner's own code for the place, and the exact value these endpoints take. This is what makes them compose, and it carries more weight here than on other sources: Skyscanner's place autosuggest is disallowed by robots.txt, so these codes are the only place lookup this API has." }, "entity_id": { "type": "string", "nullable": true, "example": "27544008", "description": "Skyscanner's numeric entity id for the place." }, "name": { "type": "string", "nullable": true, "example": "London" }, "country_name": { "type": "string", "nullable": true, "example": "United Kingdom", "description": "Frequently null — Skyscanner states it on a deal's origin and usually leaves it empty on the destination." }, "image_url": { "type": "string", "nullable": true, "example": null } }, "required": [ "sky_code", "entity_id", "name", "country_name", "image_url" ], "description": "The origin as Skyscanner itself names it. Null when the page quoted no deals, since the pair is only stated on a deal." }, "SkyscannerDeal": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "{bl}:202608211200I*SENEWR20261205skypEZY", "description": "Skyscanner's own price-trace id. Distinct routes return disjoint id sets — measured across six city pairs, zero shared ids between unrelated pairs." }, "price": { "type": "number", "nullable": true, "example": 188, "description": "The fare as a number, in the response's `currency`. A deal quoting no fare is dropped rather than published with a null price." }, "formatted_price": { "type": "string", "nullable": true, "example": "£188" }, "direct": { "type": "boolean", "nullable": true, "example": false }, "cabin_class": { "type": "string", "nullable": true, "example": null }, "origin": { "$ref": "#/components/schemas/SkyscannerPlace" }, "destination": { "$ref": "#/components/schemas/SkyscannerPlace" }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerLeg" }, "description": "One entry for a one-way quote, two for a return. Each names its own airports, date and carrier." }, "deep_link_path": { "type": "string", "nullable": true, "example": "/transport/flights/SEN/EWR/20261205?locale=en-GB", "description": "Skyscanner's own path into its live search. Published as a path, not as a fetchable URL, and this API does not follow it — `/transport/` is disallowed by Skyscanner's robots.txt. It is here because it names the exact airports and date the quote belongs to." } }, "required": [ "id", "price", "formatted_price", "direct", "cabin_class", "origin", "destination", "legs", "deep_link_path" ] }, "SkyscannerLeg": { "type": "object", "properties": { "date": { "type": "string", "nullable": true, "example": "2026-12-05" }, "formatted_date": { "type": "string", "nullable": true, "example": "Sat, 5 Dec" }, "quoted_at": { "type": "string", "nullable": true, "example": "2026-08-21T12:00Z", "description": "When Skyscanner quoted this fare. These are cached quotes, not a live search, and this is the field that says how stale one is." }, "origin": { "allOf": [ { "$ref": "#/components/schemas/SkyscannerPlace" }, { "description": "The departure airport for this leg, not the city." } ] }, "destination": { "$ref": "#/components/schemas/SkyscannerPlace" }, "carrier_name": { "type": "string", "nullable": true, "example": "easyJet" }, "carrier_code": { "type": "string", "nullable": true, "example": "EZY", "description": "The airline's own code as Skyscanner states it." } }, "required": [ "date", "formatted_date", "quoted_at", "origin", "destination", "carrier_name", "carrier_code" ] }, "SkyscannerMonthPrice": { "type": "object", "properties": { "month": { "type": "string", "nullable": true, "example": "2026-10" }, "month_name": { "type": "string", "nullable": true, "example": "October" }, "price": { "type": "number", "example": 226 }, "formatted_price": { "type": "string", "nullable": true, "example": "£226" } }, "required": [ "month", "month_name", "price", "formatted_price" ] }, "SkyscannerNearbyAirport": { "type": "object", "properties": { "airport_name": { "type": "string", "nullable": true, "example": "New York Newark" }, "sky_code": { "type": "string", "nullable": true, "example": "EWR", "description": "Valid as an `origin` or `destination` on `/v1/skyscanner/route`." }, "distance": { "type": "number", "nullable": true, "example": 9, "description": "Distance from the destination city, in the site's own unit." }, "formatted_price": { "type": "string", "nullable": true, "example": "£188" }, "carrier_name": { "type": "string", "nullable": true, "example": "easyJet" }, "is_cheapest": { "type": "boolean", "nullable": true, "example": true }, "is_closest": { "type": "boolean", "nullable": true, "example": false } }, "required": [ "airport_name", "sky_code", "distance", "formatted_price", "carrier_name", "is_cheapest", "is_closest" ] }, "SkyscannerAirline": { "type": "object", "properties": { "name": { "type": "string", "example": "British Airways" }, "code": { "type": "string", "nullable": true, "example": "BA" }, "logo_url": { "type": "string", "nullable": true, "example": "https://logos.skyscnr.com/images/airlines/BA.png" } }, "required": [ "name", "code", "logo_url" ] }, "SkyscannerFaq": { "type": "object", "properties": { "question": { "type": "string", "example": "How many airports are there in New York?" }, "answer": { "type": "string", "nullable": true, "example": "There are 6 airports in New York: New York LaGuardia, New York Newark, New York John F. Kennedy, Westchester County, Islip, and Stewart International.", "description": "Skyscanner's own answer, stripped of the inline markup it ships with. These are route-specific facts rather than boilerplate, and some of them appear nowhere else on the page." } }, "required": [ "question", "answer" ] }, "SkyscannerFacts": { "type": "object", "properties": { "cheapest_month": { "type": "string", "nullable": true, "example": "October" }, "most_expensive_month": { "type": "string", "nullable": true, "example": "August" }, "cheapest_origin_airport": { "type": "string", "nullable": true, "example": "London Gatwick" }, "cheapest_destination_airport": { "type": "string", "nullable": true, "example": "New York John F. Kennedy" }, "cheapest_airline": { "type": "string", "nullable": true, "example": "Ryanair" }, "most_popular_airline": { "type": "string", "nullable": true, "example": "British Airways" }, "average_flight_time": { "type": "string", "nullable": true, "example": "8 hours" }, "cheapest_outbound_date": { "type": "string", "nullable": true, "example": "Monday, 5 October 2026" }, "formatted_one_way_price": { "type": "string", "nullable": true, "example": "£188" }, "formatted_return_price": { "type": "string", "nullable": true, "example": "£146" }, "formatted_annual_average_price": { "type": "string", "nullable": true, "example": "£146" }, "warmest_month": { "type": "string", "nullable": true, "example": "July" }, "coldest_month": { "type": "string", "nullable": true, "example": "January" }, "wettest_month": { "type": "string", "nullable": true, "example": "August" }, "driest_month": { "type": "string", "nullable": true, "example": "February" } }, "required": [ "cheapest_month", "most_expensive_month", "cheapest_origin_airport", "cheapest_destination_airport", "cheapest_airline", "most_popular_airline", "average_flight_time", "cheapest_outbound_date", "formatted_one_way_price", "formatted_return_price", "formatted_annual_average_price", "warmest_month", "coldest_month", "wettest_month", "driest_month" ], "description": "Route facts Skyscanner states in a flat bag — cheapest and most expensive month, typical flight time, the destination's weather extremes. Any entry Skyscanner left as an unresolved template token is null here rather than the token's own name." }, "SkyscannerDestinationResponse": { "type": "object", "nullable": true, "properties": { "requested_place": { "type": "string", "example": "nyca" }, "url": { "type": "string", "example": "https://www.skyscanner.net/flights-to/nyca" }, "destination": { "$ref": "#/components/schemas/SkyscannerPlace" }, "title": { "type": "string", "nullable": true, "example": "£146 Cheap Flights from London (LOND) to New York (NYCA) | Skyscanner", "description": "The page's own title, which states the headline fare as prose." }, "cheapest_price": { "type": "number", "nullable": true, "example": 146, "description": "The headline fare, as a number. Taken from the page's schema.org `AggregateOffer`, which is the only place it appears as a number — the title states it as localised prose and Skyscanner's own fact bag states it pre-formatted with a currency symbol." }, "currency": { "type": "string", "nullable": true, "example": "GBP", "description": "The currency every price on this response is in, as schema.org states it. `skyscanner.net` is the UK storefront and serves GBP regardless of where the request comes from, so this is stated rather than assumed." }, "offer_name": { "type": "string", "nullable": true, "example": "Cheap Flights from London to New York" }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerDeal" }, "description": "The quoted fares, in Skyscanner's own order. Empty array — never null — when the page carried a headline fare but no quotes." }, "deals_count": { "type": "number", "example": 16, "description": "Counted from what you received, never copied from the source." }, "cheapest_by_month": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerMonthPrice" }, "description": "The cheapest fare Skyscanner has for each of the coming months, 12 of them measured on every page that carried any. A month with no fare is omitted rather than published at zero." }, "nearby_airports": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerNearbyAirport" }, "description": "Airports serving the destination, with the cheapest fare into each. Each `sky_code` here is a valid input to `/v1/skyscanner/route`." }, "airlines_direct": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerAirline" }, "description": "Every airline Skyscanner lists as flying this route directly." }, "popular_airlines": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerAirline" }, "description": "The shortlist Skyscanner promotes. A different list from `airlines_direct`, not a slice of it — they ship as the same component under two different config names." }, "faqs": { "type": "array", "items": { "$ref": "#/components/schemas/SkyscannerFaq" }, "description": "Skyscanner's own route-specific Q&A, stripped of markup." }, "facts": { "$ref": "#/components/schemas/SkyscannerFacts" }, "usage_note": { "type": "string", "description": "What a caller has to know to read this response correctly, restated on every one of them." } }, "required": [ "requested_place", "url", "destination", "title", "cheapest_price", "currency", "offer_name", "deals", "deals_count", "cheapest_by_month", "nearby_airports", "airlines_direct", "popular_airlines", "faqs", "facts", "usage_note" ] }, "TwoGisSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string", "example": "кафе" }, "city": { "type": "string", "example": "moscow" }, "region_id": { "type": "string", "nullable": true, "example": "32", "description": "The internal id the city slug resolved to, published so a caller can see which region actually answered." }, "region_name": { "type": "string", "nullable": true, "example": "Москва" }, "country_code": { "type": "string", "nullable": true, "example": "ru" }, "locale": { "type": "string", "nullable": true, "example": "ru_RU" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisPlace" }, "description": "The matching organisations in 2GIS's own order, paid placements included and flagged. Empty array — never null — when nothing matched." }, "count": { "type": "number", "example": 20, "description": "How many rows are in this response. Counted from what you received, never copied from a figure 2GIS stated." }, "total": { "type": "number", "nullable": true, "example": 8616, "description": "How many results 2GIS says the query has in this city. Unlike most sources this one is reachable: pages run to `ceil(total / page_size)` and the last one is short rather than the walk dying early." }, "match_type": { "type": "string", "nullable": true, "example": "discovery", "description": "Which search mode answered — not how well it did. `discovery` means 2GIS resolved the query to one of its own categories and browsed it; `recovery` means it ran a literal text search instead. `recovery` is not a warning: measured, `Му-Му`, `hotel` in Dubai, `restaurant` in Dubai and `аптека` in St Petersburg all took that path and all answered well, at relevances of 296-3,561. Branch on `is_partial_match`, not on this. Null when nothing matched at all." }, "is_partial_match": { "type": "boolean", "nullable": true, "example": false, "description": "The field that tells you whether these rows answer your query. True means 2GIS could not match it and returned unrelated real businesses anyway, under a healthy 200 with identical row shapes. Measured over 15 queries in 5 cities it separated them perfectly: false on 10/10 real queries, true on 5/5 nonsense ones. Those rows are returned rather than hidden — a near miss is occasionally what a caller wants — but they are never returned unlabelled." }, "max_relevance": { "type": "number", "nullable": true, "example": 2151.38, "description": "The best relevance in this response, and the numeric corroboration for `is_partial_match`. Orders of magnitude is the readable difference: 10.98-8,827.83 across the measured real queries, 4.8e-16-2.9e-06 across the nonsense ones. No threshold is published because fifteen samples is not a threshold." }, "page": { "type": "number", "example": 1 }, "page_size": { "type": "number", "example": 20 }, "max_page_size": { "type": "number", "example": 50, "description": "The largest `page_size` this API will ask 2GIS for. Published as its own field because upstream refuses a larger value rather than clamping it." }, "usage_note": { "type": "string", "example": "Check is_partial_match before trusting these rows: true means 2GIS could not match the query and returned unrelated real businesses anyway, under a healthy 200, at a relevance around 1e-09 against 10-8800 for a real match. match_type is not that signal — it names which search mode answered, and a literal text search on a brand name is the best answer available rather than a degraded one. Search rows carry no phone number and no website — the site's own search request omits contact fields — so pass a row's id to /v1/2gis/place for those. If you aggregate pages, de-duplicate on id: 0-4.8% of rows repeat an organisation from an earlier page, so summing count across pages overstates the result set.", "description": "The two things a caller of this endpoint has to know, carried in the body as well as in these docs: check `is_partial_match`, and search rows have no contact details." } }, "required": [ "query", "city", "region_id", "region_name", "country_code", "locale", "results", "count", "total", "match_type", "is_partial_match", "max_relevance", "page", "page_size", "max_page_size", "usage_note" ] }, "TwoGisPlace": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "70000001007179642", "description": "The branch id, and the exact value `/v1/2gis/place` and `/v1/2gis/reviews` take. 2GIS's search response does not publish this: its `id` is this value plus a 130-character per-request context blob that works nowhere else on the site. The tail is stripped here and kept as `search_context_id`." }, "search_context_id": { "type": "string", "nullable": true, "example": "70000001007179642_ku4dspBmdBdB9A82AJ7H…", "description": "2GIS's undecorated search id, kept rather than discarded. It is per-request and carries the ad/ranking context; null on a `/v1/2gis/place` response, which has no such tail." }, "name": { "type": "string", "nullable": true, "example": "Му-Му, кафе" }, "type": { "type": "string", "nullable": true, "example": "branch", "description": "2GIS's own object type. These endpoints ask for branches." }, "url": { "type": "string", "nullable": true, "example": "https://2gis.ru/moscow/firm/70000001007179642", "description": "The organisation's public 2GIS page, built from its city slug and branch id. Open it and you see the same record." }, "address": { "$ref": "#/components/schemas/TwoGisAddress" }, "latitude": { "type": "number", "nullable": true, "example": 55.755301 }, "longitude": { "type": "number", "nullable": true, "example": 37.614586 }, "region_id": { "type": "string", "nullable": true, "example": "32", "description": "2GIS's internal id for the city. Not derivable — Moscow is 32, Novosibirsk is 1, Dubai is 99." }, "city_alias": { "type": "string", "nullable": true, "example": "moscow" }, "rubrics": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisRubric" }, "description": "Every category 2GIS files the organisation under." }, "primary_rubric": { "type": "string", "nullable": true, "example": "Кафе", "description": "The rubric marked `primary`, lifted out for convenience." }, "schedule": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "type": "string" }, { "nullable": true } ], "description": "Opening hours per weekday in 2GIS's own shape — `{Mon: {working_hours: [{from, to}]}}`, plus its own keys for round-the-clock and closed. Republished rather than renamed." }, "contacts": { "$ref": "#/components/schemas/TwoGisContacts" }, "attribute_groups": { "type": "array", "items": { "nullable": true }, "description": "2GIS's own structured attributes — average cheque, cuisine, amenities — grouped as it groups them. Rich on `/v1/2gis/place`." }, "organization": { "$ref": "#/components/schemas/TwoGisOrganization" }, "rating": { "type": "number", "nullable": true, "example": 4.8, "description": "This branch's own rating. Published beside `org_rating` on purpose: a branch of a chain frequently disagrees with its parent, and quoting either one alone misstates the other." }, "review_count": { "type": "number", "nullable": true, "example": 1090, "description": "How many ratings this branch has. Larger than what `/v1/2gis/reviews` will serve — that endpoint returns written reviews only." }, "org_rating": { "type": "number", "nullable": true, "example": 4.3, "description": "The whole chain's rating, where this is a chain branch." }, "org_review_count": { "type": "number", "nullable": true, "example": 7817 }, "is_reviewable": { "type": "boolean", "nullable": true, "example": true }, "is_advertisement": { "type": "boolean", "example": false, "description": "True when this row is a paid placement. 2GIS mixes advertised organisations into the ranked list, so a caller measuring ranking has to be able to exclude them." }, "relevance": { "type": "number", "nullable": true, "example": 1137.25, "description": "2GIS's own relevance for this row against the query. Read it together with `is_partial_match`: measured across 15 queries, real matches ran 10.98-8,827.83 and unmatched ones 4.8e-16-2.9e-06, with no overlap. It is the numeric corroboration for the boolean." } }, "required": [ "id", "search_context_id", "name", "type", "url", "address", "latitude", "longitude", "region_id", "city_alias", "rubrics", "primary_rubric", "schedule", "contacts", "attribute_groups", "organization", "rating", "review_count", "org_rating", "org_review_count", "is_reviewable", "is_advertisement", "relevance" ] }, "TwoGisAddress": { "type": "object", "properties": { "street_address": { "type": "string", "nullable": true, "example": "Манежная площадь, 1 ст2", "description": "2GIS's `address_name` — the street line only. The city is not in it; that comes from the administrative division and is published beside it here." }, "address_comment": { "type": "string", "nullable": true, "example": "-2 этаж; Средний уровень", "description": "How to find the entrance once you are at the address." }, "building_name": { "type": "string", "nullable": true, "example": "Охотный ряд" }, "postcode": { "type": "string", "nullable": true, "example": "125009" }, "country": { "type": "string", "nullable": true, "example": "Россия" }, "region": { "type": "string", "nullable": true, "example": "Москва" }, "city": { "type": "string", "nullable": true, "example": "Москва", "description": "Lifted out of 2GIS's `adm_div` list, which is where the city actually lives — the street line does not contain it." }, "district": { "type": "string", "nullable": true, "example": "Тверской" }, "settlement": { "type": "string", "nullable": true, "example": null } }, "required": [ "street_address", "address_comment", "building_name", "postcode", "country", "region", "city", "district", "settlement" ], "description": "2GIS states an address three ways — a street line, an administrative division list and a separate postcode — and all three are kept, because flattening to the first loses the city." }, "TwoGisRubric": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "161" }, "name": { "type": "string", "nullable": true, "example": "Кафе" }, "alias": { "type": "string", "nullable": true, "example": "kafe" }, "kind": { "type": "string", "nullable": true, "example": "primary", "description": "`primary` or `additional`. The primary one is republished on its own as `primary_rubric`." } }, "required": [ "id", "name", "alias", "kind" ] }, "TwoGisContacts": { "type": "object", "properties": { "phones": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisContact" } }, "websites": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisContact" } }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisContact" } } }, "required": [ "phones", "websites", "emails" ], "description": "Empty on every `/v1/2gis/search` row, populated on every `/v1/2gis/place` one. That is a property of the endpoint, not of the business: the site's own search request omits contact fields, so no amount of paging produces a phone number here." }, "TwoGisContact": { "type": "object", "properties": { "value": { "type": "string", "nullable": true, "example": "+74957818781", "description": "The real value, on every contact kind — the dialable number, the actual website, the mailbox. Normalised: 2GIS puts its own click-tracking redirector here for websites and the real address in a separate field, the inverse of what it does for phones and emails, so the two are swapped back and the redirector is published as `tracking_url`." }, "text": { "type": "string", "nullable": true, "example": "+7 (495) 781‒87‒81" }, "comment": { "type": "string", "nullable": true, "example": "служба доставки" }, "tracking_url": { "type": "string", "nullable": true, "example": "http://link.2gis.ru/1.2/97BA0CE6/…", "description": "2GIS's own `link.2gis.ru` click-tracking redirector, where it publishes one — websites in practice. Kept so nothing is discarded, and kept separate because 2GIS itself puts this in the `value` position for websites and the real address in `url`, the inverse of what it does for phones and emails. Republishing that verbatim hands a caller a tracking link as the business's website." } }, "required": [ "value", "text", "comment", "tracking_url" ] }, "TwoGisOrganization": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "4504136498368318" }, "name": { "type": "string", "nullable": true, "example": "Му-Му, кафе" }, "branch_count": { "type": "number", "nullable": true, "example": 18, "description": "How many branches the chain has in this city's catalogue." } }, "required": [ "id", "name", "branch_count" ], "description": "The chain this branch belongs to, where it belongs to one." }, "TwoGisPlaceResponse": { "allOf": [ { "$ref": "#/components/schemas/TwoGisPlace" }, { "type": "object", "nullable": true, "properties": { "requested_id": { "type": "string", "example": "70000001007179642", "description": "The branch id this response was read for, echoed back." }, "usage_note": { "type": "string", "example": "This is the same organisation a /v1/2gis/search row describes, plus the fields search cannot carry: phones, websites, emails and the full attribute groups. Every contacts.[].value is the real value — the dialable number, the actual website, the mailbox. 2GIS itself puts its click-tracking redirector in that position for websites; it is moved to tracking_url so value means one thing across all three kinds." } }, "required": [ "requested_id", "usage_note" ] } ] }, "TwoGisReviewsResponse": { "type": "object", "nullable": true, "properties": { "requested_id": { "type": "string", "example": "70000001007179642" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisReview" }, "description": "One page of written reviews. Empty array — never null — past the end of the list." }, "count": { "type": "number", "example": 20 }, "total": { "type": "number", "nullable": true, "example": 1039, "description": "How many reviews this endpoint will actually serve, and the number to walk `offset` up to. Deliberately published beside `branch_review_count`, which is larger." }, "branch_rating": { "type": "number", "nullable": true, "example": 4.8 }, "branch_review_count": { "type": "number", "nullable": true, "example": 1091, "description": "The count the place card shows — larger than `total`, because 2GIS counts star-only ratings here and returns only written reviews from this endpoint. Measured 1,091 against 1,039 on the same branch. Publishing one alone makes a complete walk look truncated." }, "providers": { "type": "array", "items": { "type": "string" }, "example": [ "flamp", "2gis" ], "description": "Every review source 2GIS aggregates for this branch. Each row's `provider` names which one it came from." }, "limit": { "type": "number", "example": 20 }, "offset": { "type": "number", "example": 0 }, "sort": { "type": "string", "example": "date_created" }, "available_sorts": { "type": "array", "items": { "type": "string" }, "example": [ "date_created", "date_edited", "friends", "trust" ], "description": "2GIS's own allowed set for `sort`." }, "usage_note": { "type": "string", "example": "total is how many reviews this endpoint will actually serve, and it is smaller than branch_review_count — 2GIS counts star-only ratings in the second and returns only written reviews here. Walk by offset up to total; past it the list is empty rather than an error." } }, "required": [ "requested_id", "results", "count", "total", "branch_rating", "branch_review_count", "providers", "limit", "offset", "sort", "available_sorts", "usage_note" ] }, "TwoGisReview": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "271440829" }, "rating": { "type": "number", "nullable": true, "example": 5 }, "text": { "type": "string", "nullable": true, "example": "Отлично!)))", "description": "The review body, in the language it was written in." }, "date_created": { "type": "string", "nullable": true, "example": "2026-08-23T03:46:23.263816+07:00" }, "date_edited": { "type": "string", "nullable": true, "example": null }, "likes_count": { "type": "number", "nullable": true, "example": 0 }, "comments_count": { "type": "number", "nullable": true, "example": 0 }, "photo_count": { "type": "number", "nullable": true, "example": 2, "description": "How many photos the reviewer attached." }, "provider": { "type": "string", "nullable": true, "example": "2gis", "description": "Which source this review came from. 2GIS aggregates its own reviews with Flamp, Booking, Avito and others under one branch, and they are not the same corpus — a caller comparing ratings across businesses needs to be able to separate them." }, "author": { "$ref": "#/components/schemas/TwoGisReviewAuthor" }, "official_answer": { "$ref": "#/components/schemas/TwoGisOfficialAnswer" } }, "required": [ "id", "rating", "text", "date_created", "date_edited", "likes_count", "comments_count", "photo_count", "provider", "author", "official_answer" ] }, "TwoGisReviewAuthor": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "54832258" }, "name": { "type": "string", "nullable": true, "example": "Марианна Винокурова" }, "public_id": { "type": "string", "nullable": true, "example": "b5702370dd1141b080fb8693fe2991fc" }, "reviews_count": { "type": "number", "nullable": true, "example": 2 } }, "required": [ "id", "name", "public_id", "reviews_count" ] }, "TwoGisOfficialAnswer": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "nullable": true }, "date_created": { "type": "string", "nullable": true } }, "required": [ "text", "date_created" ], "description": "The business's own reply, where it has replied." }, "TwoGisCitiesResponse": { "type": "object", "nullable": true, "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/TwoGisCity" } }, "count": { "type": "number", "example": 206, "description": "How many cities 2GIS covers. Counted, not stated." }, "usage_note": { "type": "string", "example": "city is what /v1/2gis/search takes. locales is the set that city accepts — asking for one outside it is rejected by 2GIS, so this is not a translation layer." } }, "required": [ "results", "count", "usage_note" ] }, "TwoGisCity": { "type": "object", "properties": { "city": { "type": "string", "nullable": true, "example": "moscow", "description": "The value `/v1/2gis/search` takes as `city`." }, "region_id": { "type": "string", "nullable": true, "example": "32" }, "name": { "type": "string", "nullable": true, "example": "Москва" }, "country_code": { "type": "string", "nullable": true, "example": "ru" }, "locale": { "type": "string", "nullable": true, "example": "ru_RU", "description": "The city's default locale — what `locale` falls back to." }, "locales": { "type": "array", "items": { "type": "string" }, "example": [ "ru_RU" ], "description": "Every locale this city accepts. A value outside this set is refused by 2GIS with a 400 rather than falling back." }, "time_zone": { "type": "string", "nullable": true, "example": "Europe/Moscow" }, "aliases": { "type": "array", "items": { "type": "string" }, "example": [ "nur_sultan" ], "description": "Other slugs 2GIS answers to for the same city." } }, "required": [ "city", "region_id", "name", "country_code", "locale", "locales", "time_zone", "aliases" ] }, "AvitoListingsResponse": { "type": "object", "nullable": true, "properties": { "requested_url": { "type": "string", "nullable": true, "example": "/moskva/avtomobili", "description": "The cleaned path that was fetched." }, "url": { "type": "string", "nullable": true, "example": "https://www.avito.ru/moskva/avtomobili", "description": "The same, as an absolute URL." }, "requested_page": { "type": "number", "nullable": true, "example": 1 }, "requested_sort": { "type": "string", "nullable": true, "example": null, "description": "The sort code that was sent, or null for Avito's default." }, "title": { "type": "string", "nullable": true, "example": "Купить автомобиль в Москве", "description": "The page's own heading, as Avito writes it." }, "canonical_url": { "type": "string", "nullable": true, "example": "https://www.avito.ru/moskva/avtomobili" }, "location_name": { "type": "string", "nullable": true, "example": "Москва" }, "location_id": { "type": "string", "nullable": true, "example": "637640", "description": "Avito's internal id for the city." }, "category_id": { "type": "string", "nullable": true, "example": "9", "description": "Avito's internal id for the category." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AvitoListing" }, "description": "Listings on this page. An empty array means the category page contained no listings." }, "count": { "type": "number", "example": 50, "description": "Number of listings in `results`, excluding advertising rows." }, "dropped_non_listing_rows": { "type": "number", "example": 3, "description": "Number of advertising rows excluded from `results` and `count`." }, "descriptions_available": { "type": "number", "example": 6, "description": "How many of `results` carried a `description`. A rendering fact, not a data-quality one — see `description`." }, "page": { "type": "number", "nullable": true, "example": 1, "description": "The page Avito says it served." }, "last_page": { "type": "number", "nullable": true, "example": 100, "description": "The last page Avito's own pager links to. Measured at 100 on every category tested." }, "items_per_page": { "type": "number", "nullable": true, "example": 50 }, "max_page": { "type": "number", "nullable": true, "example": 100, "description": "The ceiling this API enforces, mirroring `last_page`." }, "total_count": { "type": "number", "nullable": true, "example": 79551, "description": "How many listings Avito claims the category holds. Almost always far more than can be paged to — compare `reachable_count`." }, "reachable_count": { "type": "number", "nullable": true, "example": 5000, "description": "How many rows the pager will actually hand over: `last_page` × `items_per_page`. This is the number to plan a harvest against. `/moskva/telefony` advertises 533,873 listings and reaches 5,000." }, "has_next_page": { "type": "boolean", "example": true, "description": "Whether Avito's pager offers a next page from here." }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/AvitoSortOption" }, "description": "The sort vocabulary this category actually offers, with Avito's own codes. Pass one back as `sort`." }, "default_sort": { "type": "string", "nullable": true, "example": "101", "description": "The code Avito sorts by when none is given." }, "usage_note": { "type": "string", "nullable": true, "example": "Avito paginates to page 100 of 50 and no further, whatever total_count says — reachable_count is what the pager will actually hand over. Rows repeat across pages (a 12-page walk returned 554 distinct ids out of 600), so de-duplicate on id when harvesting. description arrives for a leading prefix of the rows only and how long that prefix is varies per render; descriptions_available states how many arrived on this page.", "description": "The two things a caller gets wrong here: trusting `total_count` as reachable, and harvesting several pages without de-duplicating." } }, "required": [ "requested_url", "url", "requested_page", "requested_sort", "title", "canonical_url", "location_name", "location_id", "category_id", "results", "count", "dropped_non_listing_rows", "descriptions_available", "page", "last_page", "items_per_page", "max_page", "total_count", "reachable_count", "has_next_page", "sorts", "default_sort", "usage_note" ] }, "AvitoListing": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "8082366222", "description": "Avito listing ID. Use it to de-duplicate rows across pages." }, "url": { "type": "string", "nullable": true, "example": "https://www.avito.ru/moskva/avtomobili/toyota_camry_2.5_at_2013_201_463_km_8082366222", "description": "Listing URL with the non-portable `context` search token removed." }, "title": { "type": "string", "nullable": true, "example": "Toyota Camry 2.5 AT, 2013, 201 463 км" }, "price": { "type": "number", "nullable": true, "example": 1200000, "description": "The price as a number, in roubles. Null means Avito stated none, which is not the same as zero — and it does not say whether the figure is a sale price or a monthly rent. `price_text` does." }, "price_text": { "type": "string", "nullable": true, "example": "1 200 000 ₽", "description": "Avito's own rendering of the price, currency symbol and period included. This is the only field that distinguishes a sale from a rent — a Moscow flat reads `65 000 ₽ в месяц`, and publishing the number 65000 alone would present a monthly rent as a purchase price." }, "price_was_lowered": { "type": "boolean", "nullable": true, "example": false, "description": "Whether Avito flags this listing as recently reduced." }, "category": { "type": "string", "nullable": true, "example": "Автомобили" }, "category_slug": { "type": "string", "nullable": true, "example": "avtomobili" }, "location": { "type": "string", "nullable": true, "example": "Москва", "description": "The city Avito files the listing under." }, "address": { "type": "string", "nullable": true, "example": "Москва, Варшавская", "description": "The street- or district-level address where Avito gives one, and the city where it does not." }, "latitude": { "type": "number", "nullable": true, "example": 55.664456, "description": "Avito ships coordinates as strings; they arrive here as numbers." }, "longitude": { "type": "number", "nullable": true, "example": 37.627059 }, "sort_timestamp_ms": { "type": "number", "nullable": true, "example": 1787324360000, "description": "Avito's own ordering key, in milliseconds since the epoch. Named for what it is rather than `published_at`: it is the sort timestamp, and the two diverge whenever a seller bumps a listing." }, "is_new": { "type": "boolean", "nullable": true, "example": false }, "is_verified": { "type": "boolean", "nullable": true, "example": true, "description": "Avito's own verified-listing flag." }, "is_reserved": { "type": "boolean", "nullable": true, "example": false }, "images": { "type": "array", "items": { "type": "string" }, "example": [ "https://00.img.avito.st/image/1/1.DjHNe…" ], "description": "The largest rendition of each photo. Avito ships six widths per image; the widest is chosen by parsing the width, not by taking the last key, because key order is Avito's and not a contract." }, "images_count": { "type": "number", "nullable": true, "example": 32, "description": "How many photos the listing has, as Avito states it. It can exceed `images.length` — the listing page carries more than the snippet." }, "description": { "type": "string", "nullable": true, "example": "1 собственник. ПТС оригинал.", "description": "Seller's listing text. Often null because descriptions are available for only some rows; see `descriptions_available`." }, "attributes": { "type": "string", "nullable": true, "example": "201 463 км, 2.5 AT (181 л.с.), седан, передний, бензин", "description": "Avito's own one-line attribute summary for the category — mileage, engine and body for a car, area and floor for a flat. Republished as the single string Avito renders, because the fields inside it differ per category and splitting them would invent a schema." }, "seller": { "$ref": "#/components/schemas/AvitoSeller" }, "rating": { "type": "number", "nullable": true, "example": 4.5, "description": "The listing's own rating, where Avito states one." } }, "required": [ "id", "url", "title", "price", "price_text", "price_was_lowered", "category", "category_slug", "location", "address", "latitude", "longitude", "sort_timestamp_ms", "is_new", "is_verified", "is_reserved", "images", "images_count", "description", "attributes", "seller", "rating" ] }, "AvitoSeller": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "example": "ТОРГМАШ", "description": "The seller's display name — a dealer name or a person." }, "url": { "type": "string", "nullable": true, "example": "https://www.avito.ru/brands/i116890677", "description": "The seller's own page on Avito, with Avito's referral query stripped." }, "rating": { "type": "number", "nullable": true, "example": 4.5, "description": "The seller's star rating out of 5, where Avito states one." }, "reviews_summary": { "type": "string", "nullable": true, "example": "298 отзывов", "description": "Avito's own phrasing of the review count, republished verbatim. It is localised and pluralised Russian, and a regex over it would be one more thing to get wrong for no gain." } }, "required": [ "name", "url", "rating", "reviews_summary" ], "description": "The seller, where the snippet was hydrated. Null on the same rows `description` is null on, and for the same reason." }, "AvitoSortOption": { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "example": "1", "description": "The value to pass back as `sort`." }, "name": { "type": "string", "nullable": true, "example": "Дешевле", "description": "Avito's own Russian label for it." } }, "required": [ "code", "name" ] }, "GoogleMapsSearchResponse": { "type": "object", "nullable": true, "properties": { "query": { "type": "string", "example": "coffee", "description": "The query this page was read for, echoed back after trimming. `interpreted_query` is what Google decided it meant." }, "latitude": { "type": "number", "example": 37.7749, "description": "The viewport centre latitude this page was read for." }, "longitude": { "type": "number", "example": -122.4194, "description": "The viewport centre longitude this page was read for." }, "span_metres": { "type": "number", "example": 20000, "description": "Search viewport width in metres, echoed from the request." }, "page": { "type": "number", "example": 1, "description": "The page number this response is, echoed back." }, "page_size": { "type": "number", "example": 20, "description": "Maximum businesses on one page: 20." }, "max_pages": { "type": "number", "example": 10, "description": "Maximum page number for one query and viewport. Requests above 10 are rejected." }, "has_more": { "type": "boolean", "example": true, "description": "Whether another page is available for this query and viewport. A short page can still have a following page." }, "count": { "type": "number", "example": 20, "description": "Number of businesses in this response. Pages can overlap, so this is not a count of new businesses; deduplicate accumulated results by `cid`." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleMapsBusiness" }, "description": "Up to 20 complete business records in Google's order. Each row has the same fields as the place endpoint. Empty when the viewport has no matches or the requested page is past the end." }, "interpreted_query": { "type": "string", "nullable": true, "example": "coffee in San Francisco", "description": "Google's interpretation of the query, or `null` when none is provided. Check this when results do not match the submitted text." }, "viewport": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "Map bounds searched for the requested center and span. The value can be an object or positional array; use it when planning adjacent viewports." }, "usage_note": { "type": "string", "example": "Every result is a COMPLETE business record — phone, hours, website and coordinates included — not a stub needing a follow-up call. Each result's `cid` is the exact value /v1/google-maps/place takes. Two things to know when paging: the pages OVERLAP (200 rows across 10 pages held 182 distinct businesses, so deduplicate on `cid`), and the ceiling is per query AND viewport — to cover an area beyond ~182 places, tile it with several smaller `span_metres` rather than asking once with a large one.", "description": "The three things a caller of this endpoint has to know, carried in the body as well as in these docs: every row is already complete, the pages overlap so deduplicate on `cid`, and the ceiling is per query and viewport rather than per site." } }, "required": [ "query", "latitude", "longitude", "span_metres", "page", "page_size", "max_pages", "has_more", "count", "results", "interpreted_query", "viewport", "usage_note" ] }, "GoogleMapsBusiness": { "type": "object", "properties": { "cid": { "type": "string", "nullable": true, "example": "0x808587fb77f5f64d:0x25d564f177f99946", "description": "Google place identifier used by the place and review endpoints. Use it to deduplicate businesses across overlapping search pages." }, "name": { "type": "string", "nullable": true, "example": "The Coffee Movement", "description": "Business name, or `null` when Google provides none." }, "place_id": { "type": "string", "nullable": true, "example": "ChIJ_2f19_uHhYARRpn5d_Fk1SU", "description": "Google Places `ChIJ…` identifier for joining this business with other datasets. Use `cid` with this API's place and review endpoints." }, "feature_id": { "type": "string", "nullable": true, "example": "/g/11h547vvy9", "description": "Google Knowledge Graph feature ID for the same place, or `null` when unavailable." }, "address": { "type": "string", "nullable": true, "example": "1030 Washington St, San Francisco, CA 94108", "description": "Full one-line address. `address_lines` contains display lines, and `address_components` contains the positional structured value." }, "address_lines": { "type": "array", "items": { "type": "string" }, "example": [ "599 3rd St #100", "San Francisco, CA 94107" ], "description": "The address as Google's own display lines — normally the street line and then the locality line. Empty array when the record carries none." }, "address_components": { "type": "array", "nullable": true, "items": { "nullable": true }, "description": "Positional structured address data. Prefer the named `address`, `city`, `neighborhood`, and `country_code` fields when they cover your use case." }, "neighborhood": { "type": "string", "nullable": true, "example": "Chinatown", "description": "The neighbourhood Google files the business under. Null where Google names none, which is common outside dense urban areas." }, "city": { "type": "string", "nullable": true, "example": "San Francisco, CA", "description": "Google's own city label for the business, which on US records carries the state with it — republished as the one string Google states rather than split into a city and a state this layer guessed at." }, "country_code": { "type": "string", "nullable": true, "example": "US", "description": "The two-letter country code for the business." }, "latitude": { "type": "number", "nullable": true, "example": 37.7936, "description": "Business latitude, or `null` when unavailable." }, "longitude": { "type": "number", "nullable": true, "example": -122.4116 }, "timezone": { "type": "string", "nullable": true, "example": "America/Los_Angeles", "description": "IANA timezone for the business. Times in `hours.days[].hours` use this local timezone." }, "categories": { "type": "array", "items": { "type": "string" }, "example": [ "Coffee shop", "Cafe" ], "description": "Google business categories, most specific first. Empty when none are available." }, "rating": { "type": "number", "nullable": true, "example": 4.8, "description": "Google Maps star rating out of 5, or `null` when unavailable. This record does not include a reliable review count; use the reviews endpoint to retrieve and count reviews." }, "phone": { "type": "string", "nullable": true, "example": "(415) 780-1902", "description": "Business phone number in its local display format. `phone_e164` is the dialable international form when available." }, "phone_e164": { "type": "string", "nullable": true, "example": "+14157801902", "description": "The same number in E.164 form — country code, no separators — which is what a dialer, a CRM or a WhatsApp integration takes. Google states both forms, so both are published rather than one being derived from the other by guessing a country." }, "website": { "type": "string", "nullable": true, "example": "https://www.thecoffeemovement.com/", "description": "Business website, or `null` when unavailable." }, "website_domain": { "type": "string", "nullable": true, "example": "thecoffeemovement.com", "description": "Google's own display form of the same link, which is the domain without the scheme or the tracking a full URL may carry. Convenient as a join key when matching these businesses against another dataset." }, "description": { "type": "string", "nullable": true, "example": "Cozy cafe serving single-origin espresso and pastries.", "description": "Google's editorial description of the business, where it has written one. Frequently null — it is a Google-authored blurb rather than the owner's, and most listings do not have one." }, "hours": { "$ref": "#/components/schemas/GoogleMapsHours" }, "attributes": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "Accessibility": [ "Wheelchair accessible entrance", "Wheelchair accessible restroom" ], "Amenities": [ "Restroom", "Wi-Fi" ] }, "description": "Business attributes grouped by Google's labels, such as accessibility, amenities, payment options, and service options. Groups vary by business and category; `null` means none were listed." }, "photos": { "type": "array", "items": { "type": "string" }, "example": [ "https://lh3.googleusercontent.com/p/AF1QipN-example=w408-h306-k-no" ], "description": "Up to ten business photo URLs in display order; the first is the cover photo. Empty when no photos are available." }, "maps_url": { "type": "string", "nullable": true, "example": "https://www.google.com/maps/place/?q=place_id:ChIJ_2f19_uHhYAR", "description": "Google's own link to the place. Public: open it and you see the same business. You do not need it to fetch the record again — pass `cid` to `/v1/google-maps/place`." } }, "required": [ "cid", "name", "place_id", "feature_id", "address", "address_lines", "address_components", "neighborhood", "city", "country_code", "latitude", "longitude", "timezone", "categories", "rating", "phone", "phone_e164", "website", "website_domain", "description", "hours", "attributes", "photos", "maps_url" ] }, "GoogleMapsHours": { "type": "object", "nullable": true, "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleMapsHoursDay" }, "description": "Opening hours for the current day. This list is not a weekly schedule." }, "status": { "type": "string", "nullable": true, "example": "Closed · Opens 8 AM Mon", "description": "Current opening status and the next change, such as `\"Closed · Opens 8 AM Mon\"`." } }, "required": [ "days", "status" ], "description": "Current-day opening hours and status. This is not a weekly schedule; the whole object is `null` when Google provides no hours." }, "GoogleMapsHoursDay": { "type": "object", "properties": { "day": { "type": "string", "nullable": true, "example": "Saturday", "description": "Weekday for this entry, usually the current day. See `days` for the scope of the hours data." }, "hours": { "type": "array", "items": { "type": "string" }, "example": [ "9 AM–2 PM" ], "description": "Displayed opening spans for this day. Multiple entries indicate a break; an empty array means the business is closed for the day." }, "date": { "type": "array", "nullable": true, "items": { "type": "number" }, "example": [ 2026, 8, 15 ], "description": "Calendar date for this entry as `[year, month, day]`, or `null` when Google provides no date." } }, "required": [ "day", "hours", "date" ] }, "GoogleMapsPlaceResponse": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/GoogleMapsBusiness" }, { "type": "object", "properties": { "requested_cid": { "type": "string", "example": "0x808587fb77f5f64d:0x25d564f177f99946", "description": "The cid this record was read for, echoed back after cleaning — so a caller who pasted a Maps URL can see the id it resolved to. It will equal the record's own `cid`: a response whose identity does not match the request is refused rather than published." }, "usage_note": { "type": "string", "example": "This is the same record /v1/google-maps/search returns for every row, so calling this after a search repeats work that has already been paid for. It is here for callers who arrive holding a cid.", "description": "The one thing a caller of this endpoint has to know, carried in the body as well as in these docs: this is the same record `/v1/google-maps/search` already returns for every row." } }, "required": [ "requested_cid", "usage_note" ] } ] }, { "nullable": true } ] }, "GoogleMapsReviewsResponse": { "type": "object", "nullable": true, "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleMapsReview" }, "description": "Up to 20 reviews, newest first. An empty array means the place has no reviews; use `has_more` rather than page length to decide whether to continue." }, "count": { "type": "number", "example": 20, "description": "Number of reviews in this response. This is neither a paging signal nor the place's total review count; use `has_more` to continue." }, "next_cursor": { "type": "string", "nullable": true, "example": "0x808587fb77f5f64d:0x25d564f177f99946|CAESY0NBRVFBUm9VUTJoa1p...", "description": "Cursor for the next review page, or `null` at the end. Pass it back unchanged with the same `cid`; the cursor is opaque and cannot be constructed or reused for another place." }, "has_more": { "type": "boolean", "example": true, "description": "Whether another review page is available. Stop when this is `false`, even if earlier pages contained fewer reviews than requested." }, "requested_cid": { "type": "string", "example": "0x808587fb77f5f64d:0x25d564f177f99946", "description": "The cid these reviews were read for, echoed back after cleaning — so a caller who pasted a Maps URL can see the id it resolved to, and so a stored page is identifiable without the request beside it. It is also the cid half of `next_cursor`." }, "usage_note": { "type": "string", "example": "Newest first, and walking every `next_cursor` returns the COMPLETE corpus — measured against Maps' own displayed count on four places: 338/338, 1722/1723, 1782/1782 and 5950/5950, zero duplicate review ids across 492 pages. Pages hold at most 20 reviews. Reviews with a null `text` are star-only ratings, not broken rows: they are ~25-40% of the corpus and Maps counts them too. `next_cursor` is bound to this `cid` and cannot be used with another place. Stop when `has_more` is false, not when a page comes back short — the last page is usually both full-ish and final.", "description": "The four things a caller of this endpoint has to know, carried in the body as well as in these docs: the walk returns the complete corpus, stop on `has_more` rather than on a short page, a null `text` is a star-only rating, and a cursor belongs to its place." } }, "required": [ "reviews", "count", "next_cursor", "has_more", "requested_cid", "usage_note" ] }, "GoogleMapsReview": { "type": "object", "properties": { "review_id": { "type": "string", "example": "ChZDSUhNMG9nS0VJQ0FnSURfeGV5RVh3EAE", "description": "Google review ID and the key to use for deduplication." }, "place_ref": { "type": "string", "nullable": true, "example": "0x0:0x25d564f177f99946", "description": "Abbreviated Google place reference for this review. It corresponds to `requested_cid`." }, "rating": { "type": "number", "nullable": true, "example": 5, "description": "Reviewer's star rating from 1 to 5. It can be present when `text` is `null`." }, "text": { "type": "string", "nullable": true, "example": "Best espresso in the neighbourhood. Tiny room, huge care.", "description": "Review text. `null` means the reviewer submitted a star rating without text; these rows still count as reviews." }, "language": { "type": "string", "nullable": true, "example": "en", "description": "The language Google detected the review to be in. Null on a star-only row, which has no text to detect." }, "created_at_us": { "type": "number", "nullable": true, "example": 1747224000000000, "description": "Review creation time in microseconds since the Unix epoch. Divide by 1,000 for milliseconds or 1,000,000 for seconds." }, "updated_at_us": { "type": "number", "nullable": true, "example": 1747224000000000, "description": "Last edit time in microseconds since the Unix epoch. Equal to `created_at_us` when the review has not been edited." }, "relative_time": { "type": "string", "nullable": true, "example": "3 months ago", "description": "Displayed review age at the time of retrieval. Use `created_at_us` for calculations." }, "author": { "$ref": "#/components/schemas/GoogleMapsReviewAuthor" }, "photos": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/GoogleMapsReviewPhoto" }, "description": "Photos attached to the review, or `null` when there are none." }, "owner_response": { "$ref": "#/components/schemas/GoogleMapsOwnerResponse" } }, "required": [ "review_id", "place_ref", "rating", "text", "language", "created_at_us", "updated_at_us", "relative_time", "author", "photos", "owner_response" ] }, "GoogleMapsReviewAuthor": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Alex Rivera", "description": "The reviewer's display name, as Google files it." }, "id": { "type": "string", "nullable": true, "example": "112233445566778899000", "description": "Google's own id for the reviewer. Stable across their reviews, so it is what joins one person's reviews together across places — the display name is not unique and is renameable." }, "avatar": { "type": "string", "nullable": true, "example": "https://lh3.googleusercontent.com/a/example=s120-c-rp-mo-br100", "description": "The reviewer's profile photo URL." }, "profile_url": { "type": "string", "nullable": true, "example": "https://www.google.com/maps/contrib/112233445566778899000", "description": "Google's public link to the reviewer's contributions page." }, "review_count": { "type": "number", "nullable": true, "example": 87, "description": "How many reviews this person has written, as Google states it on their profile — an author statistic, not a fact about this review. Useful as a weak signal of how practised a reviewer is." }, "photo_count": { "type": "number", "nullable": true, "example": 412, "description": "How many photos this person has contributed, same source and same caveat as `review_count`." }, "local_guide_level": { "type": "number", "nullable": true, "example": 7, "description": "The reviewer's Local Guide level where Google states one, null where they are not a Local Guide." } }, "required": [ "name", "id", "avatar", "profile_url", "review_count", "photo_count", "local_guide_level" ], "description": "Reviewer's public profile and contribution statistics. Counts here describe the author, not engagement with this review." }, "GoogleMapsReviewPhoto": { "type": "object", "properties": { "url": { "type": "string", "example": "https://lh5.googleusercontent.com/p/AF1QipExample", "description": "The photo URL. A photo without one is not published." }, "width": { "type": "number", "nullable": true, "example": 4032, "description": "Pixel width as Google states it, null where it does not." }, "height": { "type": "number", "nullable": true, "example": 3024, "description": "Pixel height as Google states it, null where it does not." } }, "required": [ "url", "width", "height" ] }, "GoogleMapsOwnerResponse": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "example": "Thank you for the kind words — see you next time!", "description": "The reply's text. A reply with no text is not published at all, which is why this is the one field here that is never null." }, "created_at_us": { "type": "number", "nullable": true, "example": 1755212345678901, "description": "When the reply was posted, in microseconds since the epoch — Google's own integer, republished rather than reformatted. Divide by 1,000 for milliseconds." }, "updated_at_us": { "type": "number", "nullable": true, "example": 1755212345678901, "description": "When the reply was last edited, same units. Equal to `created_at_us` on a reply that has never been edited." }, "relative_time": { "type": "string", "nullable": true, "example": "2 months ago", "description": "Displayed age of the reply at retrieval time. Use `created_at_us` for calculations." }, "language": { "type": "string", "nullable": true, "example": "en", "description": "The language Google detected the reply to be in." } }, "required": [ "text", "created_at_us", "updated_at_us", "relative_time", "language" ], "description": "Business owner's public reply. The field is `null` when the review has no owner response." }, "XUser": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "11348282", "description": "X's own numeric id for the account, as a string. Stable across a rename, which the handle is not — an account that changes its handle keeps this. Published as a string because X's ids exceed what a JSON number holds exactly." }, "handle": { "type": "string", "nullable": true, "example": "NASA", "description": "The account's current handle, in X's own casing — which is usually not the casing you asked with. `@nasa` resolves to `NASA` here. Compare it against `requested_handle` if you are joining on the value you sent." }, "name": { "type": "string", "nullable": true, "example": "NASA", "description": "The display name, which is free text and changes freely." }, "description": { "type": "string", "nullable": true, "example": "There's space for everybody. ✨", "description": "The account's public bio." }, "location": { "type": "string", "nullable": true, "example": "Pale Blue Dot", "description": "Free-form profile location. This value is not a verified address." }, "website": { "type": "string", "nullable": true, "example": "http://nasa.gov", "description": "The link in the profile header, as the account stated it. Usually an X short link (`t.co/…`) on accounts that set it recently; not followed or expanded here." }, "created_at": { "type": "string", "nullable": true, "example": "Wed Dec 19 20:20:32 +0000 2007", "description": "Account creation time in X's date format." }, "followers_count": { "type": "number", "nullable": true, "example": 92304095, "description": "Number of followers reported by X." }, "following_count": { "type": "number", "nullable": true, "example": 119, "description": "How many accounts this one follows. X calls it `friends_count` in the older shape and `following` in the newer; both are read." }, "tweet_count": { "type": "number", "nullable": true, "example": 74339, "description": "Total number of posts reported by X. This is not the number of posts returned by a timeline request." }, "listed_count": { "type": "number", "nullable": true, "example": 79251, "description": "How many public lists include this account." }, "media_count": { "type": "number", "nullable": true, "example": 15064, "description": "Number of the account's posts that contain media, as reported by X." }, "favourites_count": { "type": "number", "nullable": true, "example": 15299, "description": "Number of posts the account has liked." }, "verified": { "type": "boolean", "nullable": true, "example": false, "description": "Legacy verification status. Read `is_blue_verified` for the current verification mark." }, "is_blue_verified": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the account currently has X's blue verification mark." }, "protected": { "type": "boolean", "nullable": true, "example": false, "description": "Whether posts are restricted to approved followers. Protected timelines return an empty posts page." }, "profile_image_url": { "type": "string", "nullable": true, "example": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg", "description": "Account avatar URL at the size supplied by X." }, "profile_banner_url": { "type": "string", "nullable": true, "example": "https://pbs.twimg.com/profile_banners/11348282/1600956165", "description": "The header image. Null on accounts that never set one." }, "professional": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "example": null, "description": "Professional-account type and categories. Fields vary by account; null for non-professional accounts." }, "requested_handle": { "type": "string", "nullable": true, "example": "nasa", "description": "Normalized handle from the request. Its letter casing may differ from `handle`." } }, "required": [ "id", "handle", "name", "description", "location", "website", "created_at", "followers_count", "following_count", "tweet_count", "listed_count", "media_count", "favourites_count", "verified", "is_blue_verified", "protected", "profile_image_url", "profile_banner_url", "professional", "requested_handle" ] }, "XTweetsResponse": { "type": "object", "nullable": true, "properties": { "tweets": { "type": "array", "items": { "$ref": "#/components/schemas/XTweet" }, "description": "Posts on this timeline page. A short page can still have more results; use `has_more`. Each `id` can be sent to `/v1/x/tweet`." }, "count": { "type": "number", "example": 12, "description": "Number of posts in `tweets`. Use `has_more`, not this count, to decide whether to continue." }, "next_cursor": { "type": "string", "nullable": true, "example": "DAABCgABGxxxxxxxxxxxLAAA", "description": "Cursor to send as `cursor` for the next page. Null means no later page is available." }, "has_more": { "type": "boolean", "example": true, "description": "Whether another page is available. This is true when `next_cursor` exists and the page contains posts; a short non-empty page can still return true." }, "handle": { "type": "string", "nullable": true, "example": "NASA", "description": "The account this timeline belongs to, in X's own casing — resolved from the handle you sent, which is usually cased differently." }, "user_id": { "type": "string", "nullable": true, "example": "11348282", "description": "Stable account ID for the returned timeline." }, "requested_count": { "type": "number", "example": 20, "description": "Requested post count. Compare with `count` to see how many posts were returned." }, "cursor": { "type": "string", "nullable": true, "example": null, "description": "The cursor this request used, echoed. Null on the first page. It makes a page in a log identifiable without the request beside it." }, "usage_note": { "type": "string", "example": "Send `next_cursor` to continue the timeline. A page may contain fewer posts than `count` while more results remain, so use `has_more` to determine when the timeline ends. Each post's `id` can be sent to `/v1/x/tweet`.", "description": "The one paging rule this endpoint runs on, restated on every response so it survives a caller who never read this document." } }, "required": [ "tweets", "count", "next_cursor", "has_more", "handle", "user_id", "requested_count", "cursor", "usage_note" ] }, "XTweet": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "1978472698594644405", "description": "The tweet's id, and the exact value `/v1/x/tweet` takes. That is the composition point of this whole platform: every row of a timeline page, and every tweet nested inside one, is directly fetchable with nothing constructed. Published as a string because X's snowflake ids exceed what a JSON number holds exactly." }, "text": { "type": "string", "nullable": true, "example": "There's space for everybody. ✨", "description": "Post text. For reposts, this may contain a truncated `RT @handle` form and `retweeted_tweet.text` contains the original. For long posts, this contains the full note text and `is_long_post` is true." }, "is_long_post": { "type": "boolean", "example": false, "description": "Whether `text` contains the full body of an X note post." }, "created_at": { "type": "string", "nullable": true, "example": "Wed Oct 15 18:32:11 +0000 2025", "description": "Post creation time in X's date format." }, "lang": { "type": "string", "nullable": true, "example": "en", "description": "X's own language guess for the post, as a BCP-47-ish code. `qme`, `zxx` and `und` are real values it uses for posts it considers media- only or undetermined." }, "conversation_id": { "type": "string", "nullable": true, "example": "1978472698594644405", "description": "ID of the conversation containing this post. Equal to `id` when the post starts the conversation." }, "reply_to_tweet_id": { "type": "string", "nullable": true, "example": null, "description": "ID of the parent post, or null when this post is not a reply. Send it to `/v1/x/tweet` to get the parent." }, "reply_to_handle": { "type": "string", "nullable": true, "example": null, "description": "The handle being replied to, when this post is a reply." }, "like_count": { "type": "number", "nullable": true, "example": 2341, "description": "X's `favorite_count`, renamed to what the button says." }, "retweet_count": { "type": "number", "nullable": true, "example": 412 }, "reply_count": { "type": "number", "nullable": true, "example": 88, "description": "Number of replies reported by X." }, "quote_count": { "type": "number", "nullable": true, "example": 17 }, "bookmark_count": { "type": "number", "nullable": true, "example": 231, "description": "Number of bookmarks reported by X." }, "view_count": { "type": "number", "nullable": true, "example": 54752, "description": "View count as a number. Null means X did not publish a view count; it does not mean zero views." }, "possibly_sensitive": { "type": "boolean", "nullable": true, "example": false, "description": "X's own sensitive-content flag on the post." }, "entities": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "example": null, "description": "X entities such as hashtags, URLs, user mentions, symbols, and media. Fields vary with the post's content." }, "author": { "$ref": "#/components/schemas/XTweetAuthor" }, "is_retweet": { "type": "boolean", "example": false, "description": "Whether this post is a repost. For reposts, use `retweeted_tweet` for the original text and author." }, "is_quote": { "type": "boolean", "example": false, "description": "Whether this post quotes another. When true, `quoted_tweet` carries the quoted post in full — `text` here is the commentary and `text` there is what is being commented on." }, "retweeted_tweet": { "allOf": [ { "$ref": "#/components/schemas/XTweet" }, { "nullable": true } ] }, "quoted_tweet": { "allOf": [ { "$ref": "#/components/schemas/XTweet" }, { "nullable": true } ] } }, "required": [ "id", "text", "is_long_post", "created_at", "lang", "conversation_id", "reply_to_tweet_id", "reply_to_handle", "like_count", "retweet_count", "reply_count", "quote_count", "bookmark_count", "view_count", "possibly_sensitive", "entities", "author", "is_retweet", "is_quote", "retweeted_tweet", "quoted_tweet" ] }, "XTweetAuthor": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "example": "11348282", "description": "The author's account id, as a string. Stable across a rename." }, "handle": { "type": "string", "nullable": true, "example": "NASA", "description": "The author's handle, which is what makes a retweet or a quote attributable. On a retweet the outer tweet's author is the account that retweeted and `retweeted_tweet.author` is who wrote it." }, "name": { "type": "string", "nullable": true, "example": "NASA" }, "verified": { "type": "boolean", "nullable": true, "example": false, "description": "Legacy verification. `false` on most currently-verified accounts — see `is_blue_verified` beside it." }, "is_blue_verified": { "type": "boolean", "nullable": true, "example": true, "description": "The current verification mark, and the one to read." }, "followers_count": { "type": "number", "nullable": true, "example": 92304095, "description": "The author's follower count, riding along with every tweet. It is why a timeline page is worth more than a list of texts: reach is attached to each row without a second call per author." }, "profile_image_url": { "type": "string", "nullable": true, "example": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg" } }, "required": [ "id", "handle", "name", "verified", "is_blue_verified", "followers_count", "profile_image_url" ], "description": "Who posted it, with their follower count attached. On a retweet this is the account that retweeted; `retweeted_tweet.author` is who wrote the original." }, "XTweetResponse": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/XTweet" }, { "type": "object", "properties": { "requested_tweet_id": { "type": "string", "nullable": true, "example": "1978472698594644405", "description": "The id this request asked for, after cleaning — with any pasted status URL already reduced away, so a join against your own input never rests on two layers agreeing about normalisation. It will equal the record's own `id`." }, "usage_note": { "type": "string", "example": "On a repost, `text` may be truncated; `retweeted_tweet` contains the original post when available.", "description": "The two things a caller of this endpoint has to know, carried in the body as well as in these docs: what it does not return, and which `text` you are reading on a retweet." } }, "required": [ "requested_tweet_id", "usage_note" ] } ] }, { "nullable": true } ] }, "AuthenticityReport": { "type": "object", "nullable": true, "properties": { "authenticity_score": { "type": "number", "example": 62, "description": "0–100, higher is more consistent with an organic review set. It is a summary of the evidence below, not a verdict: read `flags` before acting on it." }, "reviews_analyzed": { "type": "integer", "example": 40 }, "signal_coverage": { "type": "array", "items": { "type": "object", "properties": { "signal": { "type": "string", "enum": [ "burstiness", "rating_shape", "text_duplication", "template_phrasing", "reviewer_pattern" ] }, "applicable": { "type": "boolean" }, "skipped_reason": { "type": "string", "nullable": true, "example": "not_enough_dated_reviews" }, "usable_reviews": { "type": "integer", "example": 38 } }, "required": [ "signal", "applicable", "skipped_reason", "usable_reviews" ] }, "description": "Which of the five signals could be measured on this input. A signal that could not run scores nothing in either direction — check this before reading a high score as a clean bill of health." }, "distribution": { "type": "object", "properties": { "suspicion": { "type": "object", "properties": { "low": { "type": "integer", "example": 31 }, "medium": { "type": "integer", "example": 5 }, "high": { "type": "integer", "example": 4 } }, "required": [ "low", "medium", "high" ] }, "ratings": { "type": "object", "nullable": true, "additionalProperties": { "type": "number" }, "example": { "1": 6, "2": 1, "3": 2, "4": 4, "5": 27 }, "description": "Histogram by whole star. Null when too few reviews carried a rating to measure a shape." } }, "required": [ "suspicion", "ratings" ] }, "flags": { "type": "array", "items": { "$ref": "#/components/schemas/AuthenticityFlag" }, "description": "Findings about the SET rather than any one review — burst windows, rating bimodality, duplicate-text clusters. Ordered most severe first." }, "signals": { "type": "object", "additionalProperties": { "type": "object", "properties": { "applicable": { "type": "boolean" }, "aggregate": { "$ref": "#/components/schemas/AuthenticityEvidence" } }, "required": [ "applicable", "aggregate" ] }, "description": "Per-signal corpus measurements, keyed by signal name. Present whether or not the signal fired, so a clean set shows its numbers too." }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ScoredReview" } } }, "required": [ "authenticity_score", "reviews_analyzed", "signal_coverage", "distribution", "flags", "signals", "reviews" ] }, "AuthenticityFlag": { "type": "object", "properties": { "type": { "type": "string", "example": "duplicate_text_cluster" }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "example": "high" }, "summary": { "type": "string", "example": "2 near-duplicate text clusters covering 9 of 40 reviews with usable text; 2 span more than one reviewer.", "description": "One plain sentence, safe to show an end user." }, "evidence": { "$ref": "#/components/schemas/AuthenticityEvidence" } }, "required": [ "type", "severity", "summary", "evidence" ] }, "AuthenticityEvidence": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The measurement behind a finding, in the units it was measured in. Fields differ by signal and new ones may be added." }, "ScoredReview": { "type": "object", "properties": { "index": { "type": "integer", "example": 7, "description": "Position in the `reviews` array you sent." }, "id": { "type": "string", "nullable": true, "example": "6a80e73565b884964e2bc035" }, "suspicion": { "type": "string", "enum": [ "low", "medium", "high" ], "example": "high" }, "suspicion_score": { "type": "number", "example": 0.7, "description": "Sum of the weights of every signal that fired on this review, capped at 1. `medium` starts at 0.3, `high` at 0.6." }, "signals": { "type": "array", "items": { "type": "object", "properties": { "signal": { "type": "string", "enum": [ "burstiness", "rating_shape", "text_duplication", "template_phrasing", "reviewer_pattern" ], "example": "text_duplication" }, "weight": { "type": "number", "example": 0.55 }, "evidence": { "$ref": "#/components/schemas/AuthenticityEvidence" } }, "required": [ "signal", "weight", "evidence" ] }, "description": "Which heuristics fired and what each one measured. An empty array means nothing fired — not that the review was verified." } }, "required": [ "index", "id", "suspicion", "suspicion_score", "signals" ] }, "AuthenticityRequest": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "trustpilot", "google-maps", "yelp", "glassdoor", "tripadvisor", "airbnb", "booking", "g2", "capterra", "app-store", "google-play", "tiktok-shop", "rednote", "amazon", "other" ], "default": "other", "example": "trustpilot", "description": "Where the reviews came from. Recorded on the response and used for nothing else in v1: no per-platform reference curve is applied unless you supply one in `rating_baseline`." }, "rating_scale": { "type": "integer", "minimum": 2, "maximum": 10, "default": 5, "example": 5, "description": "Highest possible rating. 5 on Trustpilot, Google Maps, Yelp, Glassdoor and TripAdvisor; 10 on Booking." }, "burst_window_days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 3, "example": 3, "description": "Width of the sliding window the burst check counts reviews in. Widen it for a business that reviews slowly, narrow it to catch a single-day drop." }, "rating_baseline": { "type": "object", "nullable": true, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "example": { "1": 0.12, "2": 0.03, "3": 0.04, "4": 0.09, "5": 0.72 }, "description": "Your own reference rating curve for this platform, keyed by star as a string. Supply it and the response reports the total-variation distance from it. Omit it and shape statistics are used alone — we publish no reference curve we have not measured." }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewInput" }, "minItems": 1, "maxItems": 500, "description": "The review set for ONE business or listing, up to 500 per request. Mixing several businesses into one array invalidates every signal here, all of which measure a set against its own baseline." } }, "required": [ "reviews" ] }, "ReviewInput": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "maxLength": 200, "example": "6a80e73565b884964e2bc035", "description": "Your own identifier for this review. Echoed back on the scored row so you can join the result to your data. Never used as a signal." }, "rating": { "type": "number", "nullable": true, "example": 5, "description": "The star rating, on the scale given by `rating_scale`. Rounded to the nearest whole star before the distribution is measured. Omit where the platform publishes none." }, "text": { "type": "string", "nullable": true, "maxLength": 10000, "example": "Delivery was quick and the packaging was intact.", "description": "The review body. Used for near-duplicate clustering and repeated-phrase detection. Never logged, never stored, never sent anywhere." }, "date": { "type": "string", "nullable": true, "maxLength": 64, "example": "2026-08-16T00:24:53.000Z", "description": "When the review was published, ISO 8601 or any date string `Date.parse` accepts. Resolved to a whole UTC day. Unparseable values are skipped rather than rejected." }, "reviewer_name": { "type": "string", "nullable": true, "maxLength": 200, "example": "Rosemary Hart", "description": "Display name, where the platform publishes one. Only its SHAPE is returned in evidence (`Aaaaaaaa Aaaa`) — the name itself is never echoed back or logged." }, "reviewer_id": { "type": "string", "nullable": true, "maxLength": 200, "example": "6379404e69c66a0012fb0e39", "description": "Stable account identifier, where the platform publishes one. Used to tell 'six accounts wrote this' apart from 'one account wrote it six times'." }, "reviewer_review_count": { "type": "integer", "nullable": true, "minimum": 0, "example": 5, "description": "How many reviews the account has written in total. Trustpilot publishes this; Google Maps and Glassdoor do not. Absent means the single-review-account check is skipped, not passed." } } } } } }