{ "openapi": "3.0.0", "info": { "title": "Meta-Facebook Ad library Scraper API", "description": "Search and inspect Meta (Facebook/Instagram) Ad Library data — ad search by keyword or advertiser, ad details, advertiser pages, and filter options.", "version": "1.0.0", "x-category": "Advertising", "x-long-description": "Search and inspect Meta (Facebook/Instagram) Ad Library data — ad search by keyword or advertiser, ad details, advertiser pages, and filter options.\n\nContact us at *contact@toolzerhub.com* for any query or issue", "x-website": "https://toolzerhub.com", "x-public": true }, "x-documentation": { "readme": "Search and inspect Meta (Facebook/Instagram) Ad Library data — ad search by keyword or advertiser, ad details, advertiser pages, and filter options.\n\nContact us at *contact@toolzerhub.com* for any query or issue" }, "servers": [ { "url": "https://api.toolzerhub.com", "description": "Production" } ], "tags": [ { "name": "Meta Ads", "description": "Search and inspect Meta (Facebook/Instagram) Ad Library data — ad search by keyword or advertiser, ad details, advertiser pages, and filter options." } ], "paths": { "/v1/meta/resolve-url": { "get": { "operationId": "Resolve Meta Ads URL", "tags": [ "Meta Ads" ], "summary": "URL resolution", "description": "Returns the API operation and parameters represented by required public Ad Library `url`. The response contains resolution data only, not ads.", "parameters": [ { "schema": { "type": "string", "maxLength": 2000, "format": "uri", "example": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=running%20shoes&search_type=keyword_unordered", "description": "A public Facebook Meta Ad Library search or page-browse URL." }, "required": true, "description": "A public Facebook Meta Ad Library search or page-browse URL.", "name": "url", "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": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "search" ] }, "params": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "Search keyword, phrase, or advertiser name.", "example": "flipkart" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "active_status": { "type": "string", "enum": [ "all", "active", "inactive" ], "description": "Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads." }, "ad_type": { "type": "string", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "description": "Ad category. ALL includes all ad types; other values narrow results to the selected category." }, "search_type": { "type": "string", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "description": "Query match mode. keyword_unordered matches all words in any order; keyword_exact_phrase matches the exact phrase." }, "media_type": { "type": "string", "enum": [ "all", "image", "video", "meme" ], "description": "Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives." }, "sort_mode": { "type": "string", "enum": [ "total_impressions" ], "description": "Sort by total impressions." }, "sort_direction": { "type": "string", "enum": [ "desc" ], "description": "Sort direction. Use with sort_mode." }, "date_min": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start Date in YYYY-MM-DD format.", "example": "2026-01-01" }, "date_max": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End Date in YYYY-MM-DD format.", "example": "2026-12-31" }, "content_languages": { "type": "string", "description": "Comma-separated ISO 639-1 language codes, for example en,hi.", "example": "en,hi" }, "publisher_platforms": { "type": "string", "description": "Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.", "example": "FACEBOOK,INSTAGRAM" }, "page_ids": { "type": "string", "description": "Comma-separated page IDs to limit results to selected advertisers.", "example": "102988293558,10369058551" }, "is_targeted_country": { "type": "boolean", "description": "When true, only return ads targeted to the selected country." }, "potential_reach_min": { "type": "integer", "nullable": true, "minimum": 0, "description": "Minimum estimated audience size." }, "potential_reach_max": { "type": "integer", "nullable": true, "minimum": 0, "description": "Maximum estimated audience size." } }, "required": [ "q" ] } }, "required": [ "operation", "params" ] }, { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "page" ] }, "params": { "type": "object", "properties": { "page_id": { "type": "string", "minLength": 1, "description": "Page ID of the advertiser.", "example": "102988293558" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "active_status": { "type": "string", "enum": [ "all", "active", "inactive" ], "description": "Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads." }, "media_type": { "type": "string", "enum": [ "all", "image", "video", "meme" ], "description": "Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives." }, "sort_mode": { "type": "string", "enum": [ "total_impressions" ], "description": "Sort by total impressions." }, "sort_direction": { "type": "string", "enum": [ "desc" ], "description": "Sort direction. Use with sort_mode." }, "date_min": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start Date in YYYY-MM-DD format.", "example": "2026-01-01" }, "date_max": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End Date in YYYY-MM-DD format.", "example": "2026-12-31" }, "content_languages": { "type": "string", "description": "Comma-separated ISO 639-1 language codes, for example en,hi.", "example": "en,hi" }, "publisher_platforms": { "type": "string", "description": "Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.", "example": "FACEBOOK,INSTAGRAM" } }, "required": [ "page_id" ] } }, "required": [ "operation", "params" ] }, { "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 } }, "/v1/meta/search": { "get": { "operationId": "Search Ads", "tags": [ "Meta Ads" ], "summary": "Ad search", "description": "Returns ads matching required `q`. Optional fields filter by country, status, type, media, date, language, platform, page, and reach; use `cursor` for pagination.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Search keyword, phrase, or advertiser name.", "example": "flipkart" }, "required": true, "description": "Search keyword, phrase, or advertiser name.", "name": "q", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "required": false, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "name": "country", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "active", "inactive" ], "description": "Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads." }, "required": false, "description": "Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads.", "name": "active_status", "in": "query" }, { "schema": { "type": "string", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "description": "Ad category. ALL includes all ad types; other values narrow results to the selected category." }, "required": false, "description": "Ad category. ALL includes all ad types; other values narrow results to the selected category.", "name": "ad_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "description": "Query match mode. keyword_unordered matches all words in any order; keyword_exact_phrase matches the exact phrase." }, "required": false, "description": "Query match mode. keyword_unordered matches all words in any order; keyword_exact_phrase matches the exact phrase.", "name": "search_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "image", "video", "meme" ], "description": "Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives." }, "required": false, "description": "Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives.", "name": "media_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "total_impressions" ], "description": "Sort by total impressions." }, "required": false, "description": "Sort by total impressions.", "name": "sort_mode", "in": "query" }, { "schema": { "type": "string", "enum": [ "desc" ], "description": "Sort direction. Use with sort_mode." }, "required": false, "description": "Sort direction. Use with sort_mode.", "name": "sort_direction", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor from the previous response." }, "required": false, "description": "Pagination cursor from the previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Number of ads to return per request. Accepted range: 1-50.", "example": 10 }, "required": false, "description": "Number of ads to return per request. Accepted range: 1-50.", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start Date in YYYY-MM-DD format.", "example": "2026-01-01" }, "required": false, "description": "Start Date in YYYY-MM-DD format.", "name": "date_min", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End Date in YYYY-MM-DD format.", "example": "2026-12-31" }, "required": false, "description": "End Date in YYYY-MM-DD format.", "name": "date_max", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated ISO 639-1 language codes, for example en,hi.", "example": "en,hi" }, "required": false, "description": "Comma-separated ISO 639-1 language codes, for example en,hi.", "name": "content_languages", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.", "example": "FACEBOOK,INSTAGRAM" }, "required": false, "description": "Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.", "name": "publisher_platforms", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated page IDs to limit results to selected advertisers.", "example": "102988293558,10369058551" }, "required": false, "description": "Comma-separated page IDs to limit results to selected advertisers.", "name": "page_ids", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, only return ads targeted to the selected country." }, "required": false, "description": "When true, only return ads targeted to the selected country.", "name": "is_targeted_country", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Minimum estimated audience size." }, "required": false, "description": "Minimum estimated audience size.", "name": "potential_reach_min", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Maximum estimated audience size." }, "required": false, "description": "Maximum estimated audience size.", "name": "potential_reach_max", "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": { "items": { "type": "array", "items": { "type": "object", "properties": { "ad_archive_id": { "type": "string", "minLength": 1 }, "page_id": { "type": "string", "nullable": true, "minLength": 1 } }, "required": [ "ad_archive_id" ], "additionalProperties": { "nullable": true } } }, "pageInfo": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true }, "hasNextPage": { "type": "boolean" } }, "required": [ "cursor", "hasNextPage" ] } }, "required": [ "items", "pageInfo" ] } }, "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 } }, "/v1/meta/ad-details": { "get": { "operationId": "Get Ad Details", "tags": [ "Meta Ads" ], "summary": "Ad", "description": "Returns metadata for one ad. Requires `ad_archive_id` and advertiser `page_id`; `country` and `raw` are optional.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Ad archive ID.", "example": "527778036512305" }, "required": true, "description": "Ad archive ID.", "name": "ad_archive_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Page ID of the advertiser.", "example": "102988293558" }, "required": true, "description": "Page ID of the advertiser.", "name": "page_id", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "required": false, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "name": "country", "in": "query" }, { "schema": { "type": "boolean", "description": "Set to true to return the raw response payload.", "example": false }, "required": false, "description": "Set to true to return the raw response payload.", "name": "raw", "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": { "advertiser": { "type": "object", "nullable": true, "properties": { "page": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1 } }, "additionalProperties": { "nullable": true } } }, "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 } }, "/v1/meta/filter-options": { "get": { "operationId": "Get Filter Options", "tags": [ "Meta Ads" ], "summary": "Filter options", "description": "Returns available languages, pages, and regions for required `query_string`. Optional fields set ad type, country, search type, and raw response mode.", "parameters": [ { "schema": { "type": "string", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "description": "Ad category context for filter discovery." }, "required": false, "description": "Ad category context for filter discovery.", "name": "ad_type", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "required": false, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "name": "country", "in": "query" }, { "schema": { "type": "string", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "description": "Query match mode. keyword_unordered matches all words in any order; keyword_exact_phrase matches the exact phrase." }, "required": false, "description": "Query match mode. keyword_unordered matches all words in any order; keyword_exact_phrase matches the exact phrase.", "name": "search_type", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search query used to return context-specific filter options.", "example": "flipkart" }, "required": true, "description": "Search query used to return context-specific filter options.", "name": "query_string", "in": "query" }, { "schema": { "type": "boolean", "description": "Set to true to return the raw response payload.", "example": false }, "required": false, "description": "Set to true to return the raw response payload.", "name": "raw", "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": {} } }, "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 } }, "/v1/meta/page": { "get": { "operationId": "Get Page Ads", "tags": [ "Meta Ads" ], "summary": "Page ads", "description": "Returns ads from required `page_id`. Optional fields filter by country, status, media, date, language, and platform; use `cursor` for pagination.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Page ID of the advertiser.", "example": "102988293558" }, "required": true, "description": "Page ID of the advertiser.", "name": "page_id", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "required": false, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "name": "country", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "active", "inactive" ], "description": "Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads." }, "required": false, "description": "Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads.", "name": "active_status", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "image", "video", "meme" ], "description": "Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives." }, "required": false, "description": "Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives.", "name": "media_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "total_impressions" ], "description": "Sort by total impressions." }, "required": false, "description": "Sort by total impressions.", "name": "sort_mode", "in": "query" }, { "schema": { "type": "string", "enum": [ "desc" ], "description": "Sort direction. Use with sort_mode." }, "required": false, "description": "Sort direction. Use with sort_mode.", "name": "sort_direction", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start Date in YYYY-MM-DD format.", "example": "2026-01-01" }, "required": false, "description": "Start Date in YYYY-MM-DD format.", "name": "date_min", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End Date in YYYY-MM-DD format.", "example": "2026-12-31" }, "required": false, "description": "End Date in YYYY-MM-DD format.", "name": "date_max", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor from the previous response." }, "required": false, "description": "Pagination cursor from the previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Number of ads to return per request. Accepted range: 1-50.", "example": 10 }, "required": false, "description": "Number of ads to return per request. Accepted range: 1-50.", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated ISO 639-1 language codes, for example en,hi.", "example": "en,hi" }, "required": false, "description": "Comma-separated ISO 639-1 language codes, for example en,hi.", "name": "content_languages", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.", "example": "FACEBOOK,INSTAGRAM" }, "required": false, "description": "Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.", "name": "publisher_platforms", "in": "query" }, { "schema": { "type": "boolean", "description": "Set to true to return the raw response payload.", "example": false }, "required": false, "description": "Set to true to return the raw response payload.", "name": "raw", "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": { "items": { "type": "array", "items": { "type": "object", "properties": { "ad_archive_id": { "type": "string", "minLength": 1 }, "page_id": { "type": "string", "nullable": true, "minLength": 1 } }, "required": [ "ad_archive_id" ], "additionalProperties": { "nullable": true } } }, "pageInfo": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true }, "hasNextPage": { "type": "boolean" } }, "required": [ "cursor", "hasNextPage" ] } }, "required": [ "items", "pageInfo" ] } }, "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 } }, "/v1/meta/search-pages": { "get": { "operationId": "Search Pages", "tags": [ "Meta Ads" ], "summary": "Advertiser search", "description": "Returns advertiser pages matching required `q`, including available page IDs and verification information. `country`, `ad_type`, and `raw` are optional.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Brand, company, or advertiser page search query.", "example": "flipkart" }, "required": true, "description": "Brand, company, or advertiser page search query.", "name": "q", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "example": "IN" }, "required": false, "description": "ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.", "name": "country", "in": "query" }, { "schema": { "type": "string", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "description": "Ad category. ALL includes all ad types; other values narrow results to the selected category." }, "required": false, "description": "Ad category. ALL includes all ad types; other values narrow results to the selected category.", "name": "ad_type", "in": "query" }, { "schema": { "type": "boolean", "description": "Set to true to return the raw response payload.", "example": false }, "required": false, "description": "Set to true to return the raw response payload.", "name": "raw", "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": {} } }, "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 } } }, "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." } }, "additionalProperties": { "nullable": true }, "description": "`code` is the stable value to branch on; `reason` says specifically what happened and new values may be added.", "example": { "reason": "blocked_by_site", "retryAfter": 60 } }, "ErrorReason": { "type": "string", "enum": [ "analysis_failed", "analysis_unavailable", "blocked_by_site", "capacity_exhausted", "capacity_limited", "cursor_invalid", "invalid_parameter", "media_processing_failed", "media_too_large", "media_unreadable", "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" ], "example": "blocked_by_site" }, "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" ] }, "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": "The model's own confidence that this window is NOT speech. High here with a low `avg_logprob` marks a caption invented over music — measured on a real music-only creative that came back as fluent Italian." }, "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": "The caps this request was measured against, so a caller can filter before spending a call." }, "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": "Managed proxy tier for fetching the file. Default: direct." }, "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": "Managed proxy tier for fetching the file. Default: direct." }, "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 traceable to the transcript or the supplied copy. There is no on-screen text extraction in this pipeline, so a claim shown only as burnt-in text is not here — `source` is what makes that legible rather than implied." }, "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 removed as likely hallucination before analysis: the transcriber called them not-speech and wrote them 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": "Pass this through from the transcript route. Segments the transcriber flagged as not-speech AND wrote with low confidence are dropped before 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" ] }, "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": "Upstream round-trips this request cost." }, "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 the walk stopped for a reason other than running out of providers. It is the negation of `exhausted`, not a lookahead: `false` is the strong claim (the directory produced nothing new), while `true` only says the walk was cut short by `count`, the page budget or a block — it does not prove another provider exists. `stop_reason` is the field to branch on." }, "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": "Where Clutch ranked this row in the directory. Position is the product here — the ordering is Clutch's editorial and sponsorship output — so it is preserved rather than re-derived from array order, which de-duplication would have shifted." }, "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": "May be the literal string **`\"Undisclosed\"`**. That is a firm declining to publish its rate — an answer, not a missing value — so it is passed through rather than collapsed to `null`, which would make it indistinguishable from a parse failure. Treat `null` as \"we did not read a rate\" and `\"Undisclosed\"` as \"the firm withheld one\"." }, "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": "**The percentage service mix — the field that is hard to get anywhere else.** Firmographics are a commodity; \"this agency is 45% web development, 45% web design, 10% branding\" is a positioning profile, and it comes off the listing with no profile fetch. Empty when Clutch renders no mix for the row." } }, "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": "Clutch's own `aggregateRating.reviewCount`. On the profile sampled during research this was 3 while 9 reviews were embedded — the relationship between the two counts is not established, so both are returned as-is. See `reviews_embedded`." }, "reviews_embedded": { "type": "integer", "minimum": 0, "example": 9, "description": "How many reviews we actually collected from this page — the length of `reviews`, not a figure quoted by Clutch. This is the number to trust about *this response*; `review_count_reported` is the number to quote about *Clutch*." }, "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": "Always 1, echoed from the page rather than assumed. There is no page 2 — see `stop_reason`." }, "search_uid": { "type": "string", "nullable": true, "description": "Indeed's own id for this search execution. Two identical requests get different ids and partly different jobs, so this is what identifies the specific set of rows you received." }, "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": "The job rows on the single available page — roughly 40-43 for a broad query. **Repeating an identical request returns a partly different set** (42 and 41 sharing 31, measured), so repeated polling of one query does slowly accumulate new postings." }, "has_more": { "type": "boolean", "enum": [ false ], "example": false, "description": "**Always false, permanently.** Indeed redirects `start=10` to a sign-in wall it labels `branding=page-two-signin`, and its own \"Next\" link goes to the same place, so page two requires an account for logged-out humans too. This is not a walk that stopped early and not a value that can ever become true — get coverage by varying `query`, `location`, `radius` and the filters." }, "stop_reason": { "type": "string", "enum": [ "page_two_requires_signin", "no_results_blob" ], "example": "page_two_requires_signin", "description": "Why the result set ends here. `page_two_requires_signin`: the normal case — Indeed serves one page to logged-out visitors and this is it. `no_results_blob`: the page rendered but carried no results section at all, which is what a query matching nothing looks like." }, "source_index_tier_counts": { "type": "array", "items": { "$ref": "#/components/schemas/IndeedTierCount" }, "description": "**Not a total, and not summable.** Indeed's own per-tier counts for its index (13/8/10/10 on the page measured, against ~42 rows returned and a page title claiming 6,000). The tiers overlap in ways nobody has established, so adding them up produces a number that means nothing. Published because it is Indeed's own view of the query's depth, under a name that cannot be mistaken for a result count." }, "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 (`createDate`)." }, "created_at_ms": { "type": "number", "nullable": true, "description": "The same instant as Indeed sent it, in epoch milliseconds, kept so nothing is lost if our reading of the unit is ever wrong." }, "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": "**Indeed's internal advertising bid for this placement** (`rankingScoresModel.bid`), in Indeed's own units. This is the ad auction itself, published on the page, and it is the single most valuable field on this surface. 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": "The title as sent upstream, after normalisation." }, "requested_location": { "type": "string", "nullable": true, "example": "San-Francisco--CA", "description": "The location as sent upstream, in Indeed's own encoding. Null on 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" ] }, "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": "How many reviews are in `reviews`. Expect roughly 3. Read `coverage` before comparing it to the employer's review count from `/glassdoor/overview`." }, "coverage": { "type": "string", "example": "page one only: Glassdoor answers 401 'Authenticating' for _P2 and beyond without an account", "description": "**Why `count` is small, stated in the payload rather than only in these docs.** Glassdoor serves one page of reviews to a logged-out client and answers 401 for every page after it, so this endpoint returns the reviews embedded in page one and there is no parameter that can ask for more." }, "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": "**How many reviews that rating is computed over.** This is the number to quote as the employer's review count — and the number `/glassdoor/reviews` cannot enumerate, because Glassdoor charges an account for page two." }, "best": { "type": "number", "nullable": true, "example": 5 }, "worst": { "type": "number", "nullable": true, "example": 1 } }, "required": [ "value", "count", "best", "worst" ], "description": "The employer-wide aggregate, read from the schema.org `EmployerAggregateRating` block Glassdoor publishes on the page. **This is the load-bearing field on this endpoint**: it is the one part of the employer tier that is measured to be present, and it is what answers \"what does this company actually score, over how many reviews\" without needing the reviews themselves. Null if Glassdoor stops publishing the block." }, "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": "The employer's facts, assembled from the employer objects in the page's React Server Component stream. Every field is nullable and commonly is: Glassdoor ships a different subset per employer, and this layer reports a missing branch as null rather than guessing. An employer page that exists but embeds no state returns a `profile` of nulls, not a null `data` — that is reserved for a missing overview page." }, "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": "The employer's own review count as carried in the page state. `rating.count` is the same figure from the schema.org block and is the one to prefer — it is the measured, always-present source." } }, "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." }, "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": "The property name from Booking's schema.org block. This is the anchor the rest of the payload hangs off, so it is the one non-nullable field here: a page that carries a `Hotel` block with no name means Booking changed what it publishes, and that is reported as an error rather than as a hotel with a dozen nulls." }, "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": "The guest score, and it is OUT OF TEN. Booking's `aggregateRating.ratingValue`, where 9.1 is an ordinary good hotel. Read `rating_scale_max` before comparing this with anything: Yelp and TripAdvisor in this same catalogue score out of five, and a client that treats 9.1 as a five-point rating is wrong by a factor of two and will never be told." }, "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": "How many reviews the property has — an exact figure from Booking's `aggregateRating`, not an abbreviation. This is the total the score is computed over, and it is not the number of reviews in `reviews`. See `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": "Ten featured guest reviews — a curated sample, not the review list. These are the reviews Booking renders into the property page itself, and they are neither the newest N nor a page of a larger sequence: a property with 1,019 reviews returns these same ten. Compare the array's length with `review_count` before doing anything statistical with them.\n\nAlways an array and never null. It can legitimately be empty — some properties carry no featured-review block — and `reviews_note` says so when that happens, so an empty sample is never confused with a failed parse." }, "review_sample_size": { "type": "number", "example": 10, "description": "How many reviews are in `reviews`, stated next to `review_count` on purpose. Ten reviews sitting under a review count of 1,019 reads as truncation or a bug until these two numbers are seen together. Counted from the array you actually received." }, "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": "What `reviews` is and is not, stated in the response body. Booking's `/reviewlist.html` fragment endpoint — where reviews came from for years — answers 404 in every form tried, and a property page fetches no reviews over any API: recording the page's own network traffic found no review call at all. What it does do is render ten featured reviews into the HTML, and a plain HTTP fetch receives all ten (measured against the browser DOM: 10 versus 10). So the sample is complete, and the full list is not reachable on this tier." } }, "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": "How many properties Booking holds for this destination, and it is trustworthy. Its own `nbResultsTotal`: San Francisco reports 353 and means it — offset 350 returns exactly 3 rows and offset 400 returns none. Paris reports 13,061 and was still returning rows at offset 1,000. Use it to size the walk instead of discovering the end by hitting it." }, "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 another page exists, computed as `offset + count < total_results` — from Booking's own total rather than from 'this page came back full'. A full page is not evidence of a next one, and the last page of a 353-property city is 3 rows, which the naive test would call the end one page early. Null when Booking stated no total." }, "exhausted": { "type": "boolean", "example": false, "description": "True when this page came back with no rows at all — you have walked past the end. Past the last page Booking answers HTTP 200 with the results key sometimes empty and sometimes missing altogether; both spellings mean the same thing and both arrive here as `exhausted: true` with `count: 0`. It is a normal end of list, not an error." }, "priced_for_stay": { "type": "boolean", "example": false, "description": "Which of Booking's two searches this was. True when you passed `checkin` and `checkout`, in which case rows carry availability and prices for that stay. False for a dateless search, where no row has a price at all — not because the data is missing, but because a price is a property of a stay. The two kinds are not comparable with each other." }, "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": "Why the rows do or do not carry prices, stated in the response body. A dateless search returning 25 properties and 25 null prices is the single most likely thing to be reported as a bug on this endpoint, so the answer travels with the data rather than living only in these docs." }, "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": "The property's star classification, OUT OF FIVE. This is not the guest score — see `review_score`, which is out of ten. Two different measurements on two different scales sit on this row, which is why each carries its own maximum." }, "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": "The guest score, OUT OF TEN. Booking's `reviewScore.score`. Not the star rating, and not on the star rating's scale." }, "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": "Null unless you searched with dates, and that is the whole story rather than missing data. Booking prices a stay, not a hotel: without `checkin` and `checkout` every row comes back with an empty room-offer list and no price block at all — measured. With dates, both are populated. See `priced_for_stay` and `pricing_note` on the response.\n\nOnly the price is taken out of Booking's room-offer array; the rest of an offer describes a specific room and rate whose shape is not measured, and publishing it unread would be publishing a guess." }, "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": "The listings on this page. An empty array is a real answer — a category with nothing in it — and is never how a refusal arrives: the worker judges every response on named listing markup before parsing it, so a refused page becomes a retryable 503 rather than an empty success." }, "count": { "type": "number", "example": 50, "description": "How many listings are in `results`. Counted from the array, not copied from upstream, and it excludes the advertising rows Avito interleaves into the same list." }, "dropped_non_listing_rows": { "type": "number", "example": 3, "description": "How many rows on this page were advertising rather than inventory. Named rather than folded into `count`, so a page that is all promotion and no listings is visible as exactly that." }, "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's listing id — the key to de-duplicate on. Rows repeat across pages of a live inventory (554 distinct ids in a 600-row walk)." }, "url": { "type": "string", "nullable": true, "example": "https://www.avito.ru/moskva/avtomobili/toyota_camry_2.5_at_2013_201_463_km_8082366222", "description": "The listing's own page, with Avito's `?context=` search token stripped — that token is bound to the search that produced the row and is not portable. Note that Avito refuses item pages far more often than listing pages (1 of 8 measured), which is why this API has no item endpoint." }, "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": "The seller's own text. Usually null, and that is Avito's rendering rather than a missing description: it hydrates the snippet component tree for a leading prefix of the rows only, and how long that prefix is varies per render (6, 20 and 50 of 50 all measured on the same category in one day). `descriptions_available` says how many arrived on this page." }, "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": "The viewport width this page was read at, echoed back — the other half of what makes these results reproducible. A result set means nothing without the query AND the viewport that produced it, which is why all four are stated on every response rather than left to a caller's own bookkeeping." }, "page": { "type": "number", "example": 1, "description": "The page number this response is, echoed back." }, "page_size": { "type": "number", "example": 20, "description": "20 businesses a page, which is Google's own figure — stated here so an offset is never computed from a guess. The last reachable page is normally short: page 10 of a measured walk carried 18." }, "max_pages": { "type": "number", "example": 10, "description": "How deep one query+viewport can be paged: 10. Measured by stepping the result offset — 0 through 180 returned rows, 200 returned an empty page. 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." }, "has_more": { "type": "boolean", "example": true, "description": "Whether a page after this one is worth asking for, computed as `page < 10 && count > 0`.\n\nDeliberately NOT 'did this page come back full'. Measured: page 10 returned 18 rows and page 11 returned zero — so a full page is not a promise of another and a short page is not a promise of the end. The page cap and the row count are the two facts that are actually known.\n\nIt says nothing about whether the AREA is exhausted: this ceiling is per query and viewport, and `span_metres` is the dial that moves it." }, "count": { "type": "number", "example": 20, "description": "How many businesses are in this response. Counted from what you received, never copied from a figure the worker printed.\n\nIt is not a count of NEW businesses. The pages overlap: 200 rows across 10 pages held 182 distinct places, so accumulate on a set keyed by `cid` rather than by adding this number up." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleMapsBusiness" }, "description": "This page's businesses, up to 20 of them, in Google's own order.\n\nEach one is a COMPLETE record, not a stub — the same record `/v1/google-maps/place` returns, carrying phone, website, hours, attributes, coordinates and photos. That is a property of the site rather than a choice made here: a search row and a place-detail response are the same structure, verified field by field across both surfaces. So there is normally no second call to make, and a 500-business harvest costs 26 requests rather than 526.\n\nEmpty array — never null — for a viewport with no matching businesses, and for any page past the end of the walk." }, "interpreted_query": { "type": "string", "nullable": true, "example": "coffee in San Francisco", "description": "What Google understood the search to be, in its own words — which is not always what was sent. Worth reading when a result set looks wrong: it is the difference between 'this area has no coffee shops' and 'Google searched for something else'. Null when the response states none." }, "viewport": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "type": "array", "items": { "nullable": true } }, { "nullable": true } ], "description": "The map bounds Google actually searched, republished exactly as it arrives. It is Google's resolution of your `latitude`, `longitude` and `span_metres`, so it is the place to look when planning tiles that do not overlap or leave gaps.\n\nPositional and unnamed, like everything in this payload, and not renamed here for the same reason `address_components` is not: no capture has pinned a stable field list, and an invented index map would be a schema this layer made up." }, "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's own identifier for the place, and the exact value `/v1/google-maps/place` takes as its `cid`. That is what makes the two endpoints compose: walk a viewport here, then re-read any business later without ever constructing a URL.\n\nIt is also the key to deduplicate on, and on this site that is not optional: ten pages of one query+viewport carry 200 rows holding 182 distinct businesses.\n\nPresent on 20 of 20 businesses measured. Null only if Google filed a row without one — a search page where no row carries a cid is refused outright rather than published as 20 unaddressable results." }, "name": { "type": "string", "nullable": true, "example": "The Coffee Movement", "description": "The business name as Google files it. Present on 20 of 20 measured." }, "place_id": { "type": "string", "nullable": true, "example": "ChIJ_2f19_uHhYARRpn5d_Fk1SU", "description": "Google's `ChIJ…` place id — the identifier the official Places API speaks. Published because it is the one that joins this record to other datasets and to anything already built against Google's own API. It is NOT what `/v1/google-maps/place` takes: that endpoint keys on `cid`. Present on 20 of 20 measured." }, "feature_id": { "type": "string", "nullable": true, "example": "/g/11h547vvy9", "description": "Google's third identifier for the same place, a Knowledge Graph feature id. Published for the same reason as `place_id` — it joins outward — and consulted by nothing here." }, "address": { "type": "string", "nullable": true, "example": "1030 Washington St, San Francisco, CA 94108", "description": "The full one-line address, as Google renders it. Present on 20 of 20 measured. `address_lines` is the same address split the way Google splits it, and `address_components` is its structured form." }, "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": "Google's structured address, republished exactly as it arrives. It is a POSITIONAL list rather than a keyed object — Google states no names for its slots anywhere in the document — so renaming it here would mean publishing an index map this layer invented and calling it a schema. The named fields above (`address`, `city`, `neighborhood`, `country_code`) are the ones to rely on; this is here for callers who need more than they carry and are willing to read positions." }, "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": "Where the business is. Present on 20 of 20 measured, which is what makes a result set mappable and what lets you measure a walk's coverage against the `span_metres` you asked for." }, "longitude": { "type": "number", "nullable": true, "example": -122.4116 }, "timezone": { "type": "string", "nullable": true, "example": "America/Los_Angeles", "description": "The IANA timezone the business sits in. Present on 20 of 20 measured, and the field that makes `hours` interpretable: the spans in `hours.days[].hours` are local-time labels with no offset on them, so this is what turns '9 AM–2 PM' into a moment." }, "categories": { "type": "array", "items": { "type": "string" }, "example": [ "Coffee shop", "Cafe" ], "description": "What Google says the business is, in its own vocabulary, most specific first. Present on 20 of 20 measured. Empty array when the record carries none." }, "rating": { "type": "number", "nullable": true, "example": 4.8, "description": "The star rating out of 5. Present on 20 of 20 measured.\n\nThere is deliberately no review count beside it, and that is not an oversight — please do not report it as one. A rating without a count is a weaker number than it looks (5.0 from three reviews and 4.6 from 1,378 are not comparable), so it is worth saying exactly why one is not published here.\n\nAn earlier version of this endpoint did publish a `review_count`, taken from an integer in the record that looks like one and \"verified\" by finding the same value on a second Google surface. That verification was worthless: agreement between two surfaces proves they carry the same field, not what the field means — both were reporting the same wrong number. Checked against the count Maps itself displays, which is independent ground truth:\n\n| business | Maps displays | the field said |\n| --- | --- | --- |\n| Ritual Coffee Roasters | 1,723 | 1,324 |\n| Caffe Trieste | 1,782 | 1,969 |\n| Tartine Bakery | 5,950 | 10,337 |\n\nLow on one and high on two, so not even a consistent proxy to scale. It was withdrawn rather than renamed, because an unexplained integer published under any name invites somebody to divide by it.\n\nThe real count is not reachable on this path at all. It lives in a slot that is null without a session cookie, and these requests deliberately carry none — no cookie jar, no credential, no session. The whole cold record was searched for the true value and no integer anywhere in it matches. Saying nothing is the honest answer.\n\nReview TEXT is not in this payload either — Maps loads that from a third endpoint, and that endpoint is `/v1/google-maps/reviews`. Pass this record's `cid` to it. Walking its `next_cursor` to the end returns the complete corpus, so the count Maps displays is reproducible by counting what you receive — which is a stronger answer than the integer withdrawn above, and the reason withdrawing it cost nothing." }, "phone": { "type": "string", "nullable": true, "example": "(415) 780-1902", "description": "The business phone number as Google displays it, in the local convention. Present on 15 of 20 measured — the thinnest of the contact fields, and the reason to read `website` beside it rather than instead of it. `phone_e164` is the same number in dialable form." }, "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": "The business website. Present on 19 of 20 measured, which makes it the most reliable contact field on this record — more so than `phone`." }, "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": "What the business offers, as a map of Google's own group names to their feature lists — accessibility, amenities, payment options, service options and the rest. Present on 19 of 20 businesses measured, and one of the two things this record carries that a phone directory does not.\n\nThe keys are Google's labels and they vary by business and by category, so the map itself is republished as it arrives rather than flattened into a fixed set of booleans. A schema of named flags would either invent groups a restaurant has and a dentist does not, or silently drop the ones this API happened not to enumerate. Read a group if it is there.\n\nNull when Google lists no attributes for the business." }, "photos": { "type": "array", "items": { "type": "string" }, "example": [ "https://lh3.googleusercontent.com/p/AF1QipN-example=w408-h306-k-no" ], "description": "Photo URLs for the business, up to ten, in Google's own order — the first is the one Maps shows as the cover. Present on 20 of 20 measured.\n\nFound by shape rather than by a fixed position, because the photo block is the one part of the record that nests differently between a search row and a place-detail response. Empty array when the record carries none." }, "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": "The current day's opening hours — NOT a week of them. Measured across 8 businesses: this list held exactly one entry every time, always the current day. The record was also searched for any slot carrying four or more weekday names, and there is none: the full week is not in this payload at all.\n\nSo do not read a one-element list as 'this cafe opens on Saturdays only'. It is one day out of seven, and the other six are not being withheld — they are not there." }, "status": { "type": "string", "nullable": true, "example": "Closed · Opens 8 AM Mon", "description": "Google's own sentence about the business right now, and the most useful thing in this object. It answers the question a caller actually has — is this place open, and if not, when does it open — and it encodes the NEXT transition, which the single day in `days` cannot. Read this first and treat `days` as the detail behind it." } }, "required": [ "days", "status" ], "description": "Opening hours — and this is NOT a weekly schedule, however much the shape suggests one.\n\n`status` is the useful half: Google's own sentence, e.g. `\"Closed · Opens 8 AM Mon\"`, which says whether the business is open right now and when that next changes.\n\n`days` carries the current day only. Measured across 8 businesses: exactly one entry every time, always today. The record was also searched for any slot carrying four or more weekday names — there is none, so the full week is not in this payload, whatever flag might fetch it. The field is called `hours` rather than `opening_hours` for exactly that reason.\n\nNull when Google states no hours at all for the business." }, "GoogleMapsHoursDay": { "type": "object", "properties": { "day": { "type": "string", "nullable": true, "example": "Saturday", "description": "The weekday this entry is for, in Google's own words and in the language the worker requests (`hl=en`). Normally today, and the only day in the list — see the note on `days`." }, "hours": { "type": "array", "items": { "type": "string" }, "example": [ "9 AM–2 PM" ], "description": "The opening spans for that day, exactly as Google renders them. More than one entry when the business shuts for lunch. Rebuilt from nothing — the numeric pairs Google ships beside these are local-time integers with no timezone, while the label already carries `Closed` and `Open 24 hours`, which no pair of integers can say.\n\nEmpty array on a day the business is closed, where Google states the closure in `status` rather than as a span." }, "date": { "type": "array", "nullable": true, "items": { "type": "number" }, "example": [ 2026, 8, 15 ], "description": "The calendar date this entry is for, as Google's own `[year, month, day]` triple. Republished in that form rather than formatted into a date string, because it is what pins the entry to a specific day rather than to a recurring weekday — and it is how you can tell a stale cached response from a fresh one." } }, "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": "This page of reviews, newest first, at most 20 of them.\n\nA short page is not the end of the corpus — read `has_more`. Measured: the last page of a 338-review place held 18 rows and no cursor, and every walk ended by Google declining to issue a cursor rather than by returning short.\n\nRows with `text: null` are star-only ratings and are real reviews — see `text`. Empty array — never null — for a place with no reviews." }, "count": { "type": "number", "example": 20, "description": "How many reviews are in this response, counted from the array you received rather than copied from a figure the worker printed.\n\nIt is not a paging signal. Read `has_more`. And it is not the place's total review count either — that is what walking every `next_cursor` and counting gives you, which is the one number on this platform that reproduces what Maps displays." }, "next_cursor": { "type": "string", "nullable": true, "example": "0x808587fb77f5f64d:0x25d564f177f99946|CAESY0NBRVFBUm9VUTJoa1p...", "description": "Send this back as `cursor` to get the next page. It is the only authority on whether the corpus continues. Null means Google offered no further position, which is the end of the walk.\n\nIt is bound to the `cid` it was issued for — published as `|` — and it will be refused against any other place. That binding is the guard on this endpoint's one silent-wrong-answer failure: Google itself does not check the pair, and answers a mismatched one with a full page of the OTHER place's reviews from partway down its list.\n\nOpaque otherwise. Nothing here parses the token half, and it is not an offset — do not construct one." }, "has_more": { "type": "boolean", "example": true, "description": "Whether to page again — derived from `next_cursor`, and never from how full this page came back.\n\nThis is the field a walk terminates on and the easiest one to reimplement wrongly. Measured: the last page of a 338-review place carried 18 rows AND no cursor. A caller stopping on `count < count_requested` would stop early on any page Google chose to return short, and the whole selling point of this endpoint is that walking to the true end returns the complete corpus." }, "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's own id for this review, and the key to deduplicate on. It is what a full walk was verified against: 492 pages across four places produced zero duplicate review ids. A row Google filed without one is not published — a review that cannot be told apart from another is worse than a missing row." }, "place_ref": { "type": "string", "nullable": true, "example": "0x0:0x25d564f177f99946", "description": "The place Google says this review belongs to, echoed back in its own abbreviated form — `0x0:` followed by the low half of the `cid`. It is published because it is the evidence behind the cursor-binding rule: a cursor replayed against the wrong place returns rows whose `place_ref` is the OTHER place's, and those rows are dropped rather than published. You should never see one that disagrees with `requested_cid`." }, "rating": { "type": "number", "nullable": true, "example": 5, "description": "The star rating this reviewer gave, 1 to 5. Present on every row measured, including the star-only rows that carry no `text` — which is exactly what makes those rows worth publishing." }, "text": { "type": "string", "nullable": true, "example": "Best espresso in the neighbourhood. Tiny room, huge care.", "description": "The review body — and `null` here is a STAR-ONLY RATING, not a broken row. This is the single most misread field on the endpoint.\n\nMeasured: 25 of 100 consecutive rows had `text: null` with a rating, an author and a timestamp all present, and across the wider corpus these run to roughly 25-40% of reviews. Maps counts them in the review total it displays, and this API's walk matched that displayed total exactly on three places of four — which it could not have done if they were dropped.\n\nSo a caller filtering them out will disagree with the number on the page, and will also skew any rating average they compute: star-only rows are not a random sample of opinions. Filter them if you are doing text analysis; do not filter them and then count." }, "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": "When the review was posted, in MICROSECONDS since the epoch. Google's own integer, republished as it arrives rather than reformatted — divide by 1,000 for milliseconds, or by 1,000,000 for seconds. The unit is in the field name because a microsecond timestamp read as milliseconds lands in the year 57,000 and looks like a parsing success.\n\nReviews arrive newest first, so this decreases down the page and across a walk." }, "updated_at_us": { "type": "number", "nullable": true, "example": 1747224000000000, "description": "When the review was last edited, same units. Equal to `created_at_us` on a review that has never been edited, which is most of them. The pair is published rather than reconciled because an edited review is a real thing to be able to detect." }, "relative_time": { "type": "string", "nullable": true, "example": "3 months ago", "description": "Google's own rendering of the review's age — the string Maps shows. It is computed at the moment the page was read, so it ages in your stored copy while the timestamps do not, and it disagrees with them by design on an edited review. Read it for display; read `created_at_us` for anything else." }, "author": { "$ref": "#/components/schemas/GoogleMapsReviewAuthor" }, "photos": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/GoogleMapsReviewPhoto" }, "description": "Photos the reviewer attached, or null where they attached none — which is most reviews. A real per-review list rather than a fixed container: sampled lengths ran from 2 to 35." }, "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": "Who wrote the review, and their own contribution statistics.\n\nNote what is NOT here: there is no like or 'helpful' count on a review, and its absence is a measurement rather than an oversight. The obvious candidate slot — the one unexplained small integer that varies per row — was ruled out by its own behaviour. If it were helpful votes, Google's most-relevant ranking would surface the high values; sampled 60 rows per sort on two places it goes the other way (Tartine: 17.6 mean under most-relevant against 33.9 under newest; Caffe Trieste: 26.4 against 41.9), and it sits inside this author block, which fits an author statistic rather than a per-review one. No like count was found anywhere in the payload, and the payload carries no label for one. Publishing nothing beats publishing a plausible wrong integer, because an integer with a name on it invites arithmetic — the same mistake the withdrawn `review_count` already cost this API once." }, "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": "Google's own rendering of the reply's age, in the language the worker requests. It is a display string computed when the page was read, so it ages while the timestamps do not — read the timestamps." }, "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": "The business owner's public reply to the review, present on 8 of 10 sampled rows on a place that answers its reviews. Null where there is no reply — which is the common case across the corpus as a whole, not a sign of a broken row." }, "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 bio. X moved this from `legacy.description` into `profile_bio.description` and still serves both shapes; both are read, so this is not null for half the accounts." }, "location": { "type": "string", "nullable": true, "example": "Pale Blue Dot", "description": "Free text the account typed, not a resolved place. X does no geocoding here and neither does this API — `Pale Blue Dot` is a real measured value. Do not read it as an 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": "When the account was created, in X's own format — the Twitter date string, e.g. `Wed Dec 19 20:20:32 +0000 2007` on the measured account. Republished verbatim rather than reformatted to ISO 8601: it is unambiguous, it parses with a format string in every language, and rewriting a timestamp is a good way to introduce a timezone bug into data that did not have one." }, "followers_count": { "type": "number", "nullable": true, "example": 92304095, "description": "Followers. Measured at capture on the sampled account: ~92.3M (92,304,095 at the moment it was read — this is a live counter and a later read will differ, which is drift rather than a fault). Read it against `following_count`: 119 there against 92 million here is the shape of an institutional account rather than a person's." }, "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": "How many posts the account has made — ~74.3K on the sampled account at capture. This is the total X states, not how many `/v1/x/tweets` can reach: a timeline walk was measured to 122 tweets over 8 pages and was still cursoring, so the reachable depth is a floor rather than a ceiling and is not this number." }, "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": "How many posts by this account carry media, as X counts it. The media themselves are not reachable: the `UserMedia` operation answers 404 to a guest token. Media attached to a tweet still arrives inside that tweet's `entities`." }, "favourites_count": { "type": "number", "nullable": true, "example": 15299, "description": "How many posts this account has liked. X's own spelling, with the British `u`, kept rather than corrected so it lines up with every other tool reading this field." }, "verified": { "type": "boolean", "nullable": true, "example": false, "description": "Legacy verification — the pre-2023 blue check, and it is `false` on accounts you would expect it on. Measured on the sampled account: `verified: false` beside `is_blue_verified: true`. Reading this field alone to answer 'is this account verified' returns the wrong answer for most verified accounts today. Read `is_blue_verified` beside it." }, "is_blue_verified": { "type": "boolean", "nullable": true, "example": true, "description": "The current verification mark, and the one to read. `true` on the sampled account, where `verified` is `false`. The two are published side by side rather than merged into one boolean, because they answer different questions — a legacy check and a current subscription — and collapsing them would destroy the distinction." }, "protected": { "type": "boolean", "nullable": true, "example": false, "description": "Whether the account's posts are restricted to approved followers. A protected account's timeline is not readable here — this API holds no account and follows nobody, so `/v1/x/tweets` will return an empty page for one." }, "profile_image_url": { "type": "string", "nullable": true, "example": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg", "description": "The avatar, at whatever size X states — the URL usually carries a `_normal` size marker. Not rewritten to a larger variant here, because that is a guess about a CDN path rather than a measurement." }, "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": "X's own professional/business-account object, republished whole. It carries a category list and a professional type, and its shape varies by account type — renaming fields that have not been measured populated would publish a permanently-null column and call it a schema. Null on accounts that are not professional accounts." }, "requested_handle": { "type": "string", "nullable": true, "example": "nasa", "description": "The handle this request asked for, after cleaning — the value sent upstream, with any `@` and any pasted URL already reduced away. It is echoed so a join against your own input never rests on two layers agreeing about normalisation, and it commonly differs from `handle` in casing: `nasa` in, `NASA` out." } }, "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": "This page of the timeline. Its length is not `requested_count` and a short page is not the end — measured pages of a requested 20 came back 12, 17, 18, 14, 16, 16, 16 and 13, all of them full of new tweets. Every entry's `id` is the exact value `/v1/x/tweet` takes.\n\nAn empty array is a real answer: an account with no posts, a protected account (which this API cannot read), or the true end of the stream. Distinguish them by `has_more`." }, "count": { "type": "number", "example": 12, "description": "How many tweets are in `tweets`, counted from the array actually returned rather than copied from anything upstream. It is what X delivered, not what was asked for — compare with `requested_count`. It is not a paging signal: read `has_more`." }, "next_cursor": { "type": "string", "nullable": true, "example": "DAABCgABGxxxxxxxxxxxLAAA", "description": "Send this back as `cursor` to get the next page. It is the only authority on whether the timeline continues. Null means X offered no further position, which is the one reliable end-of-timeline signal here.\n\nMeasured: 8 consecutive pages, none of them full, and page 8 still returned a cursor. The cursor also carries the account, which is why a page after the first costs one upstream call rather than two." }, "has_more": { "type": "boolean", "example": true, "description": "Whether to page again — derived from `next_cursor`, never from how full this page came back.\n\nThis is the single most important field on the response and the easiest one to reimplement wrongly. A caller computing `count === requested_count` to decide whether to continue stops on page 1 of every timeline on X, because X delivered 12 of a requested 20 on the first page of the measured walk and then 110 more tweets over 7 further pages.\n\nIt is `false` only when X offered no cursor, or when this page carried no tweets at all — the second clause being the one stopping condition that is not a short page, since X has been observed to keep offering a cursor rather than to state an end." }, "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": "The account id this endpoint resolved the handle to, and the extra upstream call the first page pays for. It is published so a caller can see what was actually read: a handle is renameable and this is not, so a long walk is best keyed on this value." }, "requested_count": { "type": "number", "example": 20, "description": "What was asked for, echoed beside `count`, which is what arrived. The pair is published rather than reconciled precisely because they disagree on nearly every page, and a caller comparing them can see that for themselves instead of concluding the request failed." }, "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": "Page with `next_cursor`, and judge the end of the timeline by it alone. The count you asked for is a HINT: measured over 8 pages at count=20, X delivered 12, 17, 18, 14, 16, 16, 16 and 13 — every one of them full of tweets nobody had seen. A caller stopping on a short page stops on page 1. Each tweet's `id` is the exact value /v1/x/tweet takes.", "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": "The post's body — but read `is_retweet` and `is_long_post` before you count characters on it.\n\nOn a retweet this is X's own truncated `\"RT @handle: …\"` form, not the original. The original is published whole under `retweeted_tweet.text`. Both are here deliberately: which one you want depends on what you are counting — what this account posted, or what it amplified — and substituting one for the other would silently answer the wrong question.\n\nOn a long post this is the untruncated body, lifted from X's `note_tweet`, and `is_long_post` is `true`. Without that read, a 4,000-character post publishes as its first 280 characters and reads like a complete tweet." }, "is_long_post": { "type": "boolean", "example": false, "description": "Whether `text` came from X's `note_tweet` — the untruncated body of a long post — rather than from the ordinary 280-character field.\n\nThis exists because the failure it prevents is invisible. A long post whose `note_tweet` is not read publishes as its first 280 characters, with no ellipsis and no marker: a truncated post that reads like a complete one. When this is `true`, `text` is the whole thing." }, "created_at": { "type": "string", "nullable": true, "example": "Wed Oct 15 18:32:11 +0000 2025", "description": "When the tweet was posted, in X's own date format. Republished verbatim rather than reformatted — see the same note on the account record's `created_at`." }, "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": "The id of the thread this post belongs to. Equal to `id` on a post that starts one. Note what it does NOT let you do here: the replies under a thread need X's `TweetDetail` operation, which answers 404 to a guest token and is not available on this API." }, "reply_to_tweet_id": { "type": "string", "nullable": true, "example": null, "description": "The id of the post this one replies to, or null if it replies to nothing. It is a tweet id like any other, so `/v1/x/tweet` fetches the parent — which is how you walk a thread upward here, one hop at a time, given that walking it downward is not available." }, "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": "How many replies X counts on this post — not the replies themselves, which are not reachable without a logged-in account." }, "quote_count": { "type": "number", "nullable": true, "example": 17 }, "bookmark_count": { "type": "number", "nullable": true, "example": 231, "description": "How many people bookmarked the post. A private-intent signal X publishes on the payload but renders on nobody else's timeline." }, "view_count": { "type": "number", "nullable": true, "example": 54752, "description": "Impressions, and the widest-reaching number on the record — typically one to two orders of magnitude above the like count, which is what makes it the honest denominator for an engagement rate.\n\nX sends this as a STRING (`\"54752\"`), and it is coerced to a number here. It lives outside the tweet's `legacy` object, under `views.count`, and is typed as text there. The coercion is deliberate: this is a count, callers sort and sum and divide by it, and a string sorts lexicographically — `\"9\"` orders above `\"54752\"`, which is a bug that produces a plausible-looking leaderboard. The conversion is done once, in this API's normalizer, rather than in every caller.\n\nNull when X states no view count, which is normal on older posts and on some reply-scoped ones. Null means 'X published none' rather than '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's own entities structure, republished whole and under its own key names — `hashtags`, `urls`, `user_mentions`, `symbols` and `media`, each an array of objects carrying the indices into `text` where they appear.\n\nIt is the one object here that keeps X's vocabulary rather than being renamed into this API's. The reason is that anything already written against a Twitter payload reads these keys as they stand, and the shape varies by what a post actually contains — flattening it would mean inventing a fixed schema for a variable structure and losing the index offsets that make it usable.\n\nThis is also where a post's media lives. The account-level `UserMedia` operation is not reachable, but media attached to a tweet arrives here with it." }, "author": { "$ref": "#/components/schemas/XTweetAuthor" }, "is_retweet": { "type": "boolean", "example": false, "description": "Whether this row is a retweet — and therefore whether `text` is X's truncated `\"RT @handle: …\"` form rather than a post this account wrote. Check it before you count characters, run sentiment, or attribute authorship." }, "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": "This is the tweet itself, not its replies — those need a logged-in account, which this API does not use. On a retweet, `text` is X's own truncated 'RT @handle: ...' form and the original is published whole under `retweeted_tweet`.", "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." } } }, "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\nIt 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." }, "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\nOrdering 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\nIt 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 `/v2/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\nA 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\nIt 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\nIt 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\nOn `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 `/v2/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 `/v2/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" ] }, "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\nOn `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\nIt 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 `/v2/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." }, "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\nThis 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\nNever 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\nA 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\nThese 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." }, "ApifyStoreIntel": { "type": "object", "nullable": true, "properties": { "status": { "type": "object", "nullable": true, "properties": { "last_run_at": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "actors_tracked": { "type": "number" }, "builders_tracked": { "type": "number" }, "builders_active": { "type": "number" }, "builders_retrying": { "type": "number" }, "builders_failed_last_run": { "type": "number" }, "coverage_percent": { "type": "number", "nullable": true }, "new_last_run": { "type": "number" }, "days_of_history": { "type": "number" }, "latest_stage": { "type": "string", "nullable": true }, "latest_reason": { "type": "string", "nullable": true }, "latest_trigger": { "type": "string", "nullable": true }, "proxy_tier": { "type": "string", "nullable": true } }, "required": [ "last_run_at", "status", "actors_tracked", "builders_tracked", "builders_active", "builders_retrying", "builders_failed_last_run", "coverage_percent", "new_last_run", "days_of_history", "latest_stage", "latest_reason", "latest_trigger", "proxy_tier" ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "started_at": { "type": "string" }, "finished_at": { "type": "string", "nullable": true }, "duration_s": { "type": "number", "nullable": true }, "builders_swept": { "type": "number" }, "builders_discovered": { "type": "number" }, "actors_seen": { "type": "number" }, "actors_new": { "type": "number" }, "upstream_calls": { "type": "number" }, "error_count": { "type": "number" }, "context": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } } }, "required": [ "id", "status", "started_at", "finished_at", "duration_s", "builders_swept", "builders_discovered", "actors_seen", "actors_new", "upstream_calls", "error_count", "context" ] } }, "newActors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "url": { "type": "string" }, "username": { "type": "string" }, "target": { "type": "string", "nullable": true }, "published_at": { "type": "string", "nullable": true }, "first_seen_at": { "type": "string" }, "age_days": { "type": "number", "nullable": true }, "daily_runs": { "type": "number", "description": "Runs per day, derived from the change in Apify's lifetime run counter between nightly sweeps." }, "window_runs": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "users_30d": { "type": "number", "nullable": true }, "price_usd": { "type": "string", "nullable": true }, "competitors": { "type": "number" } }, "required": [ "id", "title", "url", "username", "target", "published_at", "first_seen_at", "age_days", "daily_runs", "window_runs", "users_30d", "price_usd", "competitors" ] } }, "risers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "url": { "type": "string" }, "username": { "type": "string" }, "target": { "type": "string", "nullable": true }, "daily_runs": { "type": "number", "description": "Runs per day, derived from the change in Apify's lifetime run counter between nightly sweeps." }, "prior_daily_runs": { "type": "number" }, "growth": { "type": "number" }, "window_runs": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "users_30d": { "type": "number", "nullable": true }, "age_days": { "type": "number", "nullable": true }, "competitors": { "type": "number" } }, "required": [ "id", "title", "url", "username", "target", "daily_runs", "prior_daily_runs", "growth", "window_runs", "users_30d", "age_days", "competitors" ] } }, "gaps": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "competitors": { "type": "number" }, "niche_daily_runs": { "type": "number" }, "runs_per_competitor": { "type": "number" }, "leader_title": { "type": "string", "nullable": true }, "leader_url": { "type": "string", "nullable": true }, "leader_daily_runs": { "type": "number" } }, "required": [ "target", "competitors", "niche_daily_runs", "runs_per_competitor", "leader_title", "leader_url", "leader_daily_runs" ] } }, "activePublishers": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "launch_count": { "type": "number" }, "latest_launch_at": { "type": "string" } }, "required": [ "username", "launch_count", "latest_launch_at" ] } } }, "required": [ "status", "runs", "newActors", "risers", "gaps", "activePublishers" ] }, "ApifyStoreSweepTrigger": { "type": "object", "nullable": true, "properties": { "started": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "started", "local_run_in_progress", "lock_held" ] }, "trigger": { "type": "string", "enum": [ "manual" ] } }, "required": [ "started", "reason", "trigger" ] }, "ApifyStoreSweepCancel": { "type": "object", "nullable": true, "properties": { "requested": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "cancellation_requested", "no_manual_sweep_running" ] } }, "required": [ "requested", "reason" ] }, "ApifyDeveloperWatch": { "type": "object", "nullable": true, "properties": { "username": { "type": "string" }, "added_at": { "type": "string" } }, "required": [ "username", "added_at" ] }, "ApifyWatchedDeveloperLaunches": { "allOf": [ { "$ref": "#/components/schemas/ApifyDeveloperWatch" }, { "type": "object", "properties": { "launch_count": { "type": "number" }, "actors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "url": { "type": "string" }, "published_at": { "type": "string" } }, "required": [ "id", "name", "title", "url", "published_at" ] } } }, "required": [ "launch_count", "actors" ] } ] } }, "parameters": {} } }