{ "openapi": "3.0.1", "info": { "title": "Market Insights API", "description": "API for connectivity providers to retrieve market insights data including demand, booking window, booker insights, pace reports, and sales statistics for properties.", "contact": { "name": "Connectivity Support", "url": "https://connect.booking.com", "email": "connectivity@booking.com" }, "license": { "name": "Copyright Booking.com. All rights reserved.", "url": "https://www.booking.com" }, "version": "1.0.0" }, "externalDocs": { "description": "Find out more about Connectivity APIs", "url": "https://connect.booking.com/" }, "servers": [ { "url": "https://supply-xml.booking.com/market-insights-api", "description": "Production Environment", "variables": {} } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Market Insights", "description": "Endpoints for retrieving market insights and analytics data for properties." } ], "paths": { "/properties/{propertyId}/area_demand_data": { "get": { "tags": [ "Market Insights" ], "summary": "Get area demand data for a property", "operationId": "areaDemandData", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Demand data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemandDataResponse" }, "example": { "data": { "report_area": "Paris", "report_date": "2024-01-15", "demand_data": [ { "category_name": "book_window", "title": "Book window", "category_summary": "Most searches were looking for 0-1 day in the future", "stats": [ { "title": "0-1 day", "key": "bookwindow_0_1", "formatted_score": "23.32%" } ] }, { "category_name": "traveller_type", "title": "Traveller type", "category_summary": "Most searches were from couples", "stats": [ { "title": "Couple", "key": "traveller_couple", "formatted_score": "72.11%" } ] } ] }, "warnings": [], "errors": [] } } } }, "401": { "description": "Unauthorized. The bearer token is missing, invalid or expired. For the possible error codes and fixes, see [Troubleshooting Market Insights API error responses](/connectivity/docs/market-insights-api/troubleshooting-market-insights-api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseUnauthorized" }, "examples": { "missingOrInvalidToken": { "summary": "Missing, invalid or expired bearer token", "value": { "meta": { "ruid": "" }, "warnings": [], "errors": [ { "message": "", "code": "", "details": null } ] } } } } } }, "403": { "description": "Property not eligible or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "propertyNotAccessible": { "summary": "Property not accessible with these credentials", "value": { "warnings": [], "errors": [ { "message": "Unable to process", "code": 450, "description": "Forbidden" } ], "meta": { "ruid": "" } } }, "propertyIdNotValid": { "summary": "Property ID is not valid", "value": { "warnings": [], "errors": [ { "message": "Data not found", "code": 635, "description": "Not found" } ], "meta": { "ruid": "" } } } } } } }, "500": { "description": "Internal server error" } } } }, "/properties/{propertyId}/book_window_data": { "get": { "tags": [ "Market Insights" ], "summary": "Get book window information data for a property", "operationId": "bookWindowData", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "date_range", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } }, { "name": "compare_with", "in": "query", "schema": { "type": "string", "enum": [ "NONE", "LAST_YEAR", "COMPETITIVE_SET", "PEER_GROUP", "MARKET" ] } } ], "responses": { "200": { "description": "Book window data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketInsightResponse" }, "example": { "data": { "book_window": [ { "value": "0-1 days", "percent": 5.17, "percent_comparison_set": 4.82, "report": { "adr": { "value": 110.67, "comparison_set": 105.3, "percent_change": 5.1 }, "room_nights": null, "revenue": null } }, { "value": "8-14 days", "percent": 11.11, "percent_comparison_set": 10.9, "report": { "adr": { "value": 133.57, "comparison_set": 128.6, "percent_change": 3.9 }, "room_nights": null, "revenue": null } } ], "total_booked_rooms": 2856 }, "warnings": [], "errors": [], "meta": null } } } }, "400": { "description": "Invalid parameter value. The `errors` entry names the parameter and lists its allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "invalidDateRange": { "summary": "Invalid date_range value", "value": { "warnings": [], "errors": [ { "message": "Invalid value", "code": 320, "details": { "fields": [ "query param date_range" ], "allowed_values": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } } ], "meta": { "ruid": "" } } } } } } }, "401": { "description": "Unauthorized. The bearer token is missing, invalid or expired. For the possible error codes and fixes, see [Troubleshooting Market Insights API error responses](/connectivity/docs/market-insights-api/troubleshooting-market-insights-api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseUnauthorized" }, "examples": { "missingOrInvalidToken": { "summary": "Missing, invalid or expired bearer token", "value": { "meta": { "ruid": "" }, "warnings": [], "errors": [ { "message": "", "code": "", "details": null } ] } } } } } }, "403": { "description": "Provider not certified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "propertyNotAccessible": { "summary": "Property not accessible with these credentials", "value": { "warnings": [], "errors": [ { "message": "Unable to process", "code": 450, "description": "Forbidden" } ], "meta": { "ruid": "" } } }, "propertyIdNotValid": { "summary": "Property ID is not valid", "value": { "warnings": [], "errors": [ { "message": "Data not found", "code": 635, "description": "Not found" } ], "meta": { "ruid": "" } } } } } } }, "500": { "description": "Internal server error" } } } }, "/properties/{propertyId}/booker_insights_data": { "get": { "tags": [ "Market Insights" ], "summary": "Get booker insights data for a property", "operationId": "bookerInsightsData", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "date_range", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } }, { "name": "compare_with", "in": "query", "schema": { "type": "string", "enum": [ "NONE", "LAST_YEAR", "COMPETITIVE_SET", "PEER_GROUP", "MARKET" ] } } ], "responses": { "200": { "description": "Booker insights retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketInsightResponse" }, "example": { "data": { "country": [ { "value": "de", "percent": 67.19, "percent_comparison_set": 68.73 }, { "value": "nl", "percent": 19.9, "percent_comparison_set": 17.94 }, { "value": "other", "percent": 1.14, "percent_comparison_set": 1.77 } ], "total_booked_rooms": 2856 }, "warnings": [], "errors": [], "meta": null } } } }, "400": { "description": "Invalid parameter value. The `errors` entry names the parameter and lists its allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "invalidDateRange": { "summary": "Invalid date_range value", "value": { "warnings": [], "errors": [ { "message": "Invalid value", "code": 320, "details": { "fields": [ "query param date_range" ], "allowed_values": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } } ], "meta": { "ruid": "" } } } } } } }, "401": { "description": "Unauthorized. The bearer token is missing, invalid or expired. For the possible error codes and fixes, see [Troubleshooting Market Insights API error responses](/connectivity/docs/market-insights-api/troubleshooting-market-insights-api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseUnauthorized" }, "examples": { "missingOrInvalidToken": { "summary": "Missing, invalid or expired bearer token", "value": { "meta": { "ruid": "" }, "warnings": [], "errors": [ { "message": "", "code": "", "details": null } ] } } } } } }, "403": { "description": "Provider not certified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "propertyNotAccessible": { "summary": "Property not accessible with these credentials", "value": { "warnings": [], "errors": [ { "message": "Unable to process", "code": 450, "description": "Forbidden" } ], "meta": { "ruid": "" } } }, "propertyIdNotValid": { "summary": "Property ID is not valid", "value": { "warnings": [], "errors": [ { "message": "Data not found", "code": 635, "description": "Not found" } ], "meta": { "ruid": "" } } } } } } }, "500": { "description": "Internal server error" } } } }, "/properties/{propertyId}/pace_report_data": { "get": { "tags": [ "Market Insights" ], "summary": "Get pace report data for a property", "operationId": "paceReportData", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "date_range", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } }, { "name": "view_by", "in": "query", "schema": { "type": "string", "enum": [ "MONTH", "WEEK", "DATE", "NONE" ] } }, { "name": "compare_with", "in": "query", "schema": { "type": "string", "enum": [ "NONE", "LAST_YEAR", "COMPETITIVE_SET", "PEER_GROUP", "MARKET" ] } } ], "responses": { "200": { "description": "Pace report retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketInsightResponse" }, "example": { "data": { "report": { "adr": { "value": 138.11, "comparison_set": 132.5, "percent_change": 4.2 }, "room_nights": { "value": 1442, "comparison_set": 1380, "percent_change": 4.5 }, "revenue": { "value": 199153.26, "comparison_set": 182850, "percent_change": 8.9 } } }, "warnings": [], "errors": [], "meta": null } } } }, "400": { "description": "Invalid parameter value. The `errors` entry names the parameter and lists its allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "invalidDateRange": { "summary": "Invalid date_range value", "value": { "warnings": [], "errors": [ { "message": "Invalid value", "code": 320, "details": { "fields": [ "query param date_range" ], "allowed_values": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } } ], "meta": { "ruid": "" } } } } } } }, "401": { "description": "Unauthorized. The bearer token is missing, invalid or expired. For the possible error codes and fixes, see [Troubleshooting Market Insights API error responses](/connectivity/docs/market-insights-api/troubleshooting-market-insights-api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseUnauthorized" }, "examples": { "missingOrInvalidToken": { "summary": "Missing, invalid or expired bearer token", "value": { "meta": { "ruid": "" }, "warnings": [], "errors": [ { "message": "", "code": "", "details": null } ] } } } } } }, "403": { "description": "Provider not certified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "propertyNotAccessible": { "summary": "Property not accessible with these credentials", "value": { "warnings": [], "errors": [ { "message": "Unable to process", "code": 450, "description": "Forbidden" } ], "meta": { "ruid": "" } } }, "propertyIdNotValid": { "summary": "Property ID is not valid", "value": { "warnings": [], "errors": [ { "message": "Data not found", "code": 635, "description": "Not found" } ], "meta": { "ruid": "" } } } } } } }, "500": { "description": "Internal server error" } } } }, "/properties/{propertyId}/sales_statistics_report_data": { "get": { "tags": [ "Market Insights" ], "summary": "Get sales statistics report data for a property", "operationId": "salesStatisticsReportData", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "start_date", "in": "query", "description": "YYYY-MM-DD", "required": true, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "description": "YYYY-MM-DD", "required": true, "schema": { "type": "string" } }, { "name": "include_reservations", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "BOOK_DATE_GROSS", "BOOK_DATE_NET", "STAY_DATE_NET" ] } }, { "name": "view_by", "in": "query", "schema": { "type": "string", "enum": [ "MONTH", "WEEK", "DATE", "NONE" ] } }, { "name": "compare_with", "in": "query", "schema": { "type": "string", "enum": [ "NONE", "LAST_YEAR", "COMPETITIVE_SET", "PEER_GROUP", "MARKET" ] } } ], "responses": { "200": { "description": "Sales statistics retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketInsightResponse" }, "example": { "data": { "month": [ { "value": "2024-01", "percent": null, "percent_comparison_set": null, "report": { "adr": { "value": 142.35, "comparison_set": 138.9, "percent_change": 2.5 }, "room_nights": { "value": 320, "comparison_set": 295, "percent_change": 8.5 }, "revenue": { "value": 45552, "comparison_set": 40975.5, "percent_change": 11.2 } } } ] }, "warnings": [], "errors": [], "meta": null } } } }, "400": { "description": "Invalid date format or range. The `errors` entry names the parameter and lists its allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "invalidDateRange": { "summary": "Invalid date_range value", "value": { "warnings": [], "errors": [ { "message": "Invalid value", "code": 320, "details": { "fields": [ "query param date_range" ], "allowed_values": [ "LAST_365_DAYS", "LAST_90_DAYS", "LAST_60_DAYS", "LAST_30_DAYS", "LAST_14_DAYS", "LAST_7_DAYS" ] } } ], "meta": { "ruid": "" } } } } } } }, "401": { "description": "Unauthorized. The bearer token is missing, invalid or expired. For the possible error codes and fixes, see [Troubleshooting Market Insights API error responses](/connectivity/docs/market-insights-api/troubleshooting-market-insights-api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseUnauthorized" }, "examples": { "missingOrInvalidToken": { "summary": "Missing, invalid or expired bearer token", "value": { "meta": { "ruid": "" }, "warnings": [], "errors": [ { "message": "", "code": "", "details": null } ] } } } } } }, "403": { "description": "Provider not certified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "propertyNotAccessible": { "summary": "Property not accessible with these credentials", "value": { "warnings": [], "errors": [ { "message": "Unable to process", "code": 450, "description": "Forbidden" } ], "meta": { "ruid": "" } } }, "propertyIdNotValid": { "summary": "Property ID is not valid", "value": { "warnings": [], "errors": [ { "message": "Data not found", "code": 635, "description": "Not found" } ], "meta": { "ruid": "" } } } } } } }, "500": { "description": "Internal server error" } } } } }, "components": { "schemas": { "DemandDataCategory": { "type": "object", "properties": { "category_summary": { "type": "string" }, "category_name": { "type": "string" }, "title": { "type": "string" }, "stats": { "type": "array", "items": { "$ref": "#/components/schemas/DemandDataStat" } } } }, "DemandDataReport": { "type": "object", "properties": { "report_date": { "type": "string" }, "report_area": { "type": "string" }, "demand_data": { "type": "array", "items": { "$ref": "#/components/schemas/DemandDataCategory" } } } }, "DemandDataStat": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "formatted_score": { "type": "string" } } }, "ApiError": { "type": "object", "properties": { "message": { "type": "string", "description": "Short name of the error, for example `Invalid value`." }, "code": { "type": "integer", "format": "int32", "description": "OTA error code, for example `320` or `450`." }, "description": { "type": "string", "description": "Explains the cause of the error." }, "details": { "type": "object", "description": "Identifies the parameter that caused the error.", "properties": { "fields": { "type": "array", "description": "Names of the affected parameters.", "items": { "type": "string" } }, "allowed_values": { "type": "array", "description": "Values the parameter accepts, when the error lists them.", "items": { "type": "string" } } } } } }, "MarketInsightBreakdown": { "type": "object", "properties": { "value": { "type": "string" }, "percent": { "type": "number", "format": "double" }, "percent_comparison_set": { "description": "Percent change compared with the comparison set. The API returns the string \"NaN\" when the comparison total is zero.", "oneOf": [ { "type": "number", "format": "double" }, { "type": "string", "enum": [ "NaN" ] } ] }, "report": { "$ref": "#/components/schemas/MarketInsightReport" } }, "description": "Root object for all breakdowns" }, "MarketInsightInfo": { "type": "object", "properties": { "country": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInsightBreakdown" } }, "book_window": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInsightBreakdown" } }, "month": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInsightBreakdown" } }, "week": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInsightBreakdown" } }, "date": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInsightBreakdown" } }, "report": { "$ref": "#/components/schemas/MarketInsightReport" }, "total_booked_rooms": { "type": "number", "format": "double" } }, "description": "Breakdowns array" }, "MarketInsightReport": { "type": "object", "properties": { "adr": { "$ref": "#/components/schemas/MarketInsightStatistic" }, "room_nights": { "$ref": "#/components/schemas/MarketInsightStatistic" }, "revenue": { "$ref": "#/components/schemas/MarketInsightStatistic" } }, "description": "Root object for the reports" }, "MarketInsightResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MarketInsightInfo" }, "ruid": { "type": "string", "writeOnly": true }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "MarketInsightStatistic": { "type": "object", "properties": { "value": { "type": "number", "format": "double" }, "comparison_set": { "type": "number", "format": "double" }, "percent_change": { "type": "number", "format": "double" } }, "description": "Root object for all insights" }, "ApiErrorResponse": { "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ApiResponseUnauthorized": { "type": "object", "description": "Response returned when the bearer token is missing, invalid or expired. The error entry has empty `message` and `code` values.", "properties": { "warnings": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "nullable": true } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "DemandDataResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DemandDataReport" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ObjectNode": { "type": "object" }, "ResponseMeta": { "type": "object", "properties": { "ruid": { "type": "string" } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "string" } } } }