learn more about rules and limitations of Note: Note: learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "what is chatgpt"
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results Note: Note: Note: Note: learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 1024,
"temperature": 0.3,
"web_search_country_iso_code": "FR",
"model_name": "claude-sonnet-5",
"web_search": true,
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"model_name": "gemini-2.5-flash",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: learn more about rules and limitations of GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: where learn more about rules and limitations of GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: you can add several filters at once (8 filters maximum) the full list of possible filters is available here. you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en"
}
]
},
"Response463397119C53_AppDataAppleAppInfoTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppInfoTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppInfoTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results you can receive the list of available filters_by making a separate request to note that you can set no more than three sorting rules in a single request Your account will be billed per each SERP containing up to 25 results; learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
},
"Response463397119C53_AppDataAppleAppReviewsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppReviewsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppReviewsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"keyword": "vpn",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
},
"Response463397119C53_AppDataAppleAppSearchesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppSearchesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppSearchesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results you can receive the list of available filters_by making a separate request to note that you can set no more than three sorting rules in a single request learn more about rules and limitations of default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: you can get the full list of semantic elements here default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: default value: today's date -(minus) one month; date format: default value: today's date -(minus) one month; date format: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: you can get the full list of semantic elements here you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: you can get the full list of semantic elements here default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: you can get the full list of semantic elements here you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: you can get the full list of semantic elements here default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier possible values: you can get the full list of semantic elements here default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier note that the number of broken pages includes pages on the possible values: you can get the full list of semantic elements here minimum value: note: for for example, if you specify: if there is no data for a certain minimum value: note: for for example, if you specify: if there is no data for a certain you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of Note: if you use this field, your account will be charged three times the standard rate for tasks involving the Google Reviews API"
},
"cid": {
"type": "string",
"description": "unique, google-defined id of the business entity Note: if you use this field, your account will be charged two times the standard rate for tasks involving the Google Reviews API"
},
"place_id": {
"type": "string",
"description": "identifier of the business entity in Google Maps Note: if you use this field, your account will be charged two times the standard rate for tasks involving the Google Reviews API"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority Your account will be billed per each SERP containing up to 20 results; learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"location_name": "London,England,United Kingdom",
"language_name": "english",
"cid": "17626775537598922320"
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleExtendedReviewsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results set the following value if you want to include one 14-years-old child: set the following value if you want to include one 14-years-old child: set the following value if you want to include one 14-years-old child: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE",
"tag": "some_string_123",
"postback_url": "https://your-server.com/postbackscript.php",
"postback_data": "advanced"
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "cheap hotel",
"check_in": "2023-06-01",
"check_out": "2023-06-30",
"currency": "USD",
"adults": 2,
"children": [
"14"
],
"sort_by": "highest_rating",
"priority": 2,
"tag": "example"
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about the learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"location_name": "London,England,United Kingdom",
"language_name": "English",
"keyword": "hedonism wines",
"depth": 50,
"sort_by": "highest_rating"
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleReviewsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"url_path": "Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html",
"location_code": 1003854,
"pingback_url": "https://your-server.com/pingback.php?id=$id&tag=$tag",
"tag": "some_string_123"
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorReviewsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of Your account will be billed per each SERP containing up to 30 results; learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"keyword": "pizza",
"location_code": 1003854,
"depth": 30
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorSearchTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"domain": "www.thepearlsource.com",
"depth": 40
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotReviewsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"keyword": "pizza restaurant",
"depth": 20
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotSearchTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules Note: all letters in ASIN code must be specified in uppercase format; for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules learn more about rules and limitations of for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default rule: for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default rule: for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules learn more about rules and limitations of Note: if the possible values: learn more about how clickstream-based metrics are calculated in this help center articlen"
},
"historical_serp_mode": {
"type": [
"string",
"null"
],
"description": "data collection mode Note: if the possible values: default rule: learn more about rules and limitations of Note: if the possible values: learn more about how clickstream-based metrics are calculated in this help center articlen"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default rule: if you specify example: Note: if the possible values: note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn't contain such keywords and cannot return data on them learn more about rules and limitations of Note: historical clickstream data is available from 2024/05 (May, 2024); learn more about rules and limitations of learn more about how clickstream-based metrics are calculated in this help center article"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of keywords in the results array [\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]] default rule: note that you can set no more than three sorting rules in a single request note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn't contain such keywords and cannot return data on them learn more about rules and limitations of learn more about how clickstream-based metrics are calculated in this help center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of learn more about how clickstream-based metrics are calculated in this help center article"
},
"exact_match": {
"type": [
"boolean",
"null"
],
"description": "search for the exact phrase for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules learn more about how clickstream-based metrics are calculated in this help center article"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords learn more about how clickstream-based metrics are calculated in this help center article"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of keywords in the results array default rule: Note: if the possible values: learn more about how clickstream-based metrics are calculated in this help center article"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords if you want to get the keywords a particular webpage ranks for, you can use a learn more about rules and limitations of number of the returned results depends on the value you set in this field [\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]] Note: if the possible values: learn more about how clickstream-based metrics are calculated in this help center article"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages example: default rule: learn more about rules and limitations of learn more about rules and limitations of possible values: Note: if the possible values: learn more about how clickstream-based metrics are calculated in this help center article"
},
"historical_serp_mode": {
"type": [
"string",
"null"
],
"description": "data collection mode default rule: learn more about how clickstream-based metrics are calculated in this help center article"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords [\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]] learn more about rules and limitations of for more information about filters, please refer to Domain Analytics Technologies API - Filters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules learn more about rules and limitations of for more information about filters, please refer to Domain Analytics Technologies API - Filters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules learn more about rules and limitations of for more information about filters, please refer to Domain Analytics Technologies API - Filters"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays if you use this field, you can receive the list of available industry names with industry_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/industries example: if you use this field, you can receive the list of available job function names with job_function_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/job_functions example: example: example: if you use this field, you can receive the list of available industry names with industry_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/industries example: if you use this field, you can receive the list of available job function names with job_function_id by making a separate request to the https://api.dataforseo.com/v3/keywords_data/bing/audience_estimation/job_functions example: learn more about rules and limitations of _ _ _ _ _ _ learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of Note: we do not recommend using a custom time range for the past year's dates"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range Note: we do not recommend using a custom time range for the past year's dates"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "Bing search partners type if there is no data, then the value is_ search volume is rounded to the closest decimal values if there is no data, then the value is_ learn more about rules and limitations of Note: we do not recommend using a custom time range for the past year's dates"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range Note: we do not recommend using a custom time range for the past year's dates"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "Bing search partners type learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier Note: we do not recommend using a custom time range for the past year's dates"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range Note: we do not recommend using a custom time range for the past year's dates"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters search volume is rounded to the closest decimal values if there is no data the value is Note: we do not recommend using a custom time range for the past year's dates"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range Note: we do not recommend using a custom time range for the past year's dates"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "Bing search partners type learn more about rules and limitations of Note: we do not recommend using a custom time range for the past year's dates"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range Note: we do not recommend using a custom time range for the past year's dates"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "Bing search partners type default value: date format: Note 2: if if you specify the with value Note: we do not recommend using a custom time range Note 2: if if you specify the with value learn more about rules and limitations of possible values: default value: Note: we do not recommend using a custom time range Note 2: if if you specify the with value minimum value: two years back from today’s date; Note: we do not recommend using a custom time range Note 2: if if you specify the with value learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier Note: keywords cannot consist of a combination of the following characters: Note: to obtain learn more about rules and limitations of Note: to obtain Note: keywords cannot consist of a combination of the following characters: Note: to obtain learn more about rules and limitations of Note: to obtain learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"asin": "B0756FCPPN"
}
]
},
"Response463397119C53_MerchantAmazonAsinTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"keyword": "shoes"
}
]
},
"Response463397119C53_MerchantAmazonProductsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"asin": "B085RFFC9Q"
}
]
},
"Response463397119C53_MerchantAmazonSellersTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
],
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"product_id": "1113158713975221117"
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductInfoTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "iphone",
"price_min": 5
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results learn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
]
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"product_id": "1113158713975221117"
}
]
},
"Response463397119C53_MerchantGoogleSellersTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleSellersTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleSellersTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results possible values: Note: to use this parameter, set Note: to use this parameter, set minimum value, in pixels: Note: to use this parameter, set minimum value, in pixels: Note: to use this parameter, set minimum value: if you use this field, note: you can set up to 1000 The full list of possible filters is available by this link."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules if you ignore this field, we will return data for all categories unless you specify possible values: if you ignore this field, we will return data for all audits; Note: that some audits do not belong to a specific category and are stand-alone page quality measurements; in general, there can be several use cases: 1. if you ignore 2. if you specify a category, you can use this field to additionally receive audits that do not belong to the category(-ies) you specified you can get the full list of possible audits here"
},
"version": {
"type": [
"string",
"null"
],
"description": "lighthouse version all fields and their descriptions are available in the official documentation by this link."
}
}
}
]
},
"Response463397119C53_OnPageLighthouseTaskGetJsonResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseTaskGetJsonTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseTaskGetJsonTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
}
}
}
}
}
]
},
"Provider463397119C53_OnPageLighthouseTaskPostRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "target URL possible values: note that some audits do not belong to a specific category and are stand-alone page quality measurements in general, there can be several use cases: 1. if you ignore 2. if you specify a category, you can use this field to additionally receive audits that do not belong to the category(-ies) you specified you can get the full list of possible audits here"
},
"version": {
"type": [
"string",
"null"
],
"description": "lighthouse version The full list of possible filters is available by this link."
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests The full list of possible filters is available by this link."
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"filters": [
[
"reason",
"=",
"robots_txt"
],
"and",
[
"url",
"like",
"%go%"
]
],
"limit": 10
}
]
},
"Response463397119C53_OnPageNonIndexableResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageNonIndexableTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageNonIndexableTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageNonIndexableResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageNonIndexableResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session possible values: Note: in this endpoint, the minimum value, in pixels: minimum value, in pixels: minimum value: The full list of possible filters is available by this link."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules the following filtering parameter is supported: examples: The full list of possible filters is available by this link."
},
"relevant_pages_filters": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "filter the resources by relevant pages learn more on our Help Center"
}
},
"example": [
{
"target": "dataforseo.com",
"max_crawl_pages": 10,
"load_resources": true,
"enable_javascript": true,
"custom_js": "meta = {}; meta.url = document.URL; meta;",
"tag": "some_string_123",
"pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
}
]
},
"Response463397119C53_OnPageTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results The full list of possible filters is available by this link."
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"filters": [
[
"meta.content_type",
"=",
"image/jpeg"
],
"and",
[
"url",
"like",
"%go%"
]
],
"limit": 10
}
]
},
"Response463397119C53_OnPageUncrawlableResourcesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageUncrawlableResourcesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageUncrawlableResourcesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageUncrawlableResourcesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageUncrawlableResourcesResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session learn more about rules and limitations of example: example: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"location_code": 2156,
"keyword": "best iphone ever",
"tag": "some_string_123",
"priority": 2
}
]
},
"Provider463397119C53_SerpApiStopCrawlOnMatchInfo": {
"type": "object",
"properties": {
"match_value": {
"type": [
"string",
"null"
],
"description": "arget domain or wildcard value\nrequired field if stop_crawl_on_match is specified;\nspecify a target domain or wildcard value;\nNote: domain name must be specified without a request protocol;\nexample: dataforseo.com"
},
"match_type": {
"type": [
"string",
"null"
],
"description": "target match type\nrequired field if stop_crawl_on_match is specified;\ntype of match for the match_value\npossible values: domain, with_subdomains, wildcard"
}
}
},
"Response463397119C53_SerpBaiduOrganicTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results where `location_code_parent` corresponds to: `\"location_code\": 20044`, keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified target domain, subdomain, or webpage to get results for optional field a domain or a subdomain should be specified without note that the results of you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results; examples: target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl default value: max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here calculate pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to \n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": " browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl default value: max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified target domain, subdomain, or webpage to get results for optional field a domain or a subdomain should be specified without note that the results of you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results; examples: target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl default value: max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl default value: max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here calcualte pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to \n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": " browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 example: where keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"location_code": {
"type": [
"integer",
"null"
],
"description": " search engine location code optional field if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: Note: if you don't specify notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the function you used for setting a task possible values: full name of search engine location optional field if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: Note: if you don't specify GPS coordinates of a location optional field if you use this field, you don't need to specify example: Note: if you don't specify user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified where `location_code_parent` corresponds to: `\"location_code\": 20044`, advertiser identifiers required field if you can specify the maximum of 25 values in this array; domain name required field if domain name associated with an advertiser account search engine location code optional field if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: Note: if you don't specify parsing depth optional field number of results in SERP default value: max value: Setting depth above 40 may result in additional charges if the search engine returns more than 40 results; The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": " notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the function you used for setting a task possible values: full name of search engine location optional field if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: Note: if you don't specify GPS coordinates of a location optional field if you use this field, you don't need to specify example: Note: if you don't specify user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified advertising platform optional field possible values: default value: ad format optional field possible values: starting date of the time range optional field required field if date format: minimum value: 2018-05-31 maximum value: today's date example: ending date of the time range optional field required field if date format: minimum value: 2018-05-31 maximum value: today's date example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their Note: check Google Search Help for the list of countries where AI Mode is currently available search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their Note: check Google Search Help for the list of countries where AI Mode is currently available full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified calculate pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to Note: if set to browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 9z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 4z the maximum value for \"zoom\": 18z example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their Note: check Google Search Help for the list of countries where AI Mode is currently available search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the function you used for setting a task possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their Note: check Google Search Help for the list of countries where AI Mode is currently available full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified calculate pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to Note: if set to browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 9z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 4z the maximum value for \"zoom\": 18z example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their search bar cursor pointer optional field the horizontal numerical position of the cursor pointer within the keyword in the search bar; by modifying the position of the cursor pointer, you will obtain different autocomplete suggestions for the same seed keyword; minimal value: default value: the number of the last character of the specified example: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: search client for autocomplete optional field autocomplete results may differ depending on the search client; possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their search bar cursor pointer optional field the horizontal numerical position of the cursor pointer within the keyword in the search bar; by modifying the position of the cursor pointer, you will obtain different autocomplete suggestions for the same seed keyword; minimal value: default value: the number of the last character of the specified example: task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": " notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.e., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: search client for autocomplete optional field autocomplete results may differ depending on the search client; possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified ID of the dataset required field you can find dataset ID in the dataset URL or example: search engine language code optional field if you use this field, you don't need to specify possible value: device type optional field return results for a specific device type possible value: full name of search engine language optional field if you use this field, you don't need to specify possible value: device operating system optional field possible values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified ID of the dataset required field you can find dataset ID in the dataset URL or example: search engine language code optional field if you use this field, you don't need to specify possible value: task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type possible value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible value: full name of search engine language optional field if you use this field, you don't need to specify possible value: device operating system optional field choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine language code optional field if you don't specify if you use this field, you don't need to specify possible value: parsing depth optional field number of results in SERP default value: max value: Setting depth above 20 may result in additional charges if the search engine returns more than 20 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type possible value: full name of search engine language optional field if you use this field, you don't need to specify possible value: device operating system optional field choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified last time the dataset was updated optional field possible values: file formats of the dataset optional field possible values: usage rights of the dataset optional field possible values: indicates whether displayed datasets are free optional field possible values: dataset topics optional field possible values: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine language code optional field possible value: parsing depth optional field number of results in SERP default value: max value: Setting depth above 20 may result in additional charges if the search engine returns more than 20 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically;"
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type possible value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server only value: full name of search engine language optional field if you use this field, you don't need to specify possible value: device operating system optional field possible values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified last time the dataset was updated optional field possible values: file formats of the dataset optional field possible values: usage rights of the dataset optional field possible values: indicates whether displayed datasets are free optional field possible values: dataset topics optional field possible values: search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified financial news filters optional field possible values: default value: Note: if you specify search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field possible value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified financial news filters optional field possible values: default value: search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values:: task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page"
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified financial news filters optional field possible values: default value: Note: if you specify search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified type of google finance market optional field possible values: default value: search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field possible value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified type of google finance market optional field possible values: default value: search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values:: task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page"
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified type of google finance market optional field possible values: default value: ticker or stock symbol required field in this field you can pass the ticker symbol of publicly traded shares of a particular stock or security on a particular stock exchange; you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified time window for optional field possible values: default value: Note: if you specify a value that is different from ticker or stock symbol required field in this field you can pass the ticker symbol of publicly traded shares of a particular stock or security on a particular stock exchange; you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified time window for optional field possible values: default value: ticker or stock symbol required field in this field you can pass the ticker symbol of publicly traded shares of a particular stock or security on a particular stock exchange; you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their device type optional field return results for a specific device type possible value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values:: task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page"
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field possible values: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified time window for optional field possible values: default value: Note: if you specify a value that is different from company or financial instrument name required field in this field, you can enter the name of a company or financial instrument to search for relevant tickers; you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified category of financial instruments to search for optional field possible values: default value: company or financial instrument name required field in this field, you can enter the name of a company or financial instrument to search for relevant tickers; you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values:: task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page"
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified category of financial instruments to search for optional field possible values: default value: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5 Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically; The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field note that this API provides results for desktop only choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field Get the list of available parameters and additional details here. direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field We choose the relevant search engine domain automatically according to the location and language you specify. However, you can set a custom search engine domain in this field example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5 Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically; The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field note that this API provides results for desktop only choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5 Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically; The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": " notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field note that this API provides results for desktop only choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your Note: the keyword you specify must indicate the job title; example: learn more about rules and limitations of search engine location code required field if you don't specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP; default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically; The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": " notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified location search radius optional field location search radius in kilometers; Note: for countries that use the imperial system of units, you will need to convert miles to kilometers by multiplying the value in miles by if value is not specified, search is executed anywhere within the specified location; maximal value: minimal value: employment contract type optional field type of employment contract for which the search results will be returned; possible values: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results respectively; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"location_coordinate": {
"type": "string",
"description": " GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 9z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 4z the maximum value for \"zoom\": 18z example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 9z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 4z the maximum value for \"zoom\": 18z example: filter results by minimum rating optional field possible values for possible values for filter results by open hours optional field using this field, you can filter places in the results by the time a place is open for visitors note that Google may also provide results that do not match this filter possible values: instead of instead of example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: parsing depth optional field number of results in SERP default value: max value: If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the function you used for setting a task possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 9z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 4z the maximum value for \"zoom\": 18z example: where `location_code_parent` corresponds to: `\"location_code\": 20044`, keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: note: for full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 17z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 3z the maximum value for \"zoom\": 21z example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: show results from the displayed area optional field can take the values: default value: if set to Note: if the search places mode optional field the search places mode allows to obtain Google Maps results on a certain place (e.g., Apple Store in New York) however, due to the pecularities of our data mining algorithm, this mode might interfere with some local-intent queries - and display results for a location that is different from that specified in the request; to prevent this interference and obtain correct results for keywords with local intent you may set this parameter to default value: Note: if the keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 100 may result in additional charges if the search engine returns more than 100 results; The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: note: for notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the function you used for setting a task possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify if \"zoom\" is not specified, 17z will be applied as a default value the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"zoom\": 3z the maximum value for \"zoom\": 21z example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: show results from the displayed area optional field can take the values: default value: if set to Note: if the search places mode optional field the search places mode allows to obtain Google Maps results on a certain place (e.g., Apple Store in New York) however, due to the pecularities of our data mining algorithm, this mode might interfere with some local-intent queries - and display results for a location that is different from that specified in the request; to prevent this interference and obtain correct results for keywords with local intent you may set this parameter to Note: if the user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5 Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field note that this API provides results for desktop only choose from the following values: default value: page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field Get the list of available parameters and additional details here. calculate pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to Note: if set to browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5 Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: device operating system optional field note that this API provides results for desktop only choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5 Note: queries containing the ‘cache:’ parameter are not supported and will return a validation error learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automatically; The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": " task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": " notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field note that this API provides results for desktop only choose from the following values: default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here calculate pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to Note: if set to browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields; Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method; example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', ‘cache:’, 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'related:', 'site:', the charge per task will be multiplied by 5"
},
"location_code": {
"type": "integer",
"description": " search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: load asynchronous ai overview optional field set to if set to default value: if the element is absent or contains full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl max value: Note: you will be charged for each page crawled (10 organic results per page); learn more about pricing on our Pricing page; Note#2: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here expand ai overview optional field set to default value: direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: target matching mode optional field to enable this parameter, defines how the crawl should stop when multiple targets are specified in possible values: default value: learn more about this parameter on our Help Center SERP element types to check for targets optional field to enable this parameter, specifies which SERP element types should be checked for target matches if not specified, all first-level elements with possible values: Note: cannot contain the same element types as example: learn more about this parameter on our Help Center SERP element types to exclude from target search optional field to enable this parameter, specifies which SERP element types should be excluded when searching for target matches possible values: Note: cannot contain the same element types as example: learn more about this parameter on our Help Center keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character '+' will be decoded to a space character) if you need to use the \"%\" character for your if you need to use the “+” character for your if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', ‘cache:’, 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'site:', the charge per task will be multiplied by 5"
},
"location_code": {
"type": "integer",
"description": " search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: device operating system optional field if you specify default value: if you specify default value: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl max value: Note: you will be charged for each page crawled (10 organic results per page); learn more about pricing on our Pricing page; Note#2: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here display related results optional field if set to if set to default value: direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: target domain, subdomain, or webpage to get results for optional field a domain or a subdomain should be specified without note that the results of you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results; examples: target matching mode optional field to enable this parameter, defines how the crawl should stop when multiple targets are specified in possible values: default value: learn more about this parameter on our Help Center SERP element types to check for targets optional field to enable this parameter, specifies which SERP element types should be checked for target matches if not specified, all first-level elements with possible values: Note: cannot contain the same element types as example: learn more about this parameter on our Help Center SERP element types to exclude from target search optional field to enable this parameter, specifies which SERP element types should be excluded when searching for target matches possible values: Note: cannot contain the same element types as example: learn more about this parameter on our Help Center note that this array contains all types of search results found in the returned SERP; note that this array contains all types of search results found in the returned SERP; keyword required field you can specify up to 700 characters in the all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your if you need to use the “+” character for your if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘cache:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘site:’, the charge per task will be multiplied by 5 learn more about rules and limitations of search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their parsing depth optional field number of results in SERP default value: max value: Setting depth above 10 may result in additional charges if the search engine returns more than 10 results; The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": " device type optional field return results for a specific device type can take the values: default value: load asynchronous ai overview optional field set to if set to default value: if the element is absent or contains notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: task priority optional field can take the following values: 1 – normal execution priority (set by default); 2 – high execution priority The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified device operating system optional field if you specify default value: if you specify default value: target match type required field if type of match for the possible values: target domain, subdomain, or wildcard value required field if specify a target domain, subdomain, or wildcard value; Note: domain or subdomain must be specified without a request protocol; example: page crawl limit optional field number of search results pages to crawl max value: Note: you will be charged for each page crawled (10 organic results per page); learn more about pricing on our Pricing page; Note#2: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here remove specific parameters from URLs optional field using this field, you can specify up to 10 parameters to remove from URLs in the result example: expand ai overview optional field set to default value: Note: this parameter applies only to HTML task results clicks on the corresponding element optional field specify the click depth on the if the element is absent or we perform fewer clicks than you specified, all extra charges will be returned to your account balance possible values: from display related results optional field if set to if set to default value: calcualte pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to \n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": " browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; can be specified within the following range: by default, the parameter is set to: Note: to use this parameter, set direct URL of the search query optional field you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method. example: target matching mode optional field to enable this parameter, defines how the crawl should stop when multiple targets are specified in possible values: default value: learn more about this parameter on our Help Center SERP element types to check for targets optional field to enable this parameter, specifies which SERP element types should be checked for target matches if not specified, all first-level elements with possible values: Note: cannot contain the same element types as example: learn more about this parameter on our Help Center SERP element types to exclude from target search optional field to enable this parameter, specifies which SERP element types should be excluded when searching for target matches possible values: Note: cannot contain the same element types as example: learn more about this parameter on our Help Center search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: URL of the image required field the results will be based on the image you specified in this field example: search engine location code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engines with their example: search engine language code required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the you can use the ‘$id’ string as a example: Note: special characters in i.a., the learn more on our Help Center postback_url datatype required field if you specify corresponds to the datatype that will be sent to your server possible values: task priority optional field can take the following values: 1 – normal execution priority (set by default) 2 – high execution priority The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": " full name of search engine location required field if you don't specify if you use this field, you don't need to specify you can receive the list of available locations of the search engine with their example: full name of search engine language required field if you don't specify if you use this field, you don't need to specify you can receive the list of available languages of the search engine with their example: user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified page crawl limit optional field number of search results pages to crawl max value: Note: the learn more at our help center additional parameters of the search query optional field get the list of available parameters and additional details here calculate pixel rankings for SERP elements in advanced results optional field pixel ranking refers to the distance between the result snippet and top left corner of the screen; Visit Help Center to learn more>> by default, the parameter is set to Note: if set to browser screen width optional field you can set a custom browser screen width to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set browser screen height optional field you can set a custom browser screen height to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set browser screen resolution ratio optional field you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device; by default, the parameter is set to Note: to use this parameter, set GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199.9 (mm) the maximum value for \"radius\": 199999 (mm) example: search engine domain optional field we choose the relevant search engine domain automatically according to the location and language you specify however, you can set a custom search engine domain in this field example: note that this array contains all types of search results found in the returned SERP; to get all items (inlcuding SERP features and rich snippets) found in the returned SERP, please refer to the Naver Organiс Advanced SERP endpoint"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"keyword": "albert einstein",
"device": "desktop",
"tag": "some_string_123",
"postback_url": "https://your-server.com/postbackscript.php",
"postback_data": "regular"
}
]
},
"Response463397119C53_SerpNaverOrganicTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results note that this array contains all types of search results found in the returned SERP; to get all items (inlcuding SERP features and rich snippets) found in the returned SERP, please refer to the Seznam Organiс Advanced SERP endpoint"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "cs",
"location_code": 2203,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results where `location_code_parent` corresponds to: `\"location_code\": 20044`, learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_SerpYahooOrganicTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results where `location_code_parent` corresponds to: `\"location_code\": 20044`, learn more about rules and limitations of Note: Note: learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "what is chatgpt"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "what is chatgpt"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:3dfc284cb998232fdec4fed99f0d9ab4d55af84ec9da111b853fb13a8489cb7a"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_post \\\n --header 'Authorization: Bearer Note: Note: Note: Note: learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 1024,
"temperature": 0.3,
"web_search_country_iso_code": "FR",
"model_name": "claude-sonnet-5",
"web_search": true,
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 1024,
"temperature": 0.3,
"web_search_country_iso_code": "FR",
"model_name": "claude-sonnet-5",
"web_search": true,
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:90c8c29cb99e8904e9f4c32205dc6f2a270460e21e0d01b3e7bc0c02eabf26e9"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/claude/llm_responses/task_post \\\n --header 'Authorization: Bearer learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"model_name": "gemini-2.5-flash",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"model_name": "gemini-2.5-flash",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:450e3ddd6ff7cfd197436e32db8f1641da30a73b5d4980b4cbd5b565ea35ead3"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/task_post \\\n --header 'Authorization: Bearer learn more about rules and limitations of GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: learn more about rules and limitations of GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: learn more about rules and limitations of GPS coordinates of a location required field if you don't specify if you use this field, you don't need to specify the maximum number of decimal digits for \"latitude\" and \"longitude\": 7 the minimum value for \"radius\": 199 (mm) the maximum value for \"radius\": 199999 (mm) example: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d6c3ee120ee631f5d1926667a5f54bbc768519355cc5ebef995ebea471b3b09c"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/task_post \\\n --header 'Authorization: Bearer The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: you can add several filters at once (8 filters maximum) the full list of possible filters is available here. you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: The full list of possible filters is available here."
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation you can add several filters at once (8 filters maximum) the full list of possible filters is available here. default value: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en"
}
]
}
]
},
"example": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:3fdb393ed15ea643417ce7a7322d1e3f60db40a6bc4eef998a05958fb5ef8326"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_info/task_post \\\n --header 'Authorization: Bearer you can receive the list of available filters_by making a separate request to note that you can set no more than three sorting rules in a single request Your account will be billed per each SERP containing up to 25 results; learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
}
]
},
"example": [
{
"app_id": "835599320",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b49453461d1534d8c43b9496184cecd2d5b2386413e4f1c2024f6685b58b1014"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_reviews/task_post \\\n --header 'Authorization: Bearer learn more about rules and limitations of learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"keyword": "vpn",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
}
]
},
"example": [
{
"keyword": "vpn",
"location_code": 2840,
"language_code": "en",
"depth": 200
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:69f67f146d4ab10a5ca40b9957756177cd61790167f77d6db644e9c12c5918e4"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_searches/task_post \\\n --header 'Authorization: Bearer you can receive the list of available filters_by making a separate request to note that you can set no more than three sorting rules in a single request learn more about rules and limitations of default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: today's date -(minus) one month; date format: default value: today's date -(minus) one month; date format: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules default value: default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: default value: The full list of possible filters is available here."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier default value: default value: you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier minimum value: note: for for example, if you specify: if there is no data for a certain minimum value: note: for for example, if you specify: if there is no data for a certain you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works and how ranking metrics are calculated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of Note: if you use this field, your account will be charged three times the standard rate for tasks involving the Google Reviews API"
},
"cid": {
"type": "string",
"description": "unique, google-defined id of the business entity Note: if you use this field, your account will be charged two times the standard rate for tasks involving the Google Reviews API"
},
"place_id": {
"type": "string",
"description": "identifier of the business entity in Google Maps Note: if you use this field, your account will be charged two times the standard rate for tasks involving the Google Reviews API"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority Your account will be billed per each SERP containing up to 20 results; learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"location_name": "London,England,United Kingdom",
"language_name": "english",
"cid": "17626775537598922320"
}
]
}
]
},
"example": [
{
"location_name": "London,England,United Kingdom",
"language_name": "english",
"cid": "17626775537598922320"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:c1cf6c3aa97dcd525fc011d9347291b487fc7bccbcbc295838ebca8c7de6379b"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/extended_reviews/task_post \\\n --header 'Authorization: Bearer set the following value if you want to include one 14-years-old child: set the following value if you want to include one 14-years-old child: set the following value if you want to include one 14-years-old child: learn more on our Help Center"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE",
"tag": "some_string_123",
"postback_url": "https://your-server.com/postbackscript.php",
"postback_data": "advanced"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE",
"tag": "some_string_123",
"postback_url": "https://your-server.com/postbackscript.php",
"postback_data": "advanced"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:63b2d0edbd0c3617312ac6bf8165cf3211615450cd35e6f5f80934464a4116ba"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_info/task_post \\\n --header 'Authorization: Bearer learn more about rules and limitations of learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "cheap hotel",
"check_in": "2023-06-01",
"check_out": "2023-06-30",
"currency": "USD",
"adults": 2,
"children": [
"14"
],
"sort_by": "highest_rating",
"priority": 2,
"tag": "example"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "cheap hotel",
"check_in": "2023-06-01",
"check_out": "2023-06-30",
"currency": "USD",
"adults": 2,
"children": [
"14"
],
"sort_by": "highest_rating",
"priority": 2,
"tag": "example"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:cb2296cf19784cec004702e30dfc2c1f184c2139232e2be32f5b634a91bc382e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_searches/task_post \\\n --header 'Authorization: Bearer this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:7655d2d99ae8da0e70e41700d603d6833339fa79d1ba257e99cfc2ccf66ffa12"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/my_business_info/task_post \\\n --header 'Authorization: Bearer learn more about the learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ecbac7e319b33555716e5ad9e2cdefd2a9eba77b83384af1b4366a6746cfbfc9"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/my_business_updates/task_post \\\n --header 'Authorization: Bearer this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of this field can also be used to pass the following parameters: example: learn more about the learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"location_name": "London,England,United Kingdom",
"language_name": "English",
"keyword": "hedonism wines",
"depth": 50,
"sort_by": "highest_rating"
}
]
}
]
},
"example": [
{
"location_name": "London,England,United Kingdom",
"language_name": "English",
"keyword": "hedonism wines",
"depth": 50,
"sort_by": "highest_rating"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:62428786c20aead0ac8dcf021eb3fda0a801e3e9eb06709a3e855196a7fee9d8"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/reviews/task_post \\\n --header 'Authorization: Bearer learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"url_path": "Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html",
"location_code": 1003854,
"pingback_url": "https://your-server.com/pingback.php?id=$id&tag=$tag",
"tag": "some_string_123"
}
]
}
]
},
"example": [
{
"url_path": "Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html",
"location_code": 1003854,
"pingback_url": "https://your-server.com/pingback.php?id=$id&tag=$tag",
"tag": "some_string_123"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:6718f78e130d4cf5e2efce1bd020eefd7b776dfaf822599612eebad2877ae3e0"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/tripadvisor/reviews/task_post \\\n --header 'Authorization: Bearer learn more about rules and limitations of Your account will be billed per each SERP containing up to 30 results; learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"keyword": "pizza",
"location_code": 1003854,
"depth": 30
}
]
}
]
},
"example": [
{
"keyword": "pizza",
"location_code": 1003854,
"depth": 30
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:e00c08bf374c3d08e7c94d21d8d3c03cbc192b0034f27c94af9480423e00484a"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/tripadvisor/search/task_post \\\n --header 'Authorization: Bearer learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"domain": "www.thepearlsource.com",
"depth": 40
}
]
}
]
},
"example": [
{
"domain": "www.thepearlsource.com",
"depth": 40
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d607589dfd9d538689e8424b01531cab5092173a404159319bca8346745c0a07"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/trustpilot/reviews/task_post \\\n --header 'Authorization: Bearer learn more about rules and limitations of learn more on our Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task learn more on our Help Center"
}
},
"example": [
{
"keyword": "pizza restaurant",
"depth": 20
}
]
}
]
},
"example": [
{
"keyword": "pizza restaurant",
"depth": 20
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:06336fea60884ccd726572a4402217db654ca559f96cb6952bd0d68554ea2258"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/trustpilot/search/task_post \\\n --header 'Authorization: Bearer [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of [\"content_info.text_category\",\"has\",10994]]] you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale possible values: default value: learn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:English"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"keywords": [
"iphone",
"seo"
]
}
]
},
"Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BaseResponseInfo": {
"properties": {
"version": {
"type": [
"string",
"null"
],
"description": "the current version of the API"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status code\nyou can find the full list of the response codes here"
},
"status_message": {
"type": [
"string",
"null"
],
"description": "general informational message\nyou can find the full list of general informational messages here"
},
"time": {
"type": [
"string",
"null"
],
"description": "total execution time, seconds"
},
"cost": {
"type": [
"number",
"null"
],
"description": "total tasks cost, USD",
"format": "double"
},
"tasks_count": {
"type": [
"integer",
"null"
],
"description": "the number of tasks in the tasks array",
"format": "int64"
},
"tasks_error": {
"type": [
"integer",
"null"
],
"description": "the number of tasks in the tasks array returned with an error",
"format": "int64"
}
}
},
"Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BaseResponseTaskInfo": {
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier\nunique task identifier in our system in the UUID format"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "status code of the task\ngenerated by DataForSEO, can be within the following range: 10000-60000\nyou can find the full list of the response codes here"
},
"status_message": {
"type": [
"string",
"null"
],
"description": "informational message of the task\nyou can find the full list of general informational messages here"
},
"time": {
"type": [
"string",
"null"
],
"description": "execution time, seconds"
},
"cost": {
"type": [
"number",
"null"
],
"description": "total tasks cost, USD",
"format": "double"
},
"result_count": {
"type": [
"integer",
"null"
],
"description": "number of elements in the result array",
"format": "int64"
},
"path": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "URL path"
},
"data": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
},
"description": "contains the same parameters that you specified in the POST request"
}
}
},
"Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveItem"
}
]
},
"description": "contains specified keywords with their AI search volume rates"
}
}
},
"Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveItem": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "specified keyword"
},
"ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "current AI search volume rate of a keyword
learn more about this metric here",
"format": "int64"
},
"ai_monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiMonthlySearches"
}
]
},
"description": "monthly AI search volume rates
array of objects with AI search volume rates in a certain month of a year"
}
}
},
"Response463397119C53_AiMonthlySearches": {
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "year"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month"
},
"ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "current AI search volume rate of a keyword
learn more about this metric here",
"format": "int64"
}
}
},
"Response463397119C53_AiOptimizationAiKeywordDataLocationsAndLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationAiKeywordDataLocationsAndLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationAiKeywordDataLocationsAndLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationAiKeywordDataLocationsAndLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationAiKeywordDataLocationsAndLanguagesResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"available_languages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvailableLanguages"
}
]
},
"description": "supported languages
contains the languages which are supported for a specific location"
}
}
},
"Response463397119C53_AvailableLanguages": {
"type": "object",
"properties": {
"available_sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "supported sources
contains the sources of data supported for a specific location and language combination
only google and bing are currently available"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
},
"keywords": {
"type": [
"integer",
"null"
],
"description": "the number of keywords available for the given location and language"
},
"serps": {
"type": [
"integer",
"null"
],
"description": "the number of SERP pages available for the given location and language"
}
}
},
"Provider463397119C53_AiOptimizationChatGptLlmResponsesLiveRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;
minimum value for non-reasoning models: 16;
maximum value: 4096;
default value: 2048
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 2
default value: 0.94
Note: not supported in reasoning models"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: 0.92top_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search
optional field
when enabled, the AI model can access and cite current web information;
default value: false;
Note: refer to the Models endpoint for a list of models that support web_search;"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response
Note #2: not supported in reasoning models"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model will search the web from the country you specify;
Note: not supported in o3-mini, o1-pro, o1 models"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location
optional field
Note: not supported in o3-mini, o1-pro, o1 models"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"model_name": "gpt-4.1-mini",
"web_search": true,
"web_search_country_iso_code": "FR",
"web_search_city": "Paris",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Provider463397119C53_LlmMessageChainItem": {
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesLiveResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"description": "number of reasoning tokens
total count of tokens used to generate reasoning content"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
}
}
},
"Response463397119C53_BaseAiOptimizationLlmResponseElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"reasoning": "#/components/schemas/Response463397119C53_ReasoningAiOptimizationLlmResponseElementItem",
"message": "#/components/schemas/Response463397119C53_MessageAiOptimizationLlmResponseElementItem"
}
}
},
"Response463397119C53_ReasoningAiOptimizationLlmResponseElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
{
"type": "object",
"properties": {
"sections": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocalJustificationInfo"
}
]
},
"description": "reasoning chain sections
array of objects containing the reasoning chain sections generated by the LLM"
}
}
}
]
},
"Response463397119C53_LocalJustificationInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"text": {
"type": [
"string",
"null"
],
"description": "text snippet of local justification"
}
}
},
"Response463397119C53_MessageAiOptimizationLlmResponseElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
{
"type": "object",
"properties": {
"sections": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMessageSectionInfo"
}
]
},
"description": "reasoning chain sections
array of objects containing the reasoning chain sections generated by the LLM"
}
}
}
]
},
"Response463397119C53_LlmMessageSectionInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"text": {
"type": [
"string",
"null"
],
"description": "text of the reasoning chain section
text of the reasoning chain section summarizing the model's thought process"
},
"annotations": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AnnotationInfo"
}
]
},
"description": "array of references used to generate the response
equals null if the web_search parameter is not set to true
Note: annotations may return empty even when web_search is true, as the AI will attempt to retrieve web information but may not find relevant results"
}
}
},
"Response463397119C53_AnnotationInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "the domain name or title of the quoted source"
},
"url": {
"type": [
"string",
"null"
],
"description": "redirect URL to the quoted source
contains a Vertex AI redirect that leads to the original source"
},
"direct_url": {
"type": [
"string",
"null"
],
"description": "direct URL to the quoted source
contains the original source URL that the Vertex AI redirect in the `url` field leads to"
},
"start_index": {
"type": [
"integer",
"null"
],
"description": "start of the annotation indexing"
},
"end_index": {
"type": [
"integer",
"null"
],
"description": "end of the annotation indexing"
},
"text": {
"type": [
"string",
"null"
],
"description": "text of the reasoning chain section
text of the reasoning chain section summarizing the model's thought process"
}
}
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesModelsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesModelsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesModelsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesModelsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesModelsResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model"
},
"web_search_supported": {
"type": [
"boolean",
"null"
],
"description": "web search support for the AI model
if true, the web_search parameter can be set with the AI model"
},
"task_post_supported": {
"type": [
"boolean",
"null"
],
"description": "indicates if Standard (POST-GET) data retrieval is supported
if true, you can use the Standard (POST-GET) data retrieval method with the AI model"
}
}
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTaskGetResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"description": "number of reasoning tokens
total count of tokens used to generate reasoning content"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
}
}
},
"Provider463397119C53_AiOptimizationChatGptLlmResponsesTaskPostRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;
minimum value for non-reasoning models: 16;
maximum value: 4096;
default value: 2048"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 2
default value: 0.94
Note: not supported in reasoning models"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: 0.92top_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search
optional field
when enabled, the AI model can access and cite current web information;
default value: false;
Note: refer to the Models endpoint for a list of models that support web_search;"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response
Note #2: not supported in reasoning models"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model will search the web from the country you specify;
Note: not supported in o3-mini, o1-pro, o1 models"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location
optional field
Note: not supported in o3-mini, o1-pro, o1 models"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data array of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"model_name": "gpt-4.1-mini",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmResponsesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmResponsesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "LLM model specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
]
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_AiOptimizationChatGptLlmScraperLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"model": {
"type": [
"string",
"null"
],
"description": "indicates the model version"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"search_results": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatgptSearchResult"
}
]
},
"description": "array of search results
all web search outputs the model retrieved when looking up information, including duplicates and unused entries"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources
the sources the model actually cited or relied on in its final answer"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
},
"brand_entities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptBrandEntity"
}
]
},
"description": "array of brand entities
contains information on brands mentioned in the response"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results",
"format": "int64"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results
contains types of search results (items) found in SERP.
possible item types:chat_gpt_text, chat_gpt_table, chat_gpt_navigation_list, chat_gpt_images, chat_gpt_local_businesses, chat_gpt_products"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
"description": "elements of ChatGPT results"
}
}
},
"Response463397119C53_ChatgptSearchResult": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "result URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "result domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "result title"
},
"description": {
"type": [
"string",
"null"
],
"description": "result description"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb"
}
}
},
"Response463397119C53_SourceInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "source title"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "source description"
},
"domain": {
"type": [
"string",
"null"
],
"description": "source domain in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"thumbnail": {
"type": [
"string",
"null"
],
"description": "source thumbnail"
},
"source_name": {
"type": [
"string",
"null"
],
"description": "source name"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes”
example:2019-11-15 12:57:46 +00:00"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
}
}
},
"Response463397119C53_ChatGptBrandEntity": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "name of the brand"
},
"category": {
"type": [
"string",
"null"
],
"description": "category of the brand"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "brand name in markdown format
contains brand name formatted in the markdown markup language"
},
"urls": {
"type": [
"object",
"null"
],
"description": " array of URLs and domains relevant to the brand"
}
}
},
"Response463397119C53_BaseChatGptLlmScraperElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"chat_gpt_text": "#/components/schemas/Response463397119C53_ChatGptTextElementItem",
"chat_gpt_table": "#/components/schemas/Response463397119C53_ChatGptTableElementItem",
"chat_gpt_navigation_list": "#/components/schemas/Response463397119C53_ChatGptNavigationListElementItem",
"chat_gpt_images": "#/components/schemas/Response463397119C53_ChatGptImagesElementItem",
"chat_gpt_products": "#/components/schemas/Response463397119C53_ChatGptProductsElementItem",
"chat_gpt_local_businesses": "#/components/schemas/Response463397119C53_ChatGptLocalBusinessesElementItem",
"chat_gpt_ad": "#/components/schemas/Response463397119C53_ChatGptAdElementItem"
}
}
},
"Response463397119C53_ChatGptTextElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources"
},
"brand_entities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptBrandEntity"
}
]
},
"description": "array of brand entities
contains information on brands mentioned in the text"
}
}
}
]
},
"Response463397119C53_ChatGptTableElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "text of the element"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table present in the element
the header and content of the table present in the element"
},
"brand_entities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptBrandEntity"
}
]
},
"description": "array of brand entities
contains information on brands mentioned in the text"
}
}
}
]
},
"Response463397119C53_Table": {
"type": "object",
"properties": {
"table_element": {
"type": [
"string",
"null"
],
"description": "name assigned to the table element\npossible values:\ntable_element"
},
"table_header": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "column names"
},
"table_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"description": "the content of the table\none line of the table in this element of the array"
}
}
},
"Response463397119C53_ChatGptNavigationListElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "name of the brand"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources"
}
}
}
]
},
"Response463397119C53_ChatGptImagesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GeminiImagesElement"
}
]
},
"description": "elements of ChatGPT results"
}
}
}
]
},
"Response463397119C53_GeminiImagesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"alt": {
"type": [
"string",
"null"
],
"description": "alt tag of the image"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
}
}
},
"Response463397119C53_ChatGptProductsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptProductsElement"
}
]
},
"description": "elements of ChatGPT results"
}
}
}
]
},
"Response463397119C53_ChatGptProductsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "product id"
},
"merchants": {
"type": [
"string",
"null"
],
"description": "merchant(s) offering the product"
},
"id_to_token_map": {
"type": [
"string",
"null"
],
"description": "product identifier token
Base64-encoded token containing Google Shopping product IDs associated with the product"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the corresponding local business
popularity rate based on reviews as displayed in the results"
},
"price": {
"type": [
"number",
"null"
],
"description": "product price"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency of the listed price
ISO code of the currency applied to the price"
},
"tag": {
"type": [
"string",
"null"
],
"description": "tag text"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "image URLs of the element
contains URLs leading to the images on the original resource or DataForSEO storage (in case the original source is not available)"
},
"product_ids": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptGoogleShoppingProduct"
}
]
},
"description": "Google Shopping product identifiers
array of Google Shopping product IDs associated with the product"
}
}
},
"Response463397119C53_RatingInfo": {
"properties": {
"rating_type": {
"type": [
"string",
"null"
],
"description": "the type of rating\nhere you can find the following elements: Max5, Percents, CustomMax"
},
"value": {
"type": [
"number",
"null"
],
"description": "the value of the rating",
"format": "double"
},
"votes_count": {
"type": [
"integer",
"null"
],
"description": "the amount of feedback",
"format": "int64"
},
"rating_max": {
"type": [
"integer",
"null"
],
"description": "the maximum value for a rating_type"
}
}
},
"Response463397119C53_ChatGptGoogleShoppingProduct": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"ei": {
"type": [
"string",
"null"
],
"description": "event identifier
internal event identifier used by Google"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "product identifier
can be used as a data_docid in Google Shopping API endpoints"
},
"catalog_id": {
"type": [
"string",
"null"
],
"description": "Google Shopping catalog identifier of the product
can be used as a product_id in Google Shopping API endpoints"
},
"gpcid": {
"type": [
"string",
"null"
],
"description": "Google product cluster identifier
can be used as a gid in Google Shopping API endpoints"
},
"headline_offer_docid": {
"type": [
"string",
"null"
],
"description": "document identifier of the main offer in the headline
can be used as a data_docid in Google Shopping API endpoints"
},
"image_docid": {
"type": [
"string",
"null"
],
"description": "identifier for the displayed product’s image"
},
"rds": {
"type": [
"string",
"null"
],
"description": "resource descriptor string
internal Google resource descriptor string that identifies the product within Google's Shopping index"
},
"query": {
"type": [
"string",
"null"
],
"description": "search query
search query used by ChatGPT to retrieve the product from Google Shopping"
},
"mid": {
"type": [
"string",
"null"
],
"description": "merchant identifier
identifier of the seller or merchant account in Google Shopping"
},
"pvt": {
"type": [
"string",
"null"
],
"description": "product view type
internal Google parameter that specifies the product view type used when rendering the product item"
},
"uule": {
"type": [
"string",
"null"
],
"description": "encoded location parameter
indicates the location for a search"
},
"gl": {
"type": [
"string",
"null"
],
"description": "country code
indicates the location for which search results are displayed"
},
"hl": {
"type": [
"string",
"null"
],
"description": "host language code
indicates the language in which search results are displayed"
}
}
},
"Response463397119C53_ChatGptLocalBusinessesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptLocalBusinessesElement"
}
]
},
"description": "elements of ChatGPT results"
}
}
}
]
},
"Response463397119C53_ChatGptLocalBusinessesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the local business"
},
"address": {
"type": [
"string",
"null"
],
"description": "address of the local business"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone of the local business"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "total number of reviews submitted for the local business",
"format": "int64"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the corresponding local business
popularity rate based on reviews as displayed in the results"
}
}
},
"Response463397119C53_ChatGptAdElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"is_rendered": {
"type": [
"boolean",
"null"
],
"description": " indicates whether the ad is displayed to the user
if `true`, the ad is present in the response and shown on the page
if `false`, the ad is present in the response but not displayed to the user"
},
"title": {
"type": [
"string",
"null"
],
"description": "name of the brand"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "source description"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image displayed in the ad"
},
"advertiser": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptAdAdvertiser"
}
],
"description": "information about the advertiser associated with the ad"
}
}
}
]
},
"Response463397119C53_ChatGptAdAdvertiser": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "name of the advertiser"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"favicon_url": {
"type": [
"string",
"null"
],
"description": "URL of the advertiser's favicon image"
}
}
},
"Provider463397119C53_AiOptimizationChatGptLlmScraperLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/languages
example:enn"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
to enable this parameter, force_web_search must also be enabled;
when enabled, the endpoint will return HTML data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found"
}
}
},
"Response463397119C53_HtmlItemInfo": {
"type": "object",
"properties": {
"page": {
"type": [
"integer",
"null"
],
"description": "serial number of the returned HTML page"
},
"date": {
"type": [
"string",
"null"
],
"description": "date and time when the HTML page was scanned
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"html": {
"type": [
"string",
"null"
],
"description": "HTML page"
}
}
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"model": {
"type": [
"string",
"null"
],
"description": "indicates the model version"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"search_results": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatgptSearchResult"
}
]
},
"description": "array of search results
all web search outputs the model retrieved when looking up information, including duplicates and unused entries"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources
the sources the model actually cited or relied on in its final answer"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
},
"brand_entities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChatGptBrandEntity"
}
]
},
"description": "array of brand entities
contains information on brands mentioned in the response"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results",
"format": "int64"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results
contains types of search results (items) found.
possible item types:chat_gpt_text, chat_gpt_table, chat_gpt_navigation_list, chat_gpt_images, chat_gpt_local_businesses, chat_gpt_products"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseChatGptLlmScraperElementItem"
}
]
},
"description": "items present in the element"
}
}
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationChatGptLlmScraperTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found"
}
}
},
"Provider463397119C53_AiOptimizationChatGptLlmScraperTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languagesn"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
to enable this parameter, force_web_search must also be enabled;
when enabled, the HTML endpoint will return data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_AiOptimizationClaudeLlmResponsesLiveRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 1
default value: 0.7temperature cannot be used together with top_p in the same request"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: nulltop_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location used for searching the web
optional field
possible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location used for searching the web
optional field
"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1025
Note #2: if set to true, force_web_search must be set to false
Note #3: if set to true, the temperature and top_p cannot be used"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"model_name": "claude-opus-5",
"temperature": 0.3,
"web_search": true,
"web_search_country_iso_code": "FR",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesLiveResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"description": "number of reasoning tokens
total count of tokens used to generate reasoning content"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
}
}
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesModelsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesModelsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesModelsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesModelsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesModelsResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model"
},
"web_search_supported": {
"type": [
"boolean",
"null"
],
"description": "web search support for the AI model
if true, the web_search parameter can be set with the AI model"
},
"task_post_supported": {
"type": [
"boolean",
"null"
],
"description": "indicates if Standard (POST-GET) data retrieval is supported
if true, you can use the Standard (POST-GET) data retrieval method with the AI model"
}
}
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTaskGetResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"description": "number of reasoning tokens
total count of tokens used to generate reasoning content"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
}
}
},
"Provider463397119C53_AiOptimizationClaudeLlmResponsesTaskPostRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 1
default value: 0.7temperature cannot be used together with top_p in the same request"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: nulltop_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location used for searching the web
optional field
possible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location used for searching the web
optional field
"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1025
Note #2: if set to true, force_web_search must be set to false
Note #3: if set to true, the temperature and top_p cannot be used"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationClaudeLlmResponsesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationClaudeLlmResponsesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "LLM model specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
]
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_AiOptimizationGeminiLlmResponsesLiveRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 2
default value: 1.3"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1024
Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"model_name": "gemini-2.5-flash",
"web_search": true,
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesLiveResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"description": "number of reasoning tokens
total count of tokens used to generate reasoning content"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
}
}
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesModelsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesModelsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesModelsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesModelsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesModelsResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model"
},
"web_search_supported": {
"type": [
"boolean",
"null"
],
"description": "web search support for the AI model
if true, the web_search parameter can be set with the AI model"
},
"task_post_supported": {
"type": [
"boolean",
"null"
],
"description": "indicates if Standard (POST-GET) data retrieval is supported
if true, you can use the Standard (POST-GET) data retrieval method with the AI model"
}
}
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTaskGetResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
],
"description": "number of reasoning tokens
total count of tokens used to generate reasoning content"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
}
}
},
"Provider463397119C53_AiOptimizationGeminiLlmResponsesTaskPostRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 2
default value: 1.3"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1024
Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmResponsesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmResponsesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "LLM model specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
]
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Provider463397119C53_AiOptimizationGeminiLlmScraperLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example: English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example: enn"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"model": {
"type": [
"string",
"null"
],
"description": "indicates the model version"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources
the sources the model actually cited or relied on in its final answer"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results",
"format": "int64"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results
contains types of search results (items) found in SERP.
possible item types:gemini_text, gemini_table, gemini_images"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseGeminiLlmScraperElementItem"
}
]
},
"description": "elements of Gemini results"
}
}
},
"Response463397119C53_BaseGeminiLlmScraperElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"gemini_text": "#/components/schemas/Response463397119C53_GeminiTextElementItem",
"gemini_table": "#/components/schemas/Response463397119C53_GeminiTableElementItem",
"gemini_images": "#/components/schemas/Response463397119C53_GeminiImagesElementItem"
}
}
},
"Response463397119C53_GeminiTextElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseGeminiLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"original_text": {
"type": [
"string",
"null"
],
"description": "unformatted text content of the element"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources"
}
}
}
]
},
"Response463397119C53_GeminiTableElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseGeminiLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"original_text": {
"type": [
"string",
"null"
],
"description": "unformatted text content of the element"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table present in the element
the header and content of the table present in the element"
}
}
}
]
},
"Response463397119C53_GeminiImagesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseGeminiLlmScraperElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GeminiImagesElement"
}
]
},
"description": "elements of Gemini results"
}
}
}
]
},
"Provider463397119C53_AiOptimizationGeminiLlmScraperLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:enn"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
when enabled, the endpoint will return HTML data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found"
}
}
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:\"location_code\": 9041134,
\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",
\"location_code_parent\": 20044location_code_parent corresponds to:\"location_code\": 20044,"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
\"location_name\": \"Lower Austria,Austria\"
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"model": {
"type": [
"string",
"null"
],
"description": "indicates the model version"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SourceInfo"
}
]
},
"description": "array of sources
the sources the model actually cited or relied on in its final answer"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results",
"format": "int64"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results
contains types of search results (items) found in SERP.
possible item types:gemini_text, gemini_table, gemini_images"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseGeminiLlmScraperElementItem"
}
]
},
"description": "items present in the element"
}
}
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found"
}
}
},
"Provider463397119C53_AiOptimizationGeminiLlmScraperTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:en"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
when enabled, the HTML endpoint will return data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationGeminiLlmScraperTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationGeminiLlmScraperTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"function": {
"type": [
"string",
"null"
],
"description": "search engine function
example: llm_scraper"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Advanced task
if the Advanced function is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the HTML task
if the HTML function is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsAvailableFiltersResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsAvailableFiltersTaskInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsAvailableFiltersTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsAvailableFiltersResultInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsAvailableFiltersResultInfo": {
"type": "object",
"properties": {
"search": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"search_mentions": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"target_metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"multi_target_metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_domains": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_pages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_brands": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_brand_categories": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"target_metrics_lite": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_domains_lite": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_pages_lite": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_brands_lite": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"top_mentioned_brand_categories_lite": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsHistoricalLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "start date of the time range
optional field
minimal value 2025-08-01
date format \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "end date of the time range
optional field
Note value specified in date_from cannot exceed the value in date_to
date format \"yyyy-mm-dd\""
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "es",
"location_code": 2840,
"platform": "google",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
]
}
]
},
"Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement": {
"type": "object",
"properties": {
"search_scope": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any"
},
"search_filter": {
"type": [
"string",
"null"
],
"description": "target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include"
}
},
"discriminator": {
"propertyName": "type",
"mapping": {
"domain": "#/components/schemas/Provider463397119C53_AiOptimizationLLmMentionsDomainElement",
"keyword": "#/components/schemas/Provider463397119C53_AiOptimizationLLmMentionsKeywordElement"
}
}
},
"Provider463397119C53_AiOptimizationLLmMentionsDomainElement": {
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "target domain\nrequired field if you don’t specify keyword\na domain should be specified without https:// and www."
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target domain will be included in the search\noptional field\nif set to true, the subdomains will be included in the search\ndefault value: false"
}
}
}
]
},
"Provider463397119C53_AiOptimizationLLmMentionsKeywordElement": {
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
{
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "target keyword\nrequired field if you don’t specify domain\nyou can specify up to 2000 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”\nlearn more about rules and limitations of keyword and keywords fields in"
},
"match_type": {
"type": [
"string",
"null"
],
"description": "target keyword match type\ndefines how the specified keyword is matched\noptional field\npossible values:\nword_match – full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for “light” will return results with “light bulb”, “light switch”);\npartial_match – substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for “light” will return results with “lighting”, “highlight”);\ndefault value: word_match"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of resuts returned in the items array
",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveItem"
}
]
},
"description": "array of historical mention metrics
contains objects with historical mention metrics for the specified target
each object contains aggregated mentions metrics for one calendar month"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsHistoricalLiveItem": {
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "year"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "aggregated mentions metrics for the given month of a year"
}
}
},
"Response463397119C53_AggregatedMetricsInfoTotalInfo": {
"type": "object",
"properties": {
"mentions": {
"type": [
"integer",
"null"
],
"description": "total LLM mentions count
the number of times the target keyword or domain were mentioned in relation to this specific grouping key"
},
"ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "aggregated AI search volume for mentions within this grouping
learn more about this metric here",
"format": "int64"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsLocationsAndLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsLocationsAndLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsLocationsAndLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsLocationsAndLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsLocationsAndLanguagesResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"available_languages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ResultAvailableLanguages"
}
]
},
"description": "supported languages
contains the languages which are supported for a specific location"
}
}
},
"Response463397119C53_ResultAvailableLanguages": {
"type": "object",
"properties": {
"available_platforms": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "supported LLM platforms
contains the sources of data supported for a specific location and language combination
only google and chat_gpt are currently available"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
},
"responses_count": {
"type": [
"integer",
"null"
],
"description": "number of LLM responses
the number of LLM responses available in the database for the certain location and language parameters",
"format": "int64"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_AiOptimizationLLmMentionsMultiTargetMetricsRequestInfo"
}
]
}
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned objects
optional field100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000, use the search_after_token if you would like to offset more results"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domain
minimum value: 1
maximum value: 10
default value: 5"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "google",
"targets": [
{
"key": "chat_gpt",
"target": [
{
"keyword": "chat gpt"
}
]
},
{
"key": "claude",
"target": [
{
"keyword": "claude"
}
]
},
{
"key": "gemini",
"target": [
{
"keyword": "gemini"
}
]
},
{
"key": "perplexity",
"target": [
{
"keyword": "perplexity",
"search_filter": "include"
}
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 5
}
]
},
"Provider463397119C53_AiOptimizationLLmMentionsMultiTargetMetricsRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
}
},
"key": {
"type": [
"string",
"null"
],
"description": "key for grouping the results\nrequired field\ngroups results for comparison and serves as a label for the group;\nyou can specify up to 250 characters in the key field"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions dataoffset specified in the request"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMentionsAggregatedMetricsInfo"
}
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all LLM mentions that match at least one target specified in the request"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveItem"
}
]
},
"description": "contains relevant mentions data"
}
}
},
"Response463397119C53_LlmMentionsAggregatedMetricsInfo": {
"type": "object",
"properties": {
"location": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "location-based grouping
array of objects containing mention metrics segmented by geographical location"
},
"language": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "language-based grouping
array of objects containing mention metrics segmented by content language"
},
"platform": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "platform-based grouping
array of group elements containing mention metrics segmented by AI platform"
},
"sources_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top source domains relevant to the target
array of objects containing data on top domains that are cited as sources in LLM responses
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top search results domains relevant to the target
array of objects containing data on top domains that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_title": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity titles that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity categories that appear in search results related to LLM queries
Note: available only for chat_gpt"
},
"total": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all found domains"
}
}
},
"Response463397119C53_AggregatedMetricsItemInfo": {
"type": "object",
"properties": {
"key": {
"type": [
"string",
"null"
],
"description": "grouping identifier
the specific identifier for the grouping dimension"
},
"mentions": {
"type": [
"integer",
"null"
],
"description": "total LLM mentions count
the number of times the target keyword or domain were mentioned in relation to this specific grouping key"
},
"ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "aggregated AI search volume for mentions within this grouping
learn more about this metric here",
"format": "int64"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsMultiTargetMetricsLiveItem": {
"type": "object",
"properties": {
"key": {
"type": [
"string",
"null"
],
"description": "grouping key
the specific identifier for the group dimension"
},
"location": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "location-based grouping
array of objects containing mention metrics segmented by geographical location"
},
"language": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "language-based grouping
array of objects containing mention metrics segmented by content language"
},
"platform": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "platform-based grouping
array of group elements containing mention metrics segmented by AI platform"
},
"sources_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top source domains relevant to the target
array of objects containing data on top domains that are cited as sources in LLM responses
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top search results domains relevant to the target
array of objects containing data on top domains that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_title": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity titles that appear in search results related to LLM queries
Note: available only for chat_gpt"
},
"brand_entities_category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity categories that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"total": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "data on total mentions and search volume for the target"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000, use the search_after_token if you would like to offset more results"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 1000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned objects
optional field100
maximum value: 1000"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"filters": [
[
"ai_search_volume",
">",
1000
]
],
"order_by": [
"ai_search_volume,desc"
],
"offset": 0,
"limit": 3
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
]
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
by specifying the unique search_after_token when setting a new task, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveItem"
}
]
},
"description": "contains relevant mentions data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsSearchMentionsLiveItem": {
"type": "object",
"properties": {
"platform": {
"type": [
"string",
"null"
],
"description": "platform received in a POST array"
},
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model from which the data was retrieved
Note: for the google platform type, the value is always google_ai_overview"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"question": {
"type": [
"string",
"null"
],
"description": "relevant question"
},
"answer": {
"type": [
"string",
"null"
],
"description": "relevant answer in markdown format
content of the result formatted in the markdown markup language"
},
"sources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Sources"
}
]
},
"description": "array of sources
the sources the model cited or relied on in its final answer
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchResults"
}
]
},
"description": "array of search results
all web search outputs the model retrieved when looking up information, including duplicates and unused entries
Note: available only for chat_gpt"
},
"ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "current AI search volume rate of a keyword
learn more about this metric here",
"format": "int64"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly AI search volume rates
array of objects with AI search volume rates in a certain month of a year"
},
"first_response_at": {
"type": [
"string",
"null"
],
"description": "date and time when the response data was first recorded
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2025-10-21 06:25:30 +00:00"
},
"last_response_at": {
"type": [
"string",
"null"
],
"description": "date and time when the response data was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2025-10-21 06:25:30 +00:00"
},
"brand_entities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BrandEntities"
}
]
},
"description": "array of brand entities
contains information on brands mentioned in the response
Note: available only for chat_gpt"
},
"fan_out_queries": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response
Note: available only for chat_gpt"
},
"is_web_search_based": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the response was generated using web search results
if true, the model retrieved live web search results to produce the response
if false, the response was generated from the model's internal knowledge"
}
}
},
"Response463397119C53_Sources": {
"type": "object",
"properties": {
"snippet": {
"type": [
"string",
"null"
],
"description": "source description"
},
"source_name": {
"type": [
"string",
"null"
],
"description": "source name"
},
"thumbnail": {
"type": [
"string",
"null"
],
"description": "source thumbnail"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
content of the result formatted in the markdown markup language"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank in the results"
},
"title": {
"type": [
"string",
"null"
],
"description": "source title"
},
"domain": {
"type": [
"string",
"null"
],
"description": "source domain"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_SearchResults": {
"type": "object",
"properties": {
"description": {
"type": [
"string",
"null"
],
"description": "result description"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank in the results"
},
"title": {
"type": [
"string",
"null"
],
"description": "source title"
},
"domain": {
"type": [
"string",
"null"
],
"description": "source domain"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_MonthlySearchesInfo": {
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "year"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate"
}
}
},
"Response463397119C53_BrandEntities": {
"type": "object",
"properties": {
"rank": {
"type": [
"integer",
"null"
],
"description": "rank in the results"
},
"title": {
"type": [
"string",
"null"
],
"description": "source title"
},
"category": {
"type": [
"string",
"null"
],
"description": "category of the brand"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTargetMetricsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domain
minimum value: 1
maximum value: 10
default value: 10"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 10
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant to the request
in this case, always equals 0",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "the number of mentions objects that are omitted in the items array
in this case, always equals 0"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array
in this case, always equals 0",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMentionsAggregatedMetricsInfo"
}
],
"description": "aggregated mentions metrics
contains aggregated LLM mention metrics across all found domains, grouped by various dimensions"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "individual target results
in this case, equals null"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "es",
"location_code": 2840,
"platform": "google",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 6
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "the number of mentions objects that are omitted in the items array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"description": "aggregated mentions metrics
in this case, always returns null"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveItem"
}
]
},
"description": "array of aggregated mentions metrics
contains objects with aggregated mention metrics for the specified target"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTargetMetricsLiteLiveItem": {
"type": "object",
"properties": {
"location": {
"type": [
"integer",
"null"
],
"description": "location identifier
location of aggregated metrics"
},
"language": {
"type": [
"string",
"null"
],
"description": "language identifier
language of aggregated metrics"
},
"platform": {
"type": [
"string",
"null"
],
"description": "LLM platform identifiers
LLM platform of aggregated metrics"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "LLM metrics
metrics aggregated by specific parameters and respective identifiers"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"date_from": {
"type": "string",
"description": "start date of the time range
required field
minimal value: 2025-08-01
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": "string",
"description": "end date of the time range
required field
Note:the value specified in date_from cannot exceed the value in date_to
date format: \"yyyy-mm-dd\""
},
"group_range": {
"type": "string",
"description": "timeseries delta range
required field
possible values:day, week, month, year"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"date_from": "2025-08-01",
"date_to": "2025-12-01",
"group_range": "month"
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveItem"
}
]
},
"description": "contains relevant LLM mentions timeseries data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesDeltaLiveItem": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"description": "date timestamp
date format: \"yyyy-mm-dd\""
},
"delta_mentions": {
"type": [
"integer",
"null"
],
"description": "LLM mentions count delta
the difference in mentions between the current timestamp and the previous one"
},
"delta_ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "LLM mentions count delta
the difference in ai_search_volume values between the current timestamp and the previous one
learn more about this metric here",
"format": "int64"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"date_from": {
"type": "string",
"description": "start date of the time range
required field
minimal value: 2025-08-01
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": "string",
"description": "end date of the time range
required field
Note:the value specified in date_from cannot exceed the value in date_to
date format: \"yyyy-mm-dd\""
},
"group_range": {
"type": "string",
"description": "timeseries range
required field
possible values:day, week, month, year"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "serp",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"date_from": "2025-08-01",
"date_to": "2025-12-01",
"group_range": "month"
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveItem"
}
]
},
"description": "contains relevant LLM mentions timeseries data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTimeseriesNewLostLiveItem": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"description": "date timestamp
date format: \"yyyy-mm-dd\""
},
"new_mentions": {
"type": [
"integer",
"null"
],
"description": "new LLM mentions
indicates the LLM responses that contain the target at the date_to timestamp, did not contain it at the date_from timestamp"
},
"lost_mentions": {
"type": [
"integer",
"null"
],
"description": "lost LLM mentions
indicates the LLM responses that contained the specified target at the date_from timestamp, do not contain it at the date_to timestamp"
},
"new_ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "ai_search_volume increment
indicates the increase of ai_search_volume values between the current timestamp and the previous one
learn more about this metric here",
"format": "int64"
},
"lost_ai_search_volume": {
"type": [
"integer",
"null"
],
"description": "ai_search_volume decrement
indicates the decrease of ai_search_volume values between the current timestamp and the previous one
learn more about this metric here",
"format": "int64"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand_categories to include in the response
optional field
if specified, only the listed brand categories will be returned in the items array
example:\"include_brand_categories\": [\"business\"]"
},
"exclude_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand categories to exclude from the response
optional field
if specified, the listed brand categories will be omitted from the items array
example:\"exclude_brand_categories\": [\"business\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "the number of mentions objects that are omitted in the items array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMentionsAggregatedMetricsInfo"
}
],
"description": "aggregated mentions metrics
contains aggregated LLM mention metrics across all found brand categories, grouped by various dimensions"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveItem"
}
]
},
"description": "individual brand categories results
array containing detailed mention metrics for each of the found brand categories"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiveItem": {
"type": "object",
"properties": {
"brand_category": {
"type": [
"string",
"null"
],
"description": "brand category
brand category found in LLM mentions for the specified target"
},
"location": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "location-based grouping
array of objects containing mention metrics segmented by geographical location"
},
"language": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "language-based grouping
array of objects containing mention metrics segmented by content language"
},
"platform": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "platform-based grouping
array of group elements containing mention metrics segmented by AI platform"
},
"sources_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top source domains relevant to the target
array of objects containing data on top domains that are cited as sources in LLM responses
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top search results domains relevant to the target
array of objects containing data on top domains that appear in search results related to LLM queries"
},
"brand_entities_title": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity titles that appear in search results related to LLM queries"
},
"brand_entities_category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity categories that appear in search results related to LLM queries"
},
"total": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all dimensions"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand categories to include in the response
optional field
if specified, only the listed brand categories will be returned in the items array
example:[\"company\",\"insurance\"]"
},
"exclude_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand categories to exclude from the response
optional field
if specified, the listed brand categories will be omitted from the items array
example:[\"company\",\"insurance\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions dataoffset specified in the request"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensionsin this case, the value will be null"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveItem"
}
]
},
"description": "contains relevant mentions data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandCategoriesLiteLiveItem": {
"type": "object",
"properties": {
"brand_category": {
"type": [
"string",
"null"
],
"description": "brand category
brand category identifier of aggregated metrics"
},
"location": {
"type": [
"integer",
"null"
],
"description": "location identifier
location of aggregated metrics"
},
"language": {
"type": [
"string",
"null"
],
"description": "language identifier
language of aggregated metrics"
},
"platform": {
"type": [
"string",
"null"
],
"description": "LLM platform identifiers
LLM platform of aggregated metrics"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "LLM metrics
metrics aggregated by specific parameters and respective identifiers"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to include in the response
optional field
if specified, only the listed brands will be returned in the items array
example:\"include_brands\": [\"Audi\"]"
},
"exclude_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to exclude from the response
optional field
if specified, the listed brands will be omitted from the items array
example:\"exclude_brands\": [\"Audi\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "the number of mentions objects that are omitted in the items array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMentionsAggregatedMetricsInfo"
}
],
"description": "aggregated mentions metrics
contains aggregated LLM mention metrics across all found brands, grouped by various dimensions"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveItem"
}
]
},
"description": "individual domain results
array containing detailed mention metrics for each of the found top domains"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiveItem": {
"type": "object",
"properties": {
"brand": {
"type": [
"string",
"null"
],
"description": "brand name
name of the brand found in LLM mentions for the specified target"
},
"location": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "location-based grouping
array of objects containing mention metrics segmented by geographical location"
},
"language": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "language-based grouping
array of objects containing mention metrics segmented by content language"
},
"platform": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "platform-based grouping
array of group elements containing mention metrics segmented by AI platform"
},
"sources_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top source domains relevant to the target
array of objects containing data on top domains that are cited as sources in LLM responses
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top search results domains relevant to the target
array of objects containing data on top domains that appear in search results related to LLM queries"
},
"brand_entities_title": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity titles that appear in search results related to LLM queries"
},
"brand_entities_category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity categories that appear in search results related to LLM queries"
},
"total": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all dimensions"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\", 1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to include in the response
optional field
if specified, only the listed brands will be returned in the items array
example:[\"BMW\",\"Audi\"]"
},
"exclude_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to exclude from the response
optional field
if specified, the listed brands will be omitted from the items array
example:[\"BMW\",\"Audi\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions dataoffset specified in the reqest"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensionsin this case, the value will be null"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveItem"
}
]
},
"description": "contains relevant mentions data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedBrandsLiteLiveItem": {
"type": "object",
"properties": {
"brand": {
"type": [
"string",
"null"
],
"description": "brand name
brand identifier of aggregated metrics"
},
"location": {
"type": [
"integer",
"null"
],
"description": "location identifier
location of aggregated metrics"
},
"language": {
"type": [
"string",
"null"
],
"description": "language identifier
language of aggregated metrics"
},
"platform": {
"type": [
"string",
"null"
],
"description": "LLM platform identifiers
LLM platform of aggregated metrics"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "LLM metrics
metrics aggregated by specific parameters and respective identifiers"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources
Note:if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to include in the response
optional field
if specified, only the listed domains will be returned in the items array
example:\"include_domains\": [\"en.wikipedia.org\"]"
},
"exclude_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to exclude from the response
optional field
if specified, the listed domains will be omitted from the items array
example:\"exclude_domains\": [\"en.wikipedia.org\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "the number of mentions objects that are omitted in the items array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMentionsAggregatedMetricsInfo"
}
],
"description": "aggregated mentions metrics
contains aggregated LLM mention metrics across all found domains, grouped by various dimensions"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveItem"
}
]
},
"description": "individual domain results
array containing detailed mention metrics for each of the found top domains"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiveItem": {
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain name
the domain name of the website found in LLM mentions for the specified target"
},
"location": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "location-based grouping
array of objects containing mention metrics segmented by geographical location"
},
"language": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "language-based grouping
array of objects containing mention metrics segmented by content language"
},
"platform": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "platform-based grouping
array of group elements containing mention metrics segmented by AI platform"
},
"sources_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top source domains relevant to the target
array of objects containing data on top domains that are cited as sources in LLM responses
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top search results domains relevant to the target
array of objects containing data on top domains that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_title": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity titles that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity categories that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"total": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all dimensions"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en onlyn"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources;
Note: if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to include in the response
optional field
if specified, only the listed domains will be returned in the items array
example:[\"dataforseo.com\",\"seoinsider.com\"]"
},
"exclude_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to exclude from the response
optional field
if specified, the listed domains will be omitted from the items array
example:[\"google.com\",\"bing.com\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions dataoffset specified in the reqest"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensionsin this case, the value will be null"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveItem"
}
]
},
"description": "contains relevant mentions data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedDomainsLiteLiveItem": {
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain name
domain of aggregated metrics"
},
"location": {
"type": [
"integer",
"null"
],
"description": "location identifier
location of aggregated metrics"
},
"language": {
"type": [
"string",
"null"
],
"description": "language identifier
language of aggregated metrics"
},
"platform": {
"type": [
"string",
"null"
],
"description": "LLM platform identifiers
LLM platform of aggregated metrics"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "LLM metrics
metrics aggregated by specific parameters and respective identifiers"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources;
Note:if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of pages to include in the response
optional field
if specified, only the listed pages will be returned in the items array
example:\"include_pages\": [\"https://example.page/\"]"
},
"exclude_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of pages to exclude from the response
optional field
if specified, the listed pages will be omitted from the items array
example:\"exclude_pages\": [\"https://example.page/\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "the number of mentions objects that are omitted in the items array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LlmMentionsAggregatedMetricsInfo"
}
],
"description": "aggregated mentions metrics
contains aggregated LLM mention metrics across all found pages, grouped by various dimensions"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveItem"
}
]
},
"description": "individual page results
array containing detailed mention metrics for each of the found top mentioned pages"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiveItem": {
"type": "object",
"properties": {
"page": {
"type": [
"string",
"null"
],
"description": "URL of a found page
the URL of a page found in LLM mentions for the specified target"
},
"location": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "location-based grouping
array of objects containing mention metrics segmented by geographical location"
},
"language": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "language-based grouping
array of objects containing mention metrics segmented by content language"
},
"platform": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "platform-based grouping
array of group elements containing mention metrics segmented by AI platform"
},
"sources_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top source domains relevant to the target
array of objects containing data on top domains that are cited as sources in LLM responses
learn more about the sources and how to retrieve LLM citation data at our Help Center"
},
"search_results_domain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "found top search results domains relevant to the target
array of objects containing data on top domains that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_title": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity titles that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"brand_entities_category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsItemInfo"
}
]
},
"description": "data on brand entities relevant to the target
array of objects containing data on brand entity categories that appear in search results related to LLM queries;
Note: available only for chat_gpt"
},
"total": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all dimensions"
}
}
},
"Provider463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_BaseAiOptimizationLLmMentionsTargetElement"
}
]
},
"description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources; ;
Note: if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of page URLs to include in the response
optional field
if specified, only the listed pages will be returned in the items array
example:
`[\"https://dataforseo.com/apis/ai-optimization-api/llm-mentions-api\", \"https://dataforseo.com/apis/ai-optimization-api\"]`"
},
"exclude_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of page URLs to exclude from the response
optional field
if specified, the listed pages will be omitted from the items array
example:
`[\"https://dataforseo.com/apis/ai-optimization-api/llm-mentions-api\", \"https://dataforseo.com/apis/ai-optimization-api\"]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions dataoffset specified in the request"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"aggregated_metrics": {
"type": [
"object",
"null"
],
"description": "aggregated mentions metrics summary
contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensionsin this case, the value will be null"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveItem"
}
]
},
"description": "contains relevant mentions data"
}
}
},
"Response463397119C53_AiOptimizationLlmMentionsTopMentionedPagesLiteLiveItem": {
"type": "object",
"properties": {
"page": {
"type": [
"string",
"null"
],
"description": "page URL
page identifier of aggregated metrics"
},
"location": {
"type": [
"integer",
"null"
],
"description": "location identifier
location of aggregated metrics"
},
"language": {
"type": [
"string",
"null"
],
"description": "language identifier
language of aggregated metrics"
},
"platform": {
"type": [
"string",
"null"
],
"description": "LLM platform identifiers
LLM platform of aggregated metrics"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AggregatedMetricsInfoTotalInfo"
}
],
"description": "LLM metrics
metrics aggregated by specific parameters and respective identifiers"
}
}
},
"Provider463397119C53_AiOptimizationPerplexityLlmResponsesLiveRequestInfo": {
"type": "object",
"properties": {
"user_prompt": {
"type": "string",
"description": "prompt for the AI model
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
you can receive the list of available LLM models by making a separate request to the following endpoint: https://api.dataforseo.com/v3/ai_optimization/perplexity/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1
maximum value: 4096;
default value: 2048;
Note: if the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 1.9
default value: 0.77"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "country code for web search localization
optional field
specify the country ISO code to get localized web search results
Note: available only for Perplexity Sonar models
example: US"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_LlmMessageChainItem"
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"web_search_country_iso_code": "FR",
"model_name": "sonar",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
},
"Response463397119C53_AiOptimizationPerplexityLlmResponsesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationPerplexityLlmResponsesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationPerplexityLlmResponsesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationPerplexityLlmResponsesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationPerplexityLlmResponsesLiveResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model used"
},
"input_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the input
total count of tokens processed"
},
"output_tokens": {
"type": [
"integer",
"null"
],
"description": "number of tokens in the output
total count of tokens generated in the AI response"
},
"reasoning_tokens": {
"type": [
"integer",
"null"
]
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "indicates if web search was used
Note: web search is enabled by default in Perplexity Sonar models"
},
"money_spent": {
"type": [
"number",
"null"
],
"description": "cost of AI tokens, USD
the price charged by the third-party AI model provider for according to its Pricing"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MessageAiOptimizationLlmResponseElementItem"
}
]
},
"description": "array of response items
contains structured AI response data"
},
"fan_out_queries": {
"type": [
"object",
"null"
],
"description": "array of fan-out queries
contains related search queries derived from the main query to provide a more comprehensive response"
}
}
},
"Response463397119C53_AiOptimizationPerplexityLlmResponsesModelsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationPerplexityLlmResponsesModelsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AiOptimizationPerplexityLlmResponsesModelsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationPerplexityLlmResponsesModelsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AiOptimizationPerplexityLlmResponsesModelsResultInfo": {
"type": "object",
"properties": {
"model_name": {
"type": [
"string",
"null"
],
"description": "name of the AI model"
},
"web_search_supported": {
"type": [
"boolean",
"null"
],
"description": "web search support for the AI model
if true, the web_search parameter can be set with the AI model"
},
"task_post_supported": {
"type": [
"boolean",
"null"
],
"description": "indicates if Standard (POST-GET) data retrieval is supported
if true, you can use the Standard (POST-GET) data retrieval method with the AI model"
}
}
},
"Response463397119C53_AppDataAppleAppInfoTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppInfoTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppInfoTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppInfoTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppInfoTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "application id received in a POST request"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppStoreInfoOrganic"
}
]
},
"description": "found app info"
}
}
},
"Response463397119C53_AppStoreInfoOrganic": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed apps
absolute position among all apps on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values: left"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "ID of the app"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the app"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the app page on App Store"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL to the app icon"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the app"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews of the app",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "average rating of the app"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price of the app"
},
"is_free": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the app is free"
},
"main_category": {
"type": [
"string",
"null"
],
"description": "main category/genre of the app"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "all relevant categories/genres of the app
Note: this field returns only one relevant category in the array"
},
"languages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "languages supported in the app
Note: this field returns only one supported language in the array"
},
"advisories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "age rating and age-based content advisories"
},
"developer": {
"type": [
"string",
"null"
],
"description": "name of the app developer"
},
"developer_id": {
"type": [
"string",
"null"
],
"description": "ID of the app developer"
},
"developer_url": {
"type": [
"string",
"null"
],
"description": "URL to the developer page on App Store"
},
"version": {
"type": [
"string",
"null"
],
"description": "current version of the app"
},
"minimum_os_version": {
"type": [
"string",
"null"
],
"description": "minimum OS version required to install the app"
},
"size": {
"type": [
"string",
"null"
],
"description": "size of the app"
},
"released_date": {
"type": [
"string",
"null"
],
"description": "date and time when the app was released
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00
Note: this field is deprecated and always returns null"
},
"last_update_date": {
"type": [
"string",
"null"
],
"description": "date and time when the app was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"update_notes": {
"type": [
"string",
"null"
],
"description": "update notes
contains the latest update notes from the developer"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "app images
contains URLs to the images used on the app page on App Store"
},
"similar_apps": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppsInfo"
}
]
},
"description": "similar apps
displays apps similar to the app in a POST request"
},
"more_apps_by_developer": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppsInfo"
}
]
},
"description": "similar apps
information about apps built by the same developer"
}
}
},
"Response463397119C53_PriceInfo": {
"type": "object",
"properties": {
"current": {
"type": [
"number",
"null"
],
"description": "current price\nindicates the current price of the product or service featured in the result",
"format": "double"
},
"regular": {
"type": [
"number",
"null"
],
"description": "regular price\nindicates the regular price of the product or service with no discounts applied",
"format": "double"
},
"max_value": {
"type": [
"number",
"null"
],
"description": "the maximum price\nthe maximum price of the product or service as indicated in the result",
"format": "double"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency of the listed price\nISO code of the currency applied to the price"
},
"is_price_range": {
"type": [
"boolean",
"null"
],
"description": "price is provided as a range\nindicates whether a price is provided in a range"
},
"displayed_price": {
"type": [
"string",
"null"
],
"description": "price string in the result\nraw price string as provided in the result"
}
}
},
"Response463397119C53_AppsInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "ID of the app"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the app page on Google Play"
}
}
},
"Provider463397119C53_AppDataAppleAppInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL `https://apps.apple.com/us/app/id835599320`
the id is `835599320`"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/locations`
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/locations`
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/languages`
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/languages`
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
`http://your-server.com/postbackscript?id=$id`
`http://your-server.com/postbackscript?id=$id&tag=$tag`
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
`http://your-server.com/pingscript?id=$id`
`http://your-server.com/pingscript?id=$id&tag=$tag`
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "app collection received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
in this case, the value will be null"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of app items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppStoreSearchOrganic"
}
]
},
"description": "found apps
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_AppStoreSearchOrganic": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the app page on App Store"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL to the app icon"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews of the app",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "average rating of the app"
},
"is_free": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the app is free"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing information for the app"
}
}
},
"Provider463397119C53_AppDataAppleAppListTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_collection": {
"type": "string",
"description": "app collectionrequired fieldapp collection on App Store from which apps will be collected;you can specify the following values:top_free_ios, top_paid_ios, top_grossing_ios, new_ios, new_free_ios, new_paid_ios"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locationsexample:West Los Angeles,California,United States"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locationsexample:9061121"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine languagerequired field if you don't specify language_codeif you use this field, you don't need to specify language_codeyou can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languagesexample:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "\"search engine language coderequired field if you don't specify language_nameif you use this field, you don't need to specify language_nameyou can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languagesexample:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priorityoptional fieldcan take the following values:1 – normal execution priority (set by default)2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depthoptional fieldnumber of apps to be returned from the App Store SERP;default value: 100maximum value: 100Your account will be billed per each SERP containing up to 100 results; The cost can be calculated on the Pricing page."
},
"app_category": {
"type": [
"string",
"null"
],
"description": "application category on the App Storeoptional fieldyou can filter the results by app category;example:lifestyle;you can review the full list of available categories here or by making a separate request to https://api.dataforseo.com/v3/app_data/apple/categories"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
],
"description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23learn more on our Help Center"
}
},
"example": [
{
"app_collection": "top_free_ios",
"location_code": 2840,
"language_code": "en",
"app_category": "games"
}
]
},
"Response463397119C53_AppDataAppleAppListTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of resultsin this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListingsCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListingsCategoriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListingsCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListingsCategoriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListingsCategoriesResultInfo": {
"type": "object",
"properties": {
"category": {
"type": [
"string",
"null"
],
"description": "name of the supported app category"
},
"count": {
"type": [
"integer",
"null"
],
"description": "number of app listings that make up the supported app category",
"format": "int64"
}
}
},
"Provider463397119C53_AppDataAppleAppListingsSearchLiveRequestInfo": {
"type": "object",
"properties": {
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "app categories
optional field
the categories you specify are used to search for app listings;
you can get the full list of available app listing categories by this link
you can specify up to 10 categories"
},
"description": {
"type": [
"string",
"null"
],
"description": "keyword in the app's description
optional field
keywords that occur in the description of the app;
can contain up to 200 characters"
},
"title": {
"type": [
"string",
"null"
],
"description": "keyword in the app's title
optional field
keywords that occur in the title of the app;
can contain up to 200 characters"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rating.value\",\">\",3]https://api.dataforseo.com/v3/app_data/apple/app_listings/available_filtersn"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"item.rating.value,desc\"]
you should use a comma to separate several sorting rules
example:[\"item.rating.value,desc\",\"item.rating.value,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned apps
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"title": "vpn",
"description": "vpn",
"categories": [
"Utilities"
],
"order_by": [
"item.rating.value,desc"
],
"filters": [
[
"item.rating.value",
">",
4.5
]
],
"limit": 10
}
]
},
"Response463397119C53_AppDataAppleAppListingsSearchLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListingsSearchLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListingsSearchLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListingsSearchLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppListingsSearchLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "the total number of relevant results in the database",
"format": "int64"
},
"count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
you can use this parameter in the POST request to avoid timeouts while trying to obtain over 100,000 results in a single request"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppListingsSearchLiveItem"
}
]
},
"description": "array of apps and related data"
}
}
},
"Response463397119C53_AppDataAppleAppListingsSearchLiveItem": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "ID of the returned app"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"time_update": {
"type": [
"string",
"null"
],
"description": "date and time when SERP data was last updated
in the ISO 8601 format: “YYYY-MM-DDThh:mm:ss.sssssssZ”
example:2023-05-23 10:16:19 +00:00"
},
"item": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppStoreInfoOrganic"
}
],
"description": "detailed information about the app"
}
}
},
"Response463397119C53_AppDataAppleAppReviewsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppReviewsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppReviewsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppReviewsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppReviewsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "application id received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app
title of the application for which the reviews are collected"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the app
rating of the application for which the reviews are collected"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews
in this case, the value will be null as App Store does not indicate the total number of app reviews",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppStoreReviewsSearch"
}
]
},
"description": "found reviews"
}
}
},
"Response463397119C53_AppStoreReviewsSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: left"
},
"version": {
"type": [
"string",
"null"
],
"description": "version of the app
version of the app for which the review is submitted"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the review was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"id": {
"type": [
"string",
"null"
],
"description": "id of the review"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the review"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "content of the review"
},
"user_profile": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppUserProfileInfo"
}
],
"description": "user profile of the reviewer"
}
}
},
"Response463397119C53_AppUserProfileInfo": {
"type": "object",
"properties": {
"profile_name": {
"type": [
"string",
"null"
],
"description": "profile name of the reviewer"
},
"profile_image_url": {
"type": [
"string",
"null"
],
"description": "URL to the reviewer's profile image"
}
}
},
"Provider463397119C53_AppDataAppleAppReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:enn"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 25, because our system processes 25 reviews in a row;
default value: 25;
maximum value: 500;
Setting depth above 25 may result in additional charges if the search engine returns more than 25 results;
The cost can be calculated on the Pricing page."
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:most_recent — sort by the most recent reviews;most_helpful — sort by the most relevant reviews;
default rule: most_helpful"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppSearchesTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppSearchesTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppSearchesTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleAppSearchesTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleAppSearchesTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST request"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
in this case, the value will be null"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppStoreSearchOrganic"
}
]
},
"description": "found apps"
}
}
},
"Provider463397119C53_AppDataAppleAppSearchesTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if language_name is not specified
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:enn"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be returned from the App Store SERP;
we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row;
default value: 100
maximum value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataAppleCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleCategoriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleCategoriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleCategoriesResultInfo": {
"type": "object",
"properties": {
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains full list of supported app categories"
}
}
},
"Response463397119C53_AppDataAppleLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_AppDataAppleLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataAppleLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataAppleLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataAppleLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_name_parent": {
"type": [
"string",
"null"
],
"description": "the name of the superordinate location\nexample:\n\"location_code\": 1006473,\n\"location_name\": \"Altrincham,England,United Kingdom\",\n\"location_name_parent\": \"England,United Kingdom\", where location_name_parent corresponds to:\n\"location_code\": 20339,\n\"location_name\": \"England,United Kingdom\"\nnote: Apple App Data API currently supports countries only, that is why this value will always be null"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Response463397119C53_AppDataGoogleAppInfoTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppInfoTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppInfoTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppInfoTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppInfoTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "application id received in a POST request"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlayInfoOrganic"
}
]
},
"description": "found app info"
}
}
},
"Response463397119C53_GooglePlayInfoOrganic": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed apps
absolute position among all apps on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values: left"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "ID of the app"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the app page on Google Play"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL to the app icon"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the app"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews the app has",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "average rating of the app"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price of the app"
},
"is_free": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the app is free"
},
"main_category": {
"type": [
"string",
"null"
],
"description": "main category of the app"
},
"installs": {
"type": [
"string",
"null"
],
"description": "number of installs of the app
approximate number of installs as displayed on the app page"
},
"installs_count": {
"type": [
"integer",
"null"
],
"description": "number of installs of the app
the exact number of installs of the app",
"format": "int64"
},
"developer": {
"type": [
"string",
"null"
],
"description": "name of the app developer"
},
"developer_id": {
"type": [
"string",
"null"
],
"description": "ID of the app developer"
},
"developer_url": {
"type": [
"string",
"null"
],
"description": "URL to the developer page on Google Play"
},
"developer_email": {
"type": [
"string",
"null"
],
"description": "email address of the developer"
},
"developer_address": {
"type": [
"string",
"null"
],
"description": "physical address of the developer"
},
"developer_website": {
"type": [
"string",
"null"
],
"description": "official website of the developer"
},
"version": {
"type": [
"string",
"null"
],
"description": "current version of the app"
},
"minimum_os_version": {
"type": [
"string",
"null"
],
"description": "minimum OS version required to install the app"
},
"size": {
"type": [
"string",
"null"
],
"description": "size of the app"
},
"released_date": {
"type": [
"string",
"null"
],
"description": "date and time when the app was released
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"last_update_date": {
"type": [
"string",
"null"
],
"description": "date and time when the app was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"update_notes": {
"type": [
"string",
"null"
],
"description": "update notes
contains the latest update notes from the developer"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "app images
contains URLs to the images published on the app page on Google Play"
},
"videos": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "app videos
contains URLs to the video published on the app page on Google Play"
},
"similar_apps": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppsInfo"
}
]
},
"description": "similar apps
displays apps similar to the app in a POST request"
},
"more_apps_by_developer": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppsInfo"
}
]
},
"description": "similar apps
information about apps built by the same developer"
},
"genres": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "app genres
contains relevant app categories"
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "app tags
contains relevant app tags"
}
}
},
"Response463397119C53_AppDataGoogleAppInfoTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppInfoTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppInfoTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppInfoTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppInfoTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "application ID received in a POST request"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Provider463397119C53_AppDataGoogleAppInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if language_name is not specified
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"app_id": "org.telegram.messenger",
"location_code": 2840,
"language_code": "en"
}
]
},
"Response463397119C53_AppDataGoogleAppInfoTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppInfoTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppInfoTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "app collection received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of app items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlaySearchOrganic"
}
]
},
"description": "found apps"
}
}
},
"Response463397119C53_GooglePlaySearchOrganic": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the app page on Google Play"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL to the app icon"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews of the app",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "average rating of the app"
},
"is_free": {
"type": [
"boolean",
"null"
]
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
]
},
"developer": {
"type": [
"string",
"null"
],
"description": "name of the app developer"
},
"developer_url": {
"type": [
"string",
"null"
],
"description": "URL to the developer page on Google Play"
}
}
},
"Response463397119C53_AppDataGoogleAppListTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "app collection received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Provider463397119C53_AppDataGoogleAppListTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_collection": {
"type": "string",
"description": "app collection
required field
app collection on Google Play from which apps will be collected;
you can specify the following values:featured, topselling_paid, topselling_free, topselling_new_free, topselling_new_paid, topgrossing, movers_shakers
Note: if featured is selected, the app_category parameter cannot be used"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if language_name is not specified
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of apps to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row;
default value: 100;
maximum value: 200;
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"app_category": {
"type": [
"string",
"null"
],
"description": "application category on Google Play
optional field
you can filter the results by app category;
example:family;
you can receive the full list of available categories by making a separate request to https://api.dataforseo.com/v3/app_data/google/categories
Note: app_category cannot be used if app_collection parameter is set to featured"
},
"age_rating": {
"type": [
"string",
"null"
],
"description": "filter results by age rating
optional field
you can use this field to filter the results by age rating;
possible types of filtering:ages_up_to_5 — return apps approved for children up to 5 years old;ages_6_8 — return apps approved for children from 6 to 8 years old;ages_9_12 — return apps approved for children from 9 to 12 years old;
by default, the API returns apps for all ages;
Note: this filter works only in conjunction with the \"category\": \"family\" parameter"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"app_collection": "topselling_free",
"location_code": 2840,
"language_code": "en",
"depth": 100
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListingsCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListingsCategoriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListingsCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListingsCategoriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListingsCategoriesResultInfo": {
"type": "object",
"properties": {
"category": {
"type": [
"string",
"null"
],
"description": "name of the supported app category"
},
"count": {
"type": [
"integer",
"null"
],
"description": "number of app listings that make up the supported app category",
"format": "int64"
}
}
},
"Provider463397119C53_AppDataGoogleAppListingsSearchLiveRequestInfo": {
"type": "object",
"properties": {
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "app categories
optional field
the categories you specify are used to search for app listings;
you can get the full list of available app listing categories by this link
you can specify up to 10 categories"
},
"description": {
"type": [
"string",
"null"
],
"description": "keyword in the app's description
optional field
keywords that occur in the description of the app;
can contain up to 200 characters"
},
"title": {
"type": [
"string",
"null"
],
"description": "keyword in the app's title
optional field
keywords that occur in the title of the app;
can contain up to 200 characters"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"item.rating.value\",\">\",3]https://api.dataforseo.com/v3/app_data/google/app_listings/available_filters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"item.installs_count,asc\"]
you should use a comma to separate several sorting rules
example:[\"item.rating.value,desc\",\"item.installs_count,asc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned apps
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"title": "vpn",
"description": "vpn",
"categories": [
"Tools"
],
"order_by": [
"item.installs_count,asc"
],
"filters": [
[
"item.rating.value",
">",
4.5
]
],
"limit": 10
}
]
},
"Response463397119C53_AppDataGoogleAppListingsSearchLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListingsSearchLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListingsSearchLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListingsSearchLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppListingsSearchLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "the total number of relevant results in the database",
"format": "int64"
},
"count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
you can use this parameter in the POST request to avoid timeouts while trying to obtain over 100,000 results in a single request"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppListingsSearchLiveItem"
}
]
},
"description": "array of apps and related data"
}
}
},
"Response463397119C53_AppDataGoogleAppListingsSearchLiveItem": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "ID of the returned app"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"time_update": {
"type": [
"string",
"null"
],
"description": "date and time when SERP data was last updated
in the ISO 8601 format: “YYYY-MM-DDThh:mm:ss.sssssssZ”
example:2023-05-23 10:16:19 +00:00"
},
"item": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlayInfoOrganic"
}
],
"description": "detailed information about the app"
}
}
},
"Response463397119C53_AppDataGoogleAppReviewsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppReviewsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppReviewsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppReviewsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppReviewsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "application id received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the app
title of the application for which the reviews are collected"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the app
rating of the application for which the reviews are collected"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlayReviewsSearch"
}
]
},
"description": "found reviews
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_GooglePlayReviewsSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: left"
},
"version": {
"type": [
"string",
"null"
],
"description": "version of the app
version of the app for which the review is submitted"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the review was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"id": {
"type": [
"string",
"null"
],
"description": "id of the review"
},
"helpful_count": {
"type": [
"integer",
"null"
],
"description": "number of helpful votes
indicates how many users considered the review helpful and voted with the thumbs up icon",
"format": "int64"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the review
Google Play doesn't provide an option to title reviews, so this parameter will always equal null"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "content of the review"
},
"user_profile": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppUserProfileInfo"
}
],
"description": "user profile of the reviewer"
},
"responses": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ResponseDataInfo"
}
]
},
"description": "response from the developer"
}
}
},
"Response463397119C53_ResponseDataInfo": {
"type": "object",
"properties": {
"author": {
"type": [
"string",
"null"
],
"description": "author of the response"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the response
in this case, will equal null"
},
"text": {
"type": [
"string",
"null"
],
"description": "content of the response"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the response was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_AppDataGoogleAppReviewsTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppReviewsTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppReviewsTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppReviewsTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppReviewsTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"app_id": {
"type": [
"string",
"null"
],
"description": "app id received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Provider463397119C53_AppDataGoogleAppReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:https://play.google.com/store/apps/details?id=org.telegram.messenger"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 150, because our system processes 150 reviews in a row;
default value: 150;
maximum value: 100000;
Your account will be billed per each SERP containing up to 150 results;
Setting depth above 150 may result in additional charges if the search engine returns more than 150 results;
The cost can be calculated on the Pricing page."
},
"rating": {
"type": [
"integer",
"null"
],
"description": "filter reviews by rating
optional field
you can use this field to filter the results;
possible types of filtering:5 — return reviews with five-star rating only;4 — return reviews with four-star rating only;3 — return reviews with three-star rating only;2 — return reviews with two-star rating only;1 — return reviews with one-star rating only;
by default, the API returns all reviews regardless of the number of stars"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:newest — sort by the most recent reviews;most_relevant — sort by the most relevant reviews;
default rule: most_relevant"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"app_id": "org.telegram.messenger",
"location_code": 2840,
"language_code": "en",
"depth": 150
}
]
},
"Response463397119C53_AppDataGoogleAppReviewsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppReviewsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppReviewsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppSearchesTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppSearchesTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST request"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlaySearchOrganic"
}
]
},
"description": "found apps"
}
}
},
"Response463397119C53_AppDataGoogleAppSearchesTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppSearchesTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppSearchesTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST request"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Provider463397119C53_AppDataGoogleAppSearchesTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be returned to be returned from the Google Play SERP;
we strongly recommend setting the parsing depth in the multiples of 30, because our system processes 30 results in a row;
default value: 30;
maximum value: 200;
Your account will be billed per each SERP containing up to 30 results;
Setting depth above 30 may result in additional charges if the search engine returns more than 30 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"keyword": "vpn",
"location_code": 2840,
"language_code": "en",
"depth": 30
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleAppSearchesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleAppSearchesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_AppDataGoogleCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleCategoriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleCategoriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleCategoriesResultInfo": {
"type": "object",
"properties": {
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains full list of supported app categories"
}
}
},
"Response463397119C53_AppDataGoogleLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_AppDataGoogleLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_AppDataGoogleLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppDataGoogleLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_AppDataGoogleLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_name_parent": {
"type": [
"string",
"null"
],
"description": "the name of the superordinate location
example:\"location_code\": 1006473, where
\"location_name\": \"Altrincham,England,United Kingdom\",
\"location_name_parent\": \"England,United Kingdom\",location_name_parent corresponds to:\"location_code\": 20339,"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Provider463397119C53_BacklinksAnchorsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get anchors for
\"location_name\": \"England,United Kingdom\"
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned anchors
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned anchors
optional field
default value: 0
if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_links_types.anchors\",\">\",\"1\"][[\"broken_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"limit": 4,
"order_by": [
"backlinks,desc"
],
"filters": [
"anchor",
"like",
"%news%"
]
}
]
},
"Response463397119C53_BacklinksAnchorsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksAnchorsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksAnchorsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksAnchorsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksAnchorsLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target in the post array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksAnchorsLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksAnchorsLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"anchor": {
"type": [
"string",
"null"
],
"description": "anchor of the backlink"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank of the anchor links
rank volume that referring websites pass to the target through links with a particular anchorrank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlinks",
"format": "int64"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink with this anchor for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink with this anchor was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2017-01-24 13:20:59 +00:00"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score of all backlinks with this anchor
learn more about how the metric is calculated on this help center page",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the target",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring domains",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to target with this anchor",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target with this anchor",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and link count per each semantic location
examples:article, section, summary"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksBacklinksLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get backlinks for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns all backlinksone_per_domain - returns one backlink per domainone_per_anchor - returns one backlink per anchoras_is"
},
"custom_mode": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
},
"description": "detailed results grouping type
optional field
use this object to get a specific number of backlinks per field
if you use custom_mode, then mode will be ignored
example:\"custom_mode\": {\"field\": \"domain\", \"value\": 100}"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, regex, not_regex, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rank\",\">\",\"80\"][[\"page_from_rank\",\">\",\"55\"],
\"and\",
[\"dofollow\",\"=\",true]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"text_pre\",\"like\",\"%seo%\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"domain_from_rank,desc\",\"page_from_rank,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned backlinks
optional field0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks;
Note: the maximum value is 20,000, use the search_after_token if you would like to offset more results"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned backlinks
optional field100
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"mode": "as_is",
"filters": [
"dofollow",
"=",
true
],
"limit": 5
}
]
},
"Response463397119C53_BacklinksBacklinksLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBacklinksLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBacklinksLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBacklinksLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBacklinksLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"mode": {
"type": [
"string",
"null"
],
"description": "mode specified in a POST array"
},
"custom_mode": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
},
"description": "custom mode specified in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBacklinksLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
by specifying the unique search_after_token when setting a new task, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task"
}
}
},
"Response463397119C53_BacklinksBacklinksLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"domain_from": {
"type": [
"string",
"null"
],
"description": "domain referring to the target domain or webpage"
},
"url_from": {
"type": [
"string",
"null"
],
"description": "URL of the page where the backlink is found"
},
"url_from_https": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the referring URL is secured with HTTPS
if true, the referring URL is secured with HTTPS"
},
"domain_to": {
"type": [
"string",
"null"
],
"description": "domain the backlink is pointing to"
},
"url_to": {
"type": [
"string",
"null"
],
"description": "URL the backlink is pointing to"
},
"url_to_https": {
"type": [
"boolean",
"null"
],
"description": "indicates if the URL the backlink is pointing to is secured with HTTPS
if true, the URL is secured with HTTPS"
},
"tld_from": {
"type": [
"string",
"null"
],
"description": "top-level domain of the referring URL"
},
"is_new": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is new
if true, the backlink was found on the page last time our crawler visited it"
},
"is_lost": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink was removed
if true, the backlink or the entire page was removed"
},
"backlink_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the backlink
learn more about how the metric is calculated on this help center page"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "backlink rank
rank that the given backlink passes to the targetrank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"page_from_rank": {
"type": [
"integer",
"null"
],
"description": "page rank of the referring pagepage_from_rank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"domain_from_rank": {
"type": [
"integer",
"null"
],
"description": "domain rank of the referring domaindomain_from_rank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"domain_from_platform_type": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "platform types of the referring domaincms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"domain_from_is_ip": {
"type": [
"boolean",
"null"
],
"description": "indicates if the domain is IP
if true, the domain functions as an IP address and does not have a domain name"
},
"domain_from_ip": {
"type": [
"string",
"null"
],
"description": "IP address of the referring domain"
},
"domain_from_country": {
"type": [
"string",
"null"
],
"description": "ISO country code of the referring domain"
},
"page_from_external_links": {
"type": [
"integer",
"null"
],
"description": "number of external links found on the referring page"
},
"page_from_internal_links": {
"type": [
"integer",
"null"
],
"description": "number of internal links found on the referring page"
},
"page_from_size": {
"type": [
"integer",
"null"
],
"description": "size of the referring page, in bytes
example:63357"
},
"page_from_encoding": {
"type": [
"string",
"null"
],
"description": "character encoding of the referring page
example:utf-8"
},
"page_from_language": {
"type": [
"string",
"null"
],
"description": "language of the referring page
in ISO 639-1 format
example:en"
},
"page_from_title": {
"type": [
"string",
"null"
],
"description": "title of the referring page"
},
"page_from_status_code": {
"type": [
"integer",
"null"
],
"description": "HTTP status code returned by the referring page
example:200"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"prev_seen": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date when our crawler visited the backlink
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"last_seen": {
"type": [
"string",
"null"
],
"description": "most recent date when our crawler visited the backlink
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_type": {
"type": [
"string",
"null"
],
"description": "link type
possible values:anchor, image, meta, canonical, alternate, redirect"
},
"attributes": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "link attributes of the referring links
example:nofollow"
},
"dofollow": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is dofollow
if false, the backlink is nofollow"
},
"original": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink was present on the referring page when our crawler first visited it"
},
"alt": {
"type": [
"string",
"null"
],
"description": "alternative text of the image
this field will be null if backlink type is not image"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"anchor": {
"type": [
"string",
"null"
],
"description": "anchor text of the backlink"
},
"text_pre": {
"type": [
"string",
"null"
],
"description": "snippet before the anchor text"
},
"text_post": {
"type": [
"string",
"null"
],
"description": "snippet after the anchor text"
},
"semantic_location": {
"type": [
"string",
"null"
],
"description": "indicates semantic element in HTML where the backlink is found
you can get the full list of semantic elements here
examples:article, section, summary"
},
"links_count": {
"type": [
"integer",
"null"
],
"description": "number of identical backlinks found on the referring page",
"format": "int64"
},
"group_count": {
"type": [
"integer",
"null"
],
"description": "indicates total number of backlinks from this domain
for example, if mode is set to one_per_domain, this field will indicate the total number of backlinks coming from this domain",
"format": "int64"
},
"is_broken": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is broken
if true, the backlink is pointing to a page responding with a 4xx or 5xx status code"
},
"url_to_status_code": {
"type": [
"integer",
"null"
],
"description": "status code of the referenced page
if the value is null, our crawler hasn't yet visited the webpage the link is pointing to
example:200"
},
"url_to_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the referenced page
if the value is null, our crawler hasn't yet visited the webpage the link is pointing to;
learn more about how the metric is calculated on this help center page"
},
"url_to_redirect_target": {
"type": [
"string",
"null"
],
"description": "target url of the redirect
target page the redirect is pointing to"
},
"ranked_keywords_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankedKeywordsInfo"
}
]
},
"is_indirect_link": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is an indirect link
if true, the backlink is an indirect link pointing to a page that either redirects to url_to, or points to a canonical page"
},
"indirect_link_path": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksRedirectInfo"
}
]
},
"description": "indirect link path
indicates a URL or a sequence of URLs that lead to url_to"
}
}
},
"Response463397119C53_RankedKeywordsInfo": {
"type": "object",
"properties": {
"page_from_keywords_count_top_3": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"page_from_keywords_count_top_10": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"page_from_keywords_count_top_100": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
},
"Response463397119C53_BacklinksRedirectInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status code
you can find the full list of the response codes here
Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions"
},
"url": {
"type": [
"string",
"null"
],
"description": "indirect link URL"
}
}
},
"Provider463397119C53_BacklinksBulkBacklinksLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get the number of backlinks for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
},
"Response463397119C53_BacklinksBulkBacklinksLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkBacklinksLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkBacklinksLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkBacklinksLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkBacklinksLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkBacklinksLiveItem"
}
]
},
"description": "contains relevant backlink data"
}
}
},
"Response463397119C53_BacklinksBulkBacklinksLiveItem": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "domain, subdomain or webpage from a POST array"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "number of backlinks pointing to the target",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksBulkNewLostBacklinksLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get new & lost backlinks for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without `https://` and `www.` the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost backlinks;
the backlinks that appeared in our index after the specified date will be considered as new;
the backlinks that weren't found after the specified date, but were present before, will be considered as lost;
e.g. if today is 2021-10-13, default date_from will be 2021-09-13.
minimum value equals today's date -(minus) one year;
e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13.\"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
],
"date_from": "2026-09-12 05:48:19"
}
]
},
"Response463397119C53_BacklinksBulkNewLostBacklinksLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkNewLostBacklinksLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkNewLostBacklinksLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkNewLostBacklinksLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkNewLostBacklinksLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkNewLostBacklinksLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksBulkNewLostBacklinksLiveItem": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "domain, subdomain or webpage from a POST array"
},
"new_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of new backlinks
number of new backlinks pointing to the target",
"format": "int64"
},
"lost_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of lost backlinks
number of lost backlinks of the target",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksBulkNewLostReferringDomainsLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get new & lost referring domains for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost referring domains;
the referring domains that appeared in our index after the specified date will be considered as new;
the referring domains that weren't found after the specified date, but were present before, will be considered as lost;
e.g. if today is 2021-10-13, default date_from will be 2021-09-13.
minimum value equals today's date -(minus) one year;
e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13.\"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
],
"datetime_from": "2026-48-12"
}
]
},
"Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksBulkNewLostReferringDomainsLiveItem": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "domain, subdomain or webpage from a POST array"
},
"new_referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of new referring domains
number of new referring domains pointing to the target",
"format": "int64"
},
"lost_referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of lost referring domains
number of lost referring domains of the target",
"format": "int64"
},
"new_referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of new referring main domains pointing to the target",
"format": "int64"
},
"lost_referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of lost referring main domains pointing to the target",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksBulkPagesSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get summary data for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
you can specify up to 1000 pages, domains, or subdomains in each request.
note that the URLs you set in a single request cannot belong to more than 100 different domains."
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"https://dataforseo.com/solutions",
"https://dataforseo.com/about-us"
]
}
]
},
"Response463397119C53_BacklinksBulkPagesSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkPagesSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkPagesSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkPagesSummaryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkPagesSummaryLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkPagesSummaryLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksBulkPagesSummaryLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "page rank
rank of the page on the target websiterank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"main_domain_rank": {
"type": [
"integer",
"null"
],
"description": "rank of the main domain
rank of the main domain is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "number of backlinks",
"format": "int64"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found a backlink to this page for the first time
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink to this page was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2017-01-24 13:20:59 +00:00"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score of the backlinks pointing to the page
learn more about how the metric is calculated on this help center page",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the page",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number domains referring to the page",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the relevant url",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and link count per each semantic location
examples:article, section, footer"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksBulkRanksLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get rank for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
},
"Response463397119C53_BacklinksBulkRanksLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkRanksLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkRanksLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkRanksLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkRanksLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkRanksLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksBulkRanksLiveItem": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "domain, subdomain or webpage from a POST array"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank of the target
values represent real-time data for the date of the requestrank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
}
}
},
"Provider463397119C53_BacklinksBulkReferringDomainsLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get the number of referring domains for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
},
"Response463397119C53_BacklinksBulkReferringDomainsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkReferringDomainsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkReferringDomainsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkReferringDomainsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkReferringDomainsLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkReferringDomainsLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksBulkReferringDomainsLiveItem": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "domain, subdomain or webpage from a POST array"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring domains pointing to the target
note that we calculate main domains (root domains, like example.com) and their subdomains (e.g. blog.example.com) separately for this metric",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring main domains pointing to the target
the number of primary (root) domains referring to your target",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksBulkSpamScoreLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages to get rank for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
},
"Response463397119C53_BacklinksBulkSpamScoreLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkSpamScoreLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksBulkSpamScoreLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkSpamScoreLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksBulkSpamScoreLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksBulkSpamScoreLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksBulkSpamScoreLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"target": {
"type": [
"string",
"null"
],
"description": "domain, subdomain or webpage from a POST array"
},
"spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score the target
learn more about how the metric is calculated"
}
}
},
"Provider463397119C53_BacklinksCompetitorsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get competitor domains for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rank\",\">\",\"100\"][[\"target\",\"like\",\"%forbes%\"],
\"and\",
[[\"rank\",\">\",\"100\"],\"or\",[\"intersections\",\">\",\"5\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"intersections,desc\",\"rank,asc\"]"
},
"main_domain": {
"type": [
"boolean",
"null"
],
"description": "indicates if only main domain of the target will be included in the search
optional field
if set to true, only the main domain will be included in search;
default value: true"
},
"exclude_large_domains": {
"type": [
"boolean",
"null"
],
"description": "indicates whether large domain will appear in results
optional field
if set to true, the results from the large domain (google.com, amazon.com, etc.) will be omitted;
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"filters": [
"rank",
">",
100
],
"order_by": [
"rank,desc"
],
"limit": 5
}
]
},
"Response463397119C53_BacklinksCompetitorsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksCompetitorsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksCompetitorsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksCompetitorsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksCompetitorsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksCompetitorsLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksCompetitorsLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"target": {
"type": [
"string",
"null"
],
"description": "competitor domain"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "domain rank
domain rank across all domains in the databaserank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"intersections": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlink intersections with the target specified in the POST array"
}
}
},
"Provider463397119C53_BacklinksDomainIntersectionLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "domains, subdomains or webpages to get links for
required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": {
\"1\": \"http://planet.postgresql.org/\",
\"2\": \"http://gborg.postgresql.org/\"
}`"
},
"exclude_targets": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages you want to exclude
optional field
you can specify up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring domains that link to targets but don't link to exclude_targets
example:
`\"exclude_targets\": [
\"bbc.com\",
\"https://www.apple.com/iphone/*\",
\"https://dataforseo.com/apis/*\"]`"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"1.internal_links_count\",\">\",\"1\"][[\"2.referring_pages\",\">\",\"2\"],
\"and\",
[\"1.backlinks\",\">\",\"10\"]][[\"1.first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"2.target\",\"like\",\"%dataforseo.com%\"],\"or\",[\"1.referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the array of returned results
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned results
optional field
default value: 100
maximum value: 1000"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be omitted and you won't receive the same domain in the response;
default value: true"
},
"intersection_mode": {
"type": [
"string",
"null"
],
"description": "indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified domains
possible values: all, partialall - results are based on all backlinks;partial - results are based on the intersecting backlinks only;
default value: all"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": {
"1": "moz.com",
"2": "ahrefs.com"
},
"include_subdomains": false,
"exclude_targets": [
"semrush.com"
],
"limit": 5,
"order_by": [
"1.backlinks,desc"
],
"exclude_internal_backlinks": true
}
]
},
"Response463397119C53_BacklinksDomainIntersectionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainIntersectionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksDomainIntersectionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainIntersectionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksDomainIntersectionLiveResultInfo": {
"type": "object",
"properties": {
"targets": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target domains, subdomains or webpages in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainIntersectionLiveItem"
}
]
},
"description": "contains domain that link to all targets from the POST array"
}
}
},
"Response463397119C53_BacklinksDomainIntersectionLiveItem": {
"type": "object",
"properties": {
"domain_intersection": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainIntersection"
}
]
},
"description": "contains data on domains that link to the corresponding targets specified in the POST array
data is provided in separate objects corresponding to domains, subdomains or pages specified in the targets object"
},
"summary": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_IntersectionSummaryInfo"
}
],
"description": "contains the domain intersections summary"
}
}
},
"Response463397119C53_BacklinksDomainIntersection": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"target": {
"type": [
"string",
"null"
],
"description": "domain that links to the corresponding target from the POST array"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank referred to the target from the POST array
indicates the rank that the referring domain (target above) refers to your target from the POST array;rank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlinks",
"format": "int64"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink from this target for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink from this target was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score of the backlinks pointing to the target
learn more about how the metric is calculated on this help center page",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring domains",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the corresponding target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the target",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
]
},
"description": "top level domains of the referring links
contains top-level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
]
},
"description": "types of the referring links
indicates the types of referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
]
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and the link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
]
},
"description": "types of referring platforms
indicates referring platform types and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
]
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and the link count per each semantic location
you can get the full list of semantic elements here"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Response463397119C53_IntersectionSummaryInfo": {
"type": "object",
"properties": {
"intersections_count": {
"type": [
"integer",
"null"
],
"description": "total number of intersections",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksDomainPagesLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain or subdomain
required field
a domain or a subdomain should be specified without https:// and www.
example:forbes.com"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"meta.internal_links_count\",\">\",\"1\"][[\"meta.external_links_count\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_visited\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"title\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"page_summary.backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"page_summary.backlinks,desc\",\"page_summary.rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [\"dofollow\", \"=\", true]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"limit": 5,
"filters": [
[
"page_summary.backlinks",
">",
5
],
"and",
[
"page",
"like",
"%sites%"
]
]
}
]
},
"Response463397119C53_BacklinksDomainPagesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainPagesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksDomainPagesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainPagesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksDomainPagesLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainPagesLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksDomainPagesLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "main website domain
main website domain does not include subdomains"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain
domain where the page was found"
},
"tld": {
"type": [
"string",
"null"
],
"description": "top-level domain
top-level domain in the DNS root zone"
},
"page": {
"type": [
"string",
"null"
],
"description": "page URL
relevant page URL"
},
"ip": {
"type": [
"string",
"null"
],
"description": "Internet Protocol address"
},
"first_visited": {
"type": [
"string",
"null"
],
"description": "date and time of the first page visit
date and time when our crawler visited this page for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2017-01-24 13:20:59 +00:00"
},
"prev_visited": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date when our crawler visited the page
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2017-01-24 13:20:59 +00:00"
},
"fetch_time": {
"type": [
"string",
"null"
],
"description": "most recent date and time when our crawler visited the page
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2017-01-24 13:20:59 +00:00"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status code
you can find the full list of the response codes here
Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions"
},
"location": {
"type": [
"string",
"null"
],
"description": "location header
indicates the URL to redirect a page to if exists"
},
"size": {
"type": [
"integer",
"null"
],
"description": "indicates the page size, in bytes"
},
"encoded_size": {
"type": [
"integer",
"null"
],
"description": "page size after encoding
indicates the size of the encoded page, in bytes"
},
"content_encoding": {
"type": [
"string",
"null"
],
"description": "type of encoding"
},
"media_type": {
"type": [
"string",
"null"
],
"description": "types of media used to display a page"
},
"server": {
"type": [
"string",
"null"
],
"description": "server version"
},
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksPageMeta"
}
],
"properties": {
"social_media_tags": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"description": "page meta data"
},
"page_summary": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageSummary"
}
],
"properties": {
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
},
"description": "contains backlink data for this page"
}
}
},
"Response463397119C53_BacklinksPageMeta": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "page title"
},
"canonical": {
"type": [
"string",
"null"
],
"description": "canonical page"
},
"internal_links_count": {
"type": [
"integer",
"null"
],
"description": "number of internal links on the page",
"format": "int64"
},
"external_links_count": {
"type": [
"integer",
"null"
],
"description": "number of external links on the page",
"format": "int64"
},
"images_count": {
"type": [
"integer",
"null"
],
"description": "number of images on the page",
"format": "int64"
},
"words_count": {
"type": [
"integer",
"null"
],
"description": "number of words on the page",
"format": "int64"
},
"page_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the page
learn more about how the metric is calculated on this help center page"
},
"social_media_tags": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "array of social media tags found on the page
contains social media tags and their content
supported tags include but are not limited to Open Graph and Twitter card"
},
"h1": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "h1 tag
content of h1 tags"
},
"h2": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "h2 tag
content of h2 tags"
},
"h3": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "h3 tag
content of h3 tags"
},
"images_alt": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "content of alt tags"
},
"powered_by": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "CMS details"
},
"language": {
"type": [
"string",
"null"
],
"description": "page content language
example:en"
},
"charset": {
"type": [
"string",
"null"
],
"description": "character encoding
examples:utf-8"
},
"platform_type": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "type of a platform"
},
"technologies": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "website technologies"
}
}
},
"Response463397119C53_PageSummary": {
"type": "object",
"properties": {
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink for this page was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2017-01-24 13:20:59 +00:00"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "page rank
rank of the pagerank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlinks",
"format": "int64"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score of the backlinks pointing to the page
learn more about how the metric is calculated on this help center page",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the page",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring domains",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the page",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the page",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the page",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the page",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and link count per each semantic location
examples:article, section, summary"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksDomainPagesSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get summary data for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned anchors
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned anchors
optional field
default value: 0
if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_links_types.anchors\",\">\",\"1\"][[\"broken_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target domain will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, backlinks from the subdomains of the target domain will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"limit": 4,
"order_by": [
"backlinks,desc"
]
}
]
},
"Response463397119C53_BacklinksDomainPagesSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainPagesSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksDomainPagesSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainPagesSummaryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksDomainPagesSummaryLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target in the post array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksDomainPagesSummaryLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksDomainPagesSummaryLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "page rank
rank of the pagerank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "number of backlinks",
"format": "int64"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found a backlink to this page for the first time
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink to this page was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2017-01-24 13:20:59 +00:00"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score of the backlinks pointing to the page
learn more about how the metric is calculated on this help center page",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the page",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number domains referring to the page",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the page",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the page",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the relevant url",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the page",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and link count per each semantic location
examples:article, section, footer"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksHistoryLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain
required field
a domain should be specified without https:// and www."
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimum value 2019-01-01
if you don't specify this field, the minimum value will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "cnn.com",
"date_from": "2020-01-01",
"date_to": "2021-01-01"
}
]
},
"Response463397119C53_BacklinksHistoryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksHistoryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksHistoryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksHistoryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksHistoryLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target from the POST array"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
in the UTC format: “yyyy-mm-dd”
example:2019-01-01"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
in the UTC format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksHistoryLiveItem"
}
]
},
"description": "contains historical backlink data for the specified domain
the data is provided month-by-month;
the metrics are aggregated according to the backlinks the specified domain had on the first day of each given month"
}
}
},
"Response463397119C53_BacklinksHistoryLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date and time when the data for the target was stored
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "domain rank on the given date
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "number of backlinks",
"format": "int64"
},
"new_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of new backlinks for the target
data is provided based in a comparison with the previous period
Note: this data is available from May 2021;
if the date range specified in the POST request precedes May 2021, the field will equal 0",
"format": "int64"
},
"lost_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of lost backlinks for the target
data is provided based in a comparison with the previous period
Note: this data is available from May 2021;
if the date range specified in the POST request precedes May 2021, the field will equal 0",
"format": "int64"
},
"new_referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of new referring domains for the target
data is provided based in a comparison with the previous period
Note: this data is available from May 2021;
if the date range specified in the POST request precedes May 2021, the field will equal 0",
"format": "int64"
},
"lost_referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of lost referring domains for the target
data is provided based in a comparison with the previous period
Note: this data is available from May 2021;
if the date range specified in the POST request precedes May 2021, the field will equal 0",
"format": "int64"
},
"crawled_pages": {
"type": [
"integer",
"null"
],
"description": "number of crawled pages for the target"
},
"info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TargetInfo"
}
],
"description": "information about the target"
},
"internal_links_count": {
"type": [
"integer",
"null"
],
"description": "number of internal links
calculated as the sum of internal links on the pages of the specified target",
"format": "int64"
},
"external_links_count": {
"type": [
"integer",
"null"
],
"description": "number of external links on the page
calculated as the sum of external links on the pages of the specified target",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the target",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that receive backlinks but respond with 4xx or 5xx status codes"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring domains
referring domains include subdomains that are counted as separate domains for this metric",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "number of pages pointing to the target",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top-level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and link count per each semantic location
you can get the full list of semantic elements here
examples:article, section, summary"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Response463397119C53_TargetInfo": {
"type": "object",
"properties": {
"server": {
"type": [
"string",
"null"
],
"description": "server"
},
"cms": {
"type": [
"string",
"null"
],
"description": "content management system"
},
"platform_type": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "platform type"
},
"ip_address": {
"type": [
"string",
"null"
],
"description": "IP address of the target"
},
"country": {
"type": [
"string",
"null"
],
"description": "country code that the target domain is determined to belong to"
},
"is_ip": {
"type": [
"boolean",
"null"
],
"description": "indicates if the target is IP
if true, the domain, subdomain or webpage functions as an IP address and does not have a domain name"
},
"target_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the target
if the target is a domain/subdomain, this fields indicates the average spam score of all pages of that domain/subdomain;
learn more about how the metric is calculated on this help center page"
}
}
},
"Response463397119C53_BacklinksIndexResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksIndexTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksIndexTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksIndexResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksIndexResultInfo": {
"type": "object",
"properties": {
"total_backlinks": {
"type": [
"integer",
"null"
],
"description": "total number of backlinks our database contains for the moment of checking",
"format": "int64"
},
"total_pages": {
"type": [
"integer",
"null"
],
"description": "total number of pages our database contains for the moment of checking",
"format": "int64"
},
"index_history": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_IndexHistory"
}
]
},
"description": "index volume data for the past 12 months"
}
}
},
"Response463397119C53_IndexHistory": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"description": "date for which index volume data is provided
in the UTC format: \"yyyy-mm-dd\"
example:2021-10-01"
},
"total_backlinks": {
"type": [
"integer",
"null"
],
"description": "total number of backlinks our database contained on the given date",
"format": "int64"
},
"total_pages": {
"type": [
"integer",
"null"
],
"description": "total number of pages our database contained on the given date",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksPageIntersectionLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "domains, subdomains or webpages to get links for
required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": {
\"1\": \"http://planet.postgresql.org/\",
\"2\": \"http://gborg.postgresql.org/\"
}`"
},
"exclude_targets": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages you want to exclude
optional field
you can set up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring pages that link to targets but don't link to exclude_targets
example:
`\"exclude_targets\": [
\"bbc.com\",
\"https://www.apple.com/iphone/*\",
\"https://dataforseo.com/apis/*\"]`"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"1.rank\",\">\",\"80\"][[\"2.page_from_rank\",\">\",\"55\"],
\"and\",
[\"1.original\",\"=\",\"true\"]][[\"1.first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"1.acnhor\",\"like\",\"%seo%\"],\"or\",[\"1.text_pre\",\"not_like\",\"%seo%\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"domain_from_rank,desc\",\"page_from_rank,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned backlinks
optional field0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned backlinks
optional field100
maximum value: 1000"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:attributesdomain_from_platform_type10
maximum value: 1000"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the targets will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the result
default value: true"
},
"intersection_mode": {
"type": [
"string",
"null"
],
"description": "indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified URLs
possible values: all, partialall - results are based on all backlinks;partial - results are based on the intersecting backlinks only;
default value: all"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": {
"1": "football.com",
"2": "fifa.com"
},
"exclude_targets": [
"skysports.com"
],
"limit": 5,
"order_by": [
"1.rank,desc"
],
"filters": [
[
"2.domain_from_rank",
">",
400
],
"and",
[
"1.dofollow",
"=",
true
]
]
}
]
},
"Response463397119C53_BacklinksPageIntersectionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksPageIntersectionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksPageIntersectionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksPageIntersectionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksPageIntersectionLiveResultInfo": {
"type": "object",
"properties": {
"targets": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "targets from a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results relevant the request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksPageIntersectionLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksPageIntersectionLiveItem": {
"type": "object",
"properties": {
"page_intersection": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksPageIntersection"
}
]
}
},
"description": "contains data on pages that link to the corresponding targets specified in the POST array
data is provided in separate objects corresponding to pages specified in the targets object"
},
"summary": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_IntersectionSummaryInfo"
}
],
"description": "contains the page intersections summary"
}
}
},
"Response463397119C53_BacklinksPageIntersection": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"domain_from": {
"type": [
"string",
"null"
],
"description": "domain referring to the target domain or webpage"
},
"url_from": {
"type": [
"string",
"null"
],
"description": "URL of the page where the backlink is found"
},
"url_from_https": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the referring URL is secured with HTTPS
if true, the referring URL is secured with HTTPS"
},
"domain_to": {
"type": [
"string",
"null"
],
"description": "domain the backlink is pointing to"
},
"url_to": {
"type": [
"string",
"null"
],
"description": "URL the backlink is pointing to"
},
"url_to_https": {
"type": [
"boolean",
"null"
],
"description": "indicates if the URL the backlink is pointing to is secured with HTTPS
if true, the URL is secured with HTTPS"
},
"tld_from": {
"type": [
"string",
"null"
],
"description": "top-level domain of the referring URL"
},
"is_new": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is new
if true, the backlink was found on the page last time our crawler visited it"
},
"is_lost": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink was removed
if true, the backlink or the entire page was removed"
},
"backlink_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the backlink
learn more about how the metric is calculated on this help center page"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "backlink rankrank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"page_from_rank": {
"type": [
"integer",
"null"
],
"description": "page rank of the referring pagepage_from_rank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"domain_from_rank": {
"type": [
"integer",
"null"
],
"description": "domain rank of the referring domain
indicates the rank of the domain at the time our crawler last saw the backlink;domain_from_rank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"domain_from_platform_type": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "platform types of the referring domaincms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"domain_from_is_ip": {
"type": [
"boolean",
"null"
],
"description": "indicates if the domain is IP
if true, the domain functions as an IP address and does not have a domain name"
},
"domain_from_ip": {
"type": [
"string",
"null"
],
"description": "IP address of the referring domain"
},
"domain_from_country": {
"type": [
"string",
"null"
],
"description": "ISO country code of the referring domain"
},
"page_from_external_links": {
"type": [
"integer",
"null"
],
"description": "number of external links found on the referring page"
},
"page_from_internal_links": {
"type": [
"integer",
"null"
],
"description": "number of internal links found on the referring page"
},
"page_from_size": {
"type": [
"integer",
"null"
],
"description": "size of the referring page, in bytes
example:63357"
},
"page_from_encoding": {
"type": [
"string",
"null"
],
"description": "character encoding of the referring page
example:utf-8"
},
"page_from_language": {
"type": [
"string",
"null"
],
"description": "language of the referring page
in ISO 639-1 format
example:en"
},
"page_from_title": {
"type": [
"string",
"null"
],
"description": "title of the referring page"
},
"page_from_status_code": {
"type": [
"integer",
"null"
],
"description": "HTTP status code returned by the referring page
example:200"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"prev_seen": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date when our crawler visited the backlink
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"last_seen": {
"type": [
"string",
"null"
],
"description": "most recent date when our crawler visited the backlink
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_type": {
"type": [
"string",
"null"
],
"description": "link type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"attributes": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "link attributes of the referring links
example:nofollow"
},
"dofollow": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is dofollow
if false, the backlink is nofollow"
},
"original": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink was present on the referring page when our crawler first visited it"
},
"alt": {
"type": [
"string",
"null"
],
"description": "alternative text of the image
this field will be null if backlink type is not image"
},
"anchor": {
"type": [
"string",
"null"
],
"description": "anchor text of the backlink"
},
"text_pre": {
"type": [
"string",
"null"
],
"description": "text snippet before the anchor text"
},
"text_post": {
"type": [
"string",
"null"
],
"description": "snippet after the anchor text"
},
"semantic_location": {
"type": [
"string",
"null"
],
"description": "indicates semantic element in HTML where the backlink is found
you can get the full list of semantic elements here
examples:article, section, summary"
},
"links_count": {
"type": [
"integer",
"null"
],
"description": "number of identical backlinks found on the referring page",
"format": "int64"
},
"group_count": {
"type": [
"integer",
"null"
],
"description": "indicates total number of backlinks from this domain
for example, if mode is set to one_per_domain, this field will indicate the total number of backlinks coming from this domain",
"format": "int64"
},
"is_broken": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is broken
if true, the backlink is pointing to a page responding with a 4xx or 5xx status code"
},
"url_to_status_code": {
"type": [
"integer",
"null"
],
"description": "status code of the referenced page
if the value is null, our crawler hasn't yet visited the webpage the link is pointing to
example:200"
},
"url_to_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the referenced page
if the value is null, our crawler hasn't yet visited the webpage the link is pointing to
learn more about how the metric is calculated on this help center page"
},
"url_to_redirect_target": {
"type": [
"string",
"null"
],
"description": "target url of the redirect
target page the redirect is pointing to"
},
"is_indirect_link": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlink is an indirect link
if true, the backlink is an indirect link pointing to a page that either redirects to url_to, or points to a canonical page"
},
"indirect_link_path": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksRedirectInfo"
}
]
},
"description": "indirect link path
indicates a URL or a sequence of URLs that lead to url_to"
}
}
},
"Provider463397119C53_BacklinksReferringDomainsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get referring domains for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_pages\",\">\",\"1\"][[\"referring_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"domain\",\"like\",\"%dataforseo.com%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [\"dofollow\", \"=\", true]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "backlinko.com",
"limit": 5,
"order_by": [
"rank,desc"
],
"exclude_internal_backlinks": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"filters": [
"backlinks",
">",
100
]
}
]
},
"Response463397119C53_BacklinksReferringDomainsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksReferringDomainsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksReferringDomainsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksReferringDomainsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksReferringDomainsLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database
total number of main domains referring to your target;
example.com and blog.example.com are counted as one referring domain",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksReferringDomainsLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksReferringDomainsLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "referring domain"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "domain rank
rank volume that a referring website passes to the targetrank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlinks pointing to the target",
"format": "int64"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink from this domain was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2017-01-24 13:20:59 +00:00"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "average spam score of all backlinks pointing to the domain
learn more about how the metric is calculated on this help center page",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the domain",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring domains
note that we calculate main domains (root domains, like example.com) and their subdomains (e.g. blog.example.com) separately for this metric",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains
the number of primary (root) domains referring to your target",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the target specified",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and the link count per each semantic location
examples:article, section, summary"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksReferringNetworksLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get referring networks for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"network_address_type": {
"type": [
"string",
"null"
],
"description": "indicates the type of network to get data for
optional field
possible values: ip, subnet
default value: ip"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned networks
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned networks
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_pages\",\">\",\"1\"][[\"referring_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"network_address\",\"like\",\"194.1.%\"],\"or\",[\"referring_ips\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "backlinko.com",
"network_address_type": "subnet",
"limit": 5,
"order_by": [
"rank,desc"
],
"exclude_internal_backlinks": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"filters": [
"backlinks",
">",
100
]
}
]
},
"Response463397119C53_BacklinksReferringNetworksLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksReferringNetworksLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksReferringNetworksLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksReferringNetworksLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksReferringNetworksLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksReferringNetworksLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BacklinksReferringNetworksLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"network_address": {
"type": [
"string",
"null"
],
"description": "address of the referring subnetwork or IP"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "network rank
rank volume that a referring network passes to the targetrank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlinks pointing to the target",
"format": "int64"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the last backlink from this domain was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2017-01-24 13:20:59 +00:00"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the domain",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages that respond with 4xx or 5xx status codes where backlinks are pointing to"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring domains
referring domains include subdomains that are counted as separate domains for this metric",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the target specified",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and the link count per each semantic location
examples:article, section, summary"
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain, subdomain or webpage to get data for
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [\"dofollow\", \"=\", true]"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "explodingtopics.com",
"internal_list_limit": 10,
"include_subdomains": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"backlinks_status_type": "all"
}
]
},
"Response463397119C53_BacklinksSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksSummaryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksSummaryLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target in a POST array"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the backlink for the target for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"lost_date": {
"type": [
"string",
"null"
],
"description": "date and time when the backlink was lost
indicates the date and time when our crawler visited the target and it responded with a 4xx or 5xx status code or when its last backlink was removed
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "target rank
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "indicates the number of backlinks",
"format": "int64"
},
"backlinks_spam_score": {
"type": [
"integer",
"null"
],
"description": "spam score of the backlinks
displays the total spam score of all backlinks pointing to the target domain, subdomain, or webpage;
to learn more about how the metric is calculated, refer to this Help Center page",
"format": "int64"
},
"crawled_pages": {
"type": [
"integer",
"null"
],
"description": "number of crawled pages for the target"
},
"info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TargetInfo"
}
],
"description": "information about the target"
},
"internal_links_count": {
"type": [
"integer",
"null"
],
"description": "number of internal links
calculated as the sum of internal links on the pages of the specified target",
"format": "int64"
},
"external_links_count": {
"type": [
"integer",
"null"
],
"description": "number of external links on the page
calculated as the sum of external links on the pages of the specified target",
"format": "int64"
},
"broken_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of broken backlinks
number of broken backlinks pointing to the target",
"format": "int64"
},
"broken_pages": {
"type": [
"integer",
"null"
],
"description": "number of broken pages
number of pages on the target that respond with 4xx or 5xx status codestarget discovered by following external links, but it may also include pages discovered by following the target's sitemap"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring domains
referring domains include subdomains that are counted as separate domains for this metric",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "indicates the number of referring main domains",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "indicates the number of pages pointing to the target",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target",
"format": "int64"
},
"referring_links_tld": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "top-level domains of the referring links
contains top level domains and referring link count per each"
},
"referring_links_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring links
indicates the types of the referring links and link count per each type
possible values:anchor, image, link, meta, canonical, alternate, redirect"
},
"referring_links_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "link attributes of the referring links
indicates link attributes of the referring links and link count per each attribute
example values:nofollow, noopener, noreferrer, external, ugc, sponsored"
},
"referring_links_platform_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "types of referring platforms
indicates referring platform types and and link count per each platformcms, blogs, ecommerce, message-boards, wikis, news, organization"
},
"referring_links_semantic_locations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and link count per each semantic location
example values:article, section, summary, \"\""
},
"referring_links_countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country"
}
}
},
"Provider463397119C53_BacklinksTimeseriesNewLostSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain to get data for
required field
a domain should be specified without https:// and www.
example:\"forbes.com\""
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost backlinks and referring domains;
the backlinks and referring domains that appeared in our index after the specified date will be considered as new;
the backlinks and referring domains that weren't found after the specified date, but were present before, will be considered as lost;2019-01-30
maximum value shouldn't exceed the date specified in the date_to
date format: \"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
minimum value shouldn't preceed the date specified in the date_from
maximum value: today's date
date format: \"yyyy-mm-dd\"
example:\"2021-01-15\""
},
"group_range": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month, yearday, we will return items corresponding to all dates between and including date_from and date_to;
for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year\"group_range\": \"month\",
\"date_from\": \"2022-03-23\",
\"date_to\": \"2022-05-13\"
we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31day/week/month/year, we will return 0"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"date_from": "2021-12-01",
"date_to": "2022-02-01",
"group_range": "month"
}
]
},
"Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target from a POST array"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
in the UTC format: “yyyy-mm-dd”
example:2019-01-01"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
in the UTC format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"group_range": {
"type": [
"string",
"null"
],
"description": "group_range from the POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveItem"
}
]
},
"description": "contains relevant backlinks and referring domains data"
}
}
},
"Response463397119C53_BacklinksTimeseriesNewLostSummaryLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date and time when the data for the target was stored
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"new_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of new backlinks
number of new backlinks pointing to the target",
"format": "int64"
},
"lost_backlinks": {
"type": [
"integer",
"null"
],
"description": "number of lost backlinks
number of lost backlinks of the target",
"format": "int64"
},
"new_referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of new referring domains
number of new referring domains pointing to the target",
"format": "int64"
},
"lost_referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of lost referring domains
number of lost referring domains of the target",
"format": "int64"
},
"new_referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of new referring main domains
number of new referring main domains pointing to the target",
"format": "int64"
},
"lost_referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of lost referring main domains
number of lost referring main domains of the target",
"format": "int64"
}
}
},
"Provider463397119C53_BacklinksTimeseriesSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain to get data for
required field
a domain should be specified without https:// and www.
example:\"forbes.com\""
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for summary data;2019-01-30
maximum value shouldn't exceed the date specified in the date_to
date format: \"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
minimum value shouldn't preceed the date specified in the date_from
maximum value: today's date
date format: \"yyyy-mm-dd\"
example:\"2021-01-15\""
},
"group_range": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month, yearday, we will return items corresponding to all dates between and including date_from and date_to;
for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year\"group_range\": \"month\",
\"date_from\": \"2022-03-23\",
\"date_to\": \"2022-05-13\"
we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31day/week/month/year, we will return 0"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"date_from": "2021-12-01",
"date_to": "2022-02-01",
"group_range": "month"
}
]
},
"Response463397119C53_BacklinksTimeseriesSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksTimeseriesSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BacklinksTimeseriesSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksTimeseriesSummaryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BacklinksTimeseriesSummaryLiveResultInfo": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
],
"description": "target from a POST array"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
in the UTC format: “yyyy-mm-dd”
example:2019-01-01"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
in the UTC format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"group_range": {
"type": [
"string",
"null"
],
"description": "group_range from a POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksTimeseriesSummaryLiveItem"
}
]
},
"description": "contains relevant summary data"
}
}
},
"Response463397119C53_BacklinksTimeseriesSummaryLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date and time when the data for the target was stored
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "target rank for the given date
learn more about the metric and how it is calculated in this help center article"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "number of backlinks for the given date",
"format": "int64"
},
"backlinks_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of nofollow backlinks for the given date",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "number of pages pointing to target for the given date",
"format": "int64"
},
"referring_pages_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of referring pages pointing at least one nofollow link to the target for the given date",
"format": "int64"
},
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring domains for the given date
referring domains include subdomains that are counted as separate domains for this metric",
"format": "int64"
},
"referring_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of domains pointing at least one nofollow link to the target for the given date",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "number of referring main domains for the given date",
"format": "int64"
},
"referring_main_domains_nofollow": {
"type": [
"integer",
"null"
],
"description": "number of main domains pointing at least one nofollow link to the target for the given date",
"format": "int64"
},
"referring_ips": {
"type": [
"integer",
"null"
],
"description": "number of referring IP addresses for the given date
number of IP addresses pointing to this page",
"format": "int64"
},
"referring_subnets": {
"type": [
"integer",
"null"
],
"description": "number of referring subnetworks for the given date",
"format": "int64"
}
}
},
"Provider463397119C53_BusinessDataBusinessListingsSearchLiveRequestInfo": {
"type": "object",
"properties": {
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "business categories
optional field
the categories you specify are used to search for business listings;
if you don't use this field, we will return business listings found in the specified location;
you can specify up to 10 categories"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the element in SERP
optional field
the description of the business entity for which the results are collected;
can contain up to 200 characters"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP
optional field
the name of the business entity for which the results are collected;
can contain up to 200 characters"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the business is verified by its owner on Google Maps
optional field"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional fieldlocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the value of \"radius\" is specified in kilometres (km)
the minimum value for \"radius\": 1
the maximum value for \"radius\": 100000
example:53.476225,-2.243572,200
learn more about how to set location parameters in this API on our Help Center"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rating.value\",\">\",3]
you can receive the list of available filters_by making a separate request to https://api.dataforseo.com/v3/business_data/business_listings/available_filters
The full list of possible filters is available here.n"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"rating.value,desc\"]note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"rating.value,desc\",\"rating.votes_count,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned businesses
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned businesses
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"categories": [
"pizza_restaurant"
],
"description": "pizza",
"title": "pizza",
"is_claimed": true,
"location_coordinate": "53.476225,-2.243572,10",
"order_by": [
"rating.value,desc"
],
"filters": [
[
"rating.value",
">",
3
]
],
"limit": 3
}
]
},
"Response463397119C53_BusinessDataBusinessListingsSearchLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataBusinessListingsSearchLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataBusinessListingsSearchLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataBusinessListingsSearchLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataBusinessListingsSearchLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in our database relevant to your request",
"format": "int64"
},
"count": {
"type": [
"integer",
"null"
],
"description": "item types
the number of items in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"offset_token": {
"type": [
"string",
"null"
]
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataBusinessListingsSearchLiveItem"
}
]
},
"description": "encountered item types
types of search engine results encountered in the items array;
possible item types: business_listing"
}
}
},
"Response463397119C53_BusinessDataBusinessListingsSearchLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP
the name of the business entity for which the results are collected"
},
"original_title": {
"type": [
"string",
"null"
],
"description": "original title of the element
original title not translated by Google"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the element in SERP
the description of the business entity for which the results are collected"
},
"category": {
"type": [
"string",
"null"
],
"description": "business category
Google My Business general category that best describes the services provided by the business entity"
},
"category_ids": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "global category IDs
universal category IDs that do not change based on the selected country"
},
"additional_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "additional business categories
additional Google My Business categories that describe the services provided by the business entity in more detail"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment
learn more about the identifier in this help center article"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the element in SERP
learn more about the identifier in this help center article"
},
"address": {
"type": [
"string",
"null"
],
"description": "address of the business entity"
},
"address_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AddressInfo"
}
],
"description": "object containing address components of the business entity"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "unique place identifier
place id of the local establishment featured in the element
learn more about the identifier in this help center article"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number of the business entity"
},
"url": {
"type": [
"string",
"null"
],
"description": "absolute url of the business entity"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the business entity"
},
"logo": {
"type": [
"string",
"null"
],
"description": "URL of the logo featured in Google My Business profile"
},
"main_image": {
"type": [
"string",
"null"
],
"description": "URL of the main image featured in Google My Business profile"
},
"total_photos": {
"type": [
"integer",
"null"
],
"description": "total count of images featured in Google My Business profile",
"format": "int64"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information on the business entity"
},
"latitude": {
"type": [
"number",
"null"
],
"description": "latitude coordinate of the local establishments in google maps
example:\"latitude\": 51.584091"
},
"longitude": {
"type": [
"number",
"null"
],
"description": "longitude coordinate of the local establishment in google maps
example:\"longitude\": -0.31365919999999997"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "shows whether the entity is verified by its owner on Google Maps"
},
"attributes": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataAttributesInfo"
}
],
"description": "service details in a form of user-reviewed checks;
service details of a business entity displayed in a form of checks and based on user feedback and business category"
},
"place_topics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "keywords mentioned in customer reviews
contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword
example:
\"place_topics\": {
\"egg roll\": 48,
\"birthday\": 33
}
the popularity rate based on reviews and displayed in SERP"
},
"hotel_rating": {
"type": [
"integer",
"null"
],
"description": "hotel class rating
class ratings range between 1-5 stars, learn more
if there is no hotel class rating information, the value will be null"
},
"price_level": {
"type": [
"string",
"null"
],
"description": "property price level
can take values: inexpensive, moderate, expensive, very_expensive
if there is no price level information, the value will be null"
},
"rating_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "Int64"
},
"description": "the distribution of ratings of the business entity
the object displays the number of 1-star to 5-star ratings, as reviewed by users"
},
"people_also_search": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PeopleAlsoSearch"
}
]
},
"description": "related business entities"
},
"work_time": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessWorkHoursInfo"
}
],
"description": "work time details
information related to operational hours of the business entity"
},
"popular_times": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PopularTimes"
}
],
"description": "popular times
information related to busy hours of the business entity"
},
"local_business_links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseLocalBusinessLink"
}
]
},
"description": "available interactions with the business
list of options to interact with the business directly from search results"
},
"contact_info": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataContactInfo"
}
]
},
"description": "available contacts of the business
list of contacts to interact with the business"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when the data was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2023-01-26 09:03:15 +00:00"
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the business listing element for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2023-03-11 10:04:11 +00:00"
},
"services": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataServiceInfo"
}
]
}
}
}
},
"Response463397119C53_AddressInfo": {
"type": "object",
"properties": {
"borough": {
"type": [
"string",
"null"
],
"description": "administrative unit or district the local establishment belongs to"
},
"address": {
"type": [
"string",
"null"
],
"description": "street address of the local establishment"
},
"city": {
"type": [
"string",
"null"
],
"description": "name of the city where the local establishment is located"
},
"zip": {
"type": [
"string",
"null"
],
"description": "ZIP code of the local establishment"
},
"region": {
"type": [
"string",
"null"
],
"description": "DMA region the local establishment belongs to"
},
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the local establishment"
}
}
},
"Response463397119C53_BusinessDataAttributesInfo": {
"type": "object",
"properties": {
"available_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"description": "available attributes
indicates attributes a business entity can offer"
},
"unavailable_attributes": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"description": "unavailable attributes
indicates attributes a business entity cannot offer"
}
}
},
"Response463397119C53_PeopleAlsoSearch": {
"type": "object",
"properties": {
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment
learn more about the identifier in this help center article"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the element in SERP
learn more about the identifier in this help center article"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP
the name of the business entity for which the results are collected"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element's rating
the popularity rate based on reviews and displayed in SERP"
}
}
},
"Response463397119C53_BusinessWorkHoursInfo": {
"type": "object",
"properties": {
"work_hours": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_WorkHours"
}
],
"description": "open hours
information about work hours of the local establishment"
}
}
},
"Response463397119C53_WorkHours": {
"type": "object",
"properties": {
"timetable": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_WorkDayInfo"
}
],
"description": "work hours on Sundays"
}
},
"description": "work hours timetable"
},
"current_status": {
"type": [
"string",
"null"
],
"description": "current status of the establishment
indicates whether the establishment is opened or closed"
}
}
},
"Response463397119C53_WorkDayInfo": {
"type": "object",
"properties": {
"open": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TimeInfo"
}
],
"description": "opening time"
},
"close": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TimeInfo"
}
],
"description": "closing time"
}
}
},
"Response463397119C53_TimeInfo": {
"type": "object",
"properties": {
"hour": {
"type": [
"integer",
"null"
],
"description": "hours in the 24-hour format"
},
"minute": {
"type": [
"integer",
"null"
],
"description": "minutes"
}
}
},
"Response463397119C53_PopularTimes": {
"type": "object",
"properties": {
"popular_times_by_days": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PopularWorkTimeInfo"
}
],
"description": "work hours on Sundays"
}
},
"description": "popular hours
information about busy hours of the local establishment on each day of the week"
}
}
},
"Response463397119C53_PopularWorkTimeInfo": {
"type": "object",
"properties": {
"time": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TimeInfo"
}
],
"description": "hours in the 24-hour format"
},
"popular_index": {
"type": [
"integer",
"null"
],
"description": "popularity index\nrelative time-bound popularity index measured from 0 to 100;\nhigher value corresponds to a busier time of a day"
}
}
},
"Response463397119C53_BaseLocalBusinessLink": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"reservation": "#/components/schemas/Response463397119C53_LocalBusinessReservationLink",
"order": "#/components/schemas/Response463397119C53_LocalBusinessOrderLink",
"menu": "#/components/schemas/Response463397119C53_LocalBusinessMenuLink"
}
}
},
"Response463397119C53_LocalBusinessReservationLink": {
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseLocalBusinessLink"
},
{
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element\ndomain of the reservation software"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to make a reservation"
}
}
}
]
},
"Response463397119C53_LocalBusinessOrderLink": {
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseLocalBusinessLink"
},
{
"properties": {
"delivery_services": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocalBusinessDeliveryServiceInfo"
}
]
},
"description": "lists available delivery services"
}
}
}
]
},
"Response463397119C53_LocalBusinessDeliveryServiceInfo": {
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element\ndomain of the online food ordering system"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to place an order"
}
}
},
"Response463397119C53_LocalBusinessMenuLink": {
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseLocalBusinessLink"
},
{
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element\ndomain of the online menu system"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to view the menu"
}
}
}
]
},
"Response463397119C53_BusinessDataContactInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"value": {
"type": [
"string",
"null"
],
"description": "the value of the rating"
},
"source": {
"type": [
"string",
"null"
],
"description": "data source"
}
}
},
"Response463397119C53_BusinessDataServiceInfo": {
"type": "object",
"properties": {
"category": {
"type": [
"string",
"null"
],
"description": "business category
Google My Business general category that best describes the services provided by the business entity"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP
the name of the business entity for which the results are collected"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information on the business entity"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
]
}
}
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleExtendedReviewsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleExtendedReviewsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the 'reviews' element in SERP
the name of the local establishment for which the reviews are collected"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "subtitle of the 'reviews' element in SERP
additional information (e.g., address) on the 'reviews' element for which the reviews are collected"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the corresponding local establishment
popularity rate based on reviews and displayed in SERP"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the 'reviews' element in SERP
learn more about the identifier in this help center article"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "unique identifier of a business location assigned by Google
learn more about the identifier in this help center article"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment
learn more about the identifier in this help center article"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleExtendedReviewsSearch"
}
]
},
"description": "found reviews
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_GoogleExtendedReviewsSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the review"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "the content of the review"
},
"original_review_text": {
"type": [
"string",
"null"
],
"description": "original content of the review
the original content of the review, no auto-translate applied"
},
"time_ago": {
"type": [
"string",
"null"
],
"description": "the time of publication
indicates the time (in the 'time ago' format) when the review was listed"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when a review was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "total number of reviews submitted by the reviewer",
"format": "int64"
},
"photos_count": {
"type": [
"integer",
"null"
],
"description": "total number of photos submitted by the reviewer",
"format": "int64"
},
"local_guide": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the reviewer has a 'local guide' status"
},
"profile_name": {
"type": [
"string",
"null"
],
"description": "profile name of the reviewer"
},
"profile_url": {
"type": [
"string",
"null"
],
"description": "URL of the reviewer's profile"
},
"review_url": {
"type": [
"string",
"null"
],
"description": "the URL of the review"
},
"profile_image_url": {
"type": [
"string",
"null"
],
"description": "URL of the reviewer's profile image"
},
"owner_answer": {
"type": [
"string",
"null"
],
"description": "text of the owner's response
the owner's response to the review"
},
"original_owner_answer": {
"type": [
"string",
"null"
],
"description": "original text of the owner's response
the original response to the review, no auto-translate applied"
},
"owner_time_ago": {
"type": [
"string",
"null"
],
"description": "publication time
indicates the time (in the 'time ago' format) when the owner submitted the response to the review"
},
"owner_timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the owner's reply to the review
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"review_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of a review on Google
example:ChZDSUhNMG9nS0VJQ0FnSUMxbHFyMFlnEAE"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images submitted by the reviewer"
},
"review_highlights": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ReviewHighlights"
}
]
},
"description": "review highlights
contains highlighted review criteria and assessments"
},
"source": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Source"
}
],
"description": "source of the review
contains information about the source where the review was posted"
}
}
},
"Response463397119C53_AiModeImagesElementInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"alt": {
"type": [
"string",
"null"
],
"description": "alt tag of the image"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
}
}
},
"Response463397119C53_ReviewHighlights": {
"type": "object",
"properties": {
"feature": {
"type": [
"string",
"null"
],
"description": "reviewed feature"
},
"assessment": {
"type": [
"string",
"null"
],
"description": "feature assessment"
}
}
},
"Response463397119C53_Source": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "name of the source where the review was posted"
},
"image": {
"type": [
"string",
"null"
],
"description": "featured image of the source"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the source where the review was posted"
}
}
},
"Provider463397119C53_BusinessDataGoogleExtendedReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field if you don't specify cid or place_id
the keyword you specify should indicate the name of the local establishment;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation errorkeyword and keywords fields in DataForSEO APIs in this Help Center article
required field if you don't specify keyword or place_id
example:194604053573767737
learn more about the identifier in this help center article
required field if you don't specify keyword or cid
example:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the identifier in this help center article
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews in SERP
we strongly recommend setting the parsing depth in the multiples of twenty, because our systems processes twenty reviews in a row
default value: 20
maximum value: 1000
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleExtendedReviewsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleExtendedReviewsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleExtendedReviewsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_BusinessDataGoogleHotelInfoLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"hotel_identifier": {
"type": "string",
"description": "unique hotel identifier
required field
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels element of the response), or the Hotel Searches endpoint of Business Data API
example:ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude, longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
the value must not be earlier than today's date
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, two adults will be used by default
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:[13,8]"
},
"load_prices_by_dates": {
"type": [
"boolean",
"null"
],
"description": "load hotel stay prices by dates
optional field
if you specify this parameter with true, the response will include the prices_by_dates array with hotel stay prices divided by dates
if you use this parameter, you will be charged double the base price for a request"
},
"prices_start_date": {
"type": [
"string",
"null"
],
"description": "start date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, the start date is set to check_in date
date format: yyyy-mm-dd
example:2025-05-20"
},
"prices_end_date": {
"type": [
"string",
"null"
],
"description": "end date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, you will get prices by date for the month
date format: yyyy-mm-dd
example:2025-05-21"
},
"prices_date_range": {
"type": [
"string",
"null"
],
"description": "predefined period for retrieving daily price data
optional field
to use this parameter, you must specify load_prices_by_dates with true
if the prices_start_date is not specified, the start date is set to check_in date
possible values: month, three_months, six_months, year
default value: month"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "CgoI-KWyzenM_MV3EAE"
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"hotel_identifier": {
"type": [
"string",
"null"
],
"description": "identifier received in a POST array
this field will contain the hotel_identifier parameter specified when setting a task;
example:CgoI-KWyzenM_MV3EAE"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "hotel title
the title of the hotel entity for which the results are collected"
},
"stars": {
"type": [
"integer",
"null"
],
"description": "hotel class rating
class rating that ranges between 1-5 stars and displayed after review ratings in hotel summary"
},
"stars_description": {
"type": [
"string",
"null"
],
"description": "hotel class rating
class rating that ranges between 1-5 stars and displayed after review ratings in the hotel summary"
},
"address": {
"type": [
"string",
"null"
],
"description": "hotel address
physical address of the hotel"
},
"phone": {
"type": [
"string",
"null"
],
"description": "hotel phone number
contact phone number of the hotel"
},
"about": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelAboutInfo"
}
],
"description": "information about the hotel"
},
"location": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelLocationInfo"
}
],
"description": "information about the hotel location
information about the location where the hotel is located"
},
"reviews": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelReviewInfo"
}
],
"description": "hotel reviews by criteria
information about reviews of the hotel entity"
},
"overview_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "images displayed in the hotel overview
array containing URLs to images displayed in the hotel overview"
},
"prices": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelPriceInfo"
}
],
"description": "pricing details of the hotel entity
contains information about the hotel's prices"
}
}
},
"Response463397119C53_HotelAboutInfo": {
"type": "object",
"properties": {
"description": {
"type": [
"string",
"null"
],
"description": "description of the hotel
the description of the hotel entity for which the results are collected"
},
"sub_descriptions": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "additional description of the hotel
details about the hotel provided in addition to the description"
},
"check_in_time": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TimeInfo"
}
],
"description": "hotel check-in time
check-in time indicated in the hotel listing"
},
"check_out_time": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TimeInfo"
}
],
"description": "hotel check-out time
check-out time indicated in the hotel listing"
},
"full_address": {
"type": [
"string",
"null"
],
"description": "full address of the hotel
address of the hotel indicated in the standardised format"
},
"domain": {
"type": [
"string",
"null"
],
"description": "hotel domain
domain of the hotel's website"
},
"url": {
"type": [
"string",
"null"
],
"description": "hotel url
URL to the hotel's website indicated in the listing"
},
"amenities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelAmenityInfo"
}
]
},
"description": "hotel amenities
information about hotel amenities"
},
"popular_amenities": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelAmenityItemInfo"
}
]
},
"description": "hotel amenities
information about hotel amenities labelled as \"popular\""
}
}
},
"Response463397119C53_HotelAmenityInfo": {
"type": "object",
"properties": {
"category": {
"type": [
"string",
"null"
],
"description": "standardised category of the ammenity"
},
"category_label": {
"type": [
"string",
"null"
],
"description": "label of the category"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelAmenityItemInfo"
}
]
},
"description": "specific amenities and details"
}
}
},
"Response463397119C53_HotelAmenityItemInfo": {
"type": "object",
"properties": {
"amenity": {
"type": [
"string",
"null"
],
"description": "standardised amenity name"
},
"amenity_label": {
"type": [
"string",
"null"
],
"description": "displayed amenity name"
},
"hint": {
"type": [
"string",
"null"
],
"description": "standardised details about the amenity"
},
"hint_label": {
"type": [
"string",
"null"
],
"description": "displayed details about the amenity"
},
"is_available": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the amenity is available in the hotel"
}
}
},
"Response463397119C53_HotelLocationInfo": {
"type": "object",
"properties": {
"neighborhood": {
"type": [
"string",
"null"
],
"description": "name of the neighborhood where the hotel is located"
},
"neighborhood_description": {
"type": [
"string",
"null"
],
"description": "description of the neighborhood where the hotel is located"
},
"maps_url": {
"type": [
"string",
"null"
],
"description": "url to the location of the hotel in google maps"
},
"overall_score": {
"type": [
"number",
"null"
],
"description": "overall score of the hotel location
indicates the overall score of the hotel's location in the range from 1 to 5;
calculated based on data from the hotel's proximity to nearby things to do and restaurants, transportation, and airports;
note that the criteria are not weighted equally in the overall score"
},
"score_by_categories": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"number",
"null"
],
"format": "double"
},
"description": "category scores of the hotel location
the scores of the hotel's location tied to the categories that indicate the proximity to nearby things to do, restaurants, transportation, and airports;"
},
"latitude": {
"type": [
"number",
"null"
],
"description": "hotel latitude
latitude coordinates of the hotel's location
example:39.4806397"
},
"longitude": {
"type": [
"number",
"null"
],
"description": "hotel longitude
latitude coordinates of the hotel's location
example:-106.0512973"
},
"location_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocationChain"
}
]
},
"description": "elements of the location chain
additional parameters of each element of the location chain"
}
}
},
"Response463397119C53_LocationChain": {
"type": "object",
"properties": {
"card_id": {
"type": [
"string",
"null"
],
"description": "card identifier"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "feature identifier
learn more about the identifier in this help center article"
},
"cid": {
"type": [
"string",
"null"
],
"description": "client id
learn more about the identifier in this help center article"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in the location chain"
}
}
},
"Response463397119C53_HotelReviewInfo": {
"type": "object",
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "overall hotel rating based on customer votes"
},
"votes_count": {
"type": [
"integer",
"null"
],
"description": "number of customer votes
the number of customer votes included in the calculation of the hotel rating",
"format": "int64"
},
"mentions": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ReviewMentionInfo"
}
]
},
"description": "hotel mentions
information about hotel reviews by criteria"
},
"rating_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "Int64"
},
"description": "rating distribution by votes
the distribution of votes across the rating in the range from 1 to 5"
},
"other_sites_reviews": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OtherSitesReviewsInfo"
}
]
},
"description": "reviews on third-party sites
reviews from third-party sites"
}
}
},
"Response463397119C53_ReviewMentionInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the evaluated criterion"
},
"positive_score": {
"type": [
"number",
"null"
],
"description": "positive score by criterion"
},
"positive_count": {
"type": [
"integer",
"null"
],
"description": "count of positive reviews by criterion",
"format": "int64"
},
"negative_count": {
"type": [
"integer",
"null"
],
"description": "count of negative reviews by criterion",
"format": "int64"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "count of all reviews by criterion",
"format": "int64"
},
"visible_by_default": {
"type": [
"boolean",
"null"
],
"description": "element is visible by default
indicates whether the review element is visible by default"
}
}
},
"Response463397119C53_OtherSitesReviewsInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "review title
contains a name of the third-party site where review initially appeared"
},
"url": {
"type": [
"string",
"null"
],
"description": "review url
URL to the a third-party site where review initially appeared"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "review text
text of the review"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating in the review
information about the rating enclosed in the review on a third-party site"
}
}
},
"Response463397119C53_HotelPriceInfo": {
"type": "object",
"properties": {
"price": {
"type": [
"number",
"null"
],
"description": "price per night"
},
"price_without_discount": {
"type": [
"number",
"null"
],
"description": "full price per night without a discount applied",
"format": "int64"
},
"currency": {
"type": [
"string",
"null"
],
"description": "price currencyUSD is applied by default, unless specified in the POST array"
},
"discount_text": {
"type": [
"string",
"null"
],
"description": "text about a discount applied"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date and time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date and time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"visitors": {
"type": [
"integer",
"null"
],
"description": "number of hotel visitors for this price"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelPriceItemInfo"
}
]
},
"description": "encountered item types
types of search engine results encountered in the items array;
possible item types: hotel_search_item"
},
"prices_by_dates": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PricesByDates"
}
]
}
}
}
},
"Response463397119C53_HotelPriceItemInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the hotel"
},
"price": {
"type": [
"number",
"null"
],
"description": "price per night"
},
"currency": {
"type": [
"string",
"null"
],
"description": "price currencyUSD is applied by default, unless specified in the POST array"
},
"url": {
"type": [
"string",
"null"
],
"description": "third-party page url\nURL to the third-party website page with pricing information"
},
"domain": {
"type": [
"string",
"null"
],
"description": "third-party domain\ndomain of the third-party website page with pricing information"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates a paid hotel listing
if true, related hotel_search_item is a paid ad
if false, related hotel_search_item is an organic hotel listing"
},
"official_site": {
"type": [
"boolean",
"null"
]
},
"free_cancellation_until": {
"type": [
"string",
"null"
],
"description": "date until which free cancellation is available\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nequals null if free cancellation is not available for the selected dates"
},
"offers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelInfoPriceOffer"
}
]
}
}
}
},
"Response463397119C53_HotelInfoPriceOffer": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the hotel"
},
"price": {
"type": [
"number",
"null"
],
"description": "price per night"
},
"currency": {
"type": [
"string",
"null"
],
"description": "price currencyUSD is applied by default, unless specified in the POST array"
},
"url": {
"type": [
"string",
"null"
],
"description": "url of the price offer\nURL to the page of the website where price offer appears"
},
"max_visitors": {
"type": [
"integer",
"null"
],
"description": "the maximal number of visitors\nthe maximum number of visitors for which the price offer is valid"
},
"offer_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "price offer images\nURLs of the images featured in the price offer"
},
"free_cancellation_until": {
"type": [
"string",
"null"
],
"description": "date until free cancellation is available\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nequals null if free cancellation is not available for the selected dates"
}
},
"description": "featured price offers"
},
"Response463397119C53_PricesByDates": {
"type": "object",
"properties": {
"price": {
"type": [
"number",
"null"
],
"description": "price per night"
},
"currency": {
"type": [
"string",
"null"
],
"description": "price currencyUSD is applied by default, unless specified in the POST array"
},
"check_in_date": {
"type": [
"string",
"null"
]
},
"check_out_date": {
"type": [
"string",
"null"
]
}
}
},
"Provider463397119C53_BusinessDataGoogleHotelInfoLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"hotel_identifier": {
"type": "string",
"description": "unique hotel identifier
required field
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels element of the response), or the Hotel Searches endpoint of Business Data API
example:ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, two adults will be used by default
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:[13,8]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data array of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "unique hotel identifier specified as \"hotel_id:$\""
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
]
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages"
}
}
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"hotel_identifier": {
"type": [
"string",
"null"
],
"description": "unique hotel identifier
this field will contain the hotel_identifier parameter;
example:CgoI-KWyzenM_MV3EAE"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "hotel title
the title of the hotel entity for which the results are collected"
},
"stars": {
"type": [
"integer",
"null"
],
"description": "hotel class rating
class rating that ranges between 1-5 stars and displayed after review ratings in hotel summary"
},
"stars_description": {
"type": [
"string",
"null"
],
"description": "hotel class rating
class rating that ranges between 1-5 stars and displayed after review ratings in the hotel summary"
},
"address": {
"type": [
"string",
"null"
],
"description": "hotel address
physical address of the hotel"
},
"phone": {
"type": [
"string",
"null"
],
"description": "hotel phone number
contact phone number of the hotel"
},
"about": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelAboutInfo"
}
],
"description": "information about the hotel"
},
"location": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelLocationInfo"
}
],
"description": "information about the hotel location
information about the location where the hotel is located"
},
"reviews": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelReviewInfo"
}
],
"description": "hotel reviews by criteria
information about reviews of the hotel entity"
},
"overview_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "images displayed in the hotel overview
array containing URLs to images displayed in the hotel overview"
},
"prices": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelPriceInfo"
}
],
"description": "pricing details of the hotel entity
contains information about the hotel's prices"
}
}
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
]
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
]
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages"
}
}
},
"Provider463397119C53_BusinessDataGoogleHotelInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"hotel_identifier": {
"type": "string",
"description": "unique hotel identifier
required field if you don't specify keyword
if you use this field, you don't need to specify keyword
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels_pack element of the response), or the Hotel Searches endpoint of Business Data API
example:ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
},
"keyword": {
"type": "string",
"description": "keyword
required field if you don't specify hotel_identifier
if you use this field, you don't need to specify hotel_identifier
the keyword you specify should indicate the name of the hotel entity
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
the value must not be earlier than today's date
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, two adults will be used by default
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:[13,8]"
},
"load_prices_by_dates": {
"type": [
"boolean",
"null"
],
"description": "load hotel stay prices by dates
optional field
if you specify this parameter with true, the response will include the prices_by_dates array with hotel stay prices divided by dates
if you use this parameter, you will be charged double the base price for a request"
},
"prices_start_date": {
"type": [
"string",
"null"
],
"description": "start date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, the start date is set to check_in date
date format: yyyy-mm-dd
example:2025-05-20"
},
"prices_end_date": {
"type": [
"string",
"null"
],
"description": "end date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, you will get prices by date for the month
date format: yyyy-mm-dd
example:2025-05-21"
},
"prices_date_range": {
"type": [
"string",
"null"
],
"description": "predefined period for retrieving daily price data
optional field
to use this parameter, you must specify load_prices_by_dates with true
if the prices_start_date is not specified, the start date is set to check_in date
possible values: month, three_months, six_months, year
default value: month"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255;
you can use this parameter to identify the task and match it with the result;
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified;
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request;
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified;
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable;
we will set the necessary values before sending the request;
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelInfoTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelInfoTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_BusinessDataGoogleHotelSearchesLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
optional field
the keyword you specify is used to search for the list of hotels;
if you don't use this field, we will return the list of hotels found in a specified location;
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
Note: in order to obtain accurate search results, the location name is appended to the keyword automaticallykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom
Note: in order to obtain accurate search results, the location_name you specify will be automatically appended to the keyword"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement
example:53.476225,-2.243572n"
},
"search_this_area": {
"type": [
"boolean",
"null"
],
"description": "show hotels from the displayed area
optional field
can take the values: true, false
default value: true
if set to false the search_this_area mode will be turned off
Note: if the search_this_area mode is turned off, the location_name won't be appended to the keyword during search
learn more about this parameter on our Help Center"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in Google Hotels
default value: 18 organic results
max value: 140
Note: your account will be billed per each 18 organic results regardless of paid listings in the response;
thus, setting a depth above 18 may result in additional charges if Google Hotels return more than 18 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot precede the today's date"
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, the default value of 2 will be applied;
note that you can specify up to 6 persons including both adults and children
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;
age of child can be from 0 to 17;
note that you can specify up to 6 persons including both adults and children
set the following value if you want to include one 14-year-old child:[14]
set the following value if you want to include one 13-year-old child and one 8-year-old child:[13,8]"
},
"stars": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel stars
optional field
set this field to [5] if you want to get the list of 5-star hotels only
example:[3,4,5]"
},
"min_rating": {
"type": [
"number",
"null"
],
"description": "minimum rating
optional field
you can use this field to specify guest rating higher than a certain value
example:2.5"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:relevance – sort by most relevantlowest_price – sort by the lowest pricehighest_rating – sort by highest ratingmost_reviewed – sort by most reviewed
default value: relevance"
},
"min_price": {
"type": [
"integer",
"null"
],
"description": "minimum price per night
optional field
the currency of this value depends on the currency field
example:100"
},
"max_price": {
"type": [
"integer",
"null"
],
"description": "maximum price per night
optional field
the currency of this value depends on the currency field
example:600"
},
"free_cancellation": {
"type": [
"boolean",
"null"
],
"description": "hotels with a free cancellation
optional field
set this field to true if you want to get the list of hotels with free cancellation of reservations
default value: false"
},
"is_vacation_rentals": {
"type": [
"boolean",
"null"
],
"description": "search for vacation rentals
optional field
set this field to true if you want to get the list of vacation rentals instead of hotels
default value: false"
},
"amenities": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel amenities
optional field
you can use this field to specify different hotel amenities
example: [
\"free_parking\",
\"pets_allowed\"
]
possible values:
`\"air_conditioning\",
\"all_inclusive_available\",
\"bar\",
\"free_breakfast\",
\"fitness_center\",
\"kid_friendly\",
\"free_parking\",
\"pets_allowed\",
\"pool\",
\"restaurant\",
\"room_service\",
\"spa\",
\"free_wifi\",
\"parking\",
\"indoor_pool\",
\"outdoor_pool\",
\"wheelchair_accessible\",
\"beach_access\"`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "cheap hotel",
"check_in": "2023-06-01",
"check_out": "2023-06-30",
"currency": "USD",
"adults": 2,
"children": [
"14"
],
"sort_by": "highest_rating",
"priority": 2,
"tag": "example"
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "item types
the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesItem"
}
]
},
"description": "encountered item types
types of search engine results encountered in the items array;
possible item types: hotel_search_item"
}
}
},
"Response463397119C53_BusinessDataGoogleHotelSearchesItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"hotel_identifier": {
"type": [
"string",
"null"
],
"description": "unique identifier of a hotel entity in Google search
example:CgoI-KWyzenM_MV3EAE"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the hotel"
},
"stars": {
"type": [
"integer",
"null"
],
"description": "hotel class rating
class rating that ranges between 1-5 stars"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates a paid hotel listing
if true, related hotel_search_item is a paid ad
if false, related hotel_search_item is an organic hotel listing"
},
"location": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GpsCoordinatesLocationInfo"
}
],
"description": "GPS coordinates of the hotel's location"
},
"reviews": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelReviewInfo"
}
],
"description": "hotel reviews and rating information"
},
"overview_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "featured images for a hotel"
},
"prices": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelPriceInfo"
}
],
"description": "hotel price"
}
}
},
"Response463397119C53_GpsCoordinatesLocationInfo": {
"type": "object",
"properties": {
"latitude": {
"type": [
"number",
"null"
],
"description": "latitude coordinate of the hotel in google maps
example:\"latitude\": 51.584091"
},
"longitude": {
"type": [
"number",
"null"
],
"description": "longitude coordinate of the hotel in google maps
example:\"longitude\": -0.31365919999999997"
}
}
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character);
in order to obtain accurate search results, the location name is appended to the keyword automatically"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "item types
the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesItem"
}
]
},
"description": "array of items
note: this field always equals null; use it to facilitate integration and ensure interoperability with the Hotel Info endpoint"
}
}
},
"Provider463397119C53_BusinessDataGoogleHotelSearchesTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
optional field
the keyword you specify is used to search for the list of hotels;
if you don't use this field, we will return the list of hotels found in a specified location;
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
Note: in order to obtain accurate search results, the location name is appended to the keyword automaticallykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom
Note: in order to obtain accurate search results, the location_name you specify will be automatically appended to the keyword"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572"
},
"search_this_area": {
"type": [
"boolean",
"null"
],
"description": "show hotels from the displayed area
optional field
can take the values: true, false
default value: true
if set to false the search_this_area mode will be turned off
Note: if the search_this_area mode is turned off, the location_name won't be appended to the keyword during search
learn more about this parameter on our Help Center"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in Google Hotels
default value: 18 organic results
max value: 140
Note: your account will be billed per each 18 organic results regardless of paid listings in the response;
thus, setting a depth above 18 may result in additional charges if Google Hotels return more than 18 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot precede the today's date"
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, the default value of 2 will be applied;
note that you can specify up to 6 persons including both adults and children
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;
age of child can be from 0 to 17;
note that you can specify up to 6 persons including both adults and children
set the following value if you want to include one 14-year-old child:[14]
set the following value if you want to include one 13-year-old child and one 8-year-old child:[13,8]"
},
"stars": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel stars
optional field
set this field to [5] if you want to get the list of 5-star hotels only
example:[3,4,5]"
},
"min_rating": {
"type": [
"number",
"null"
],
"description": "minimum rating
optional field
you can use this field to specify guest rating higher than a certain value
example:2.5"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:relevance – sort by most relevantlowest_price – sort by the lowest pricehighest_rating – sort by highest ratingmost_reviewed – sort by most reviewed
default value: relevance"
},
"min_price": {
"type": [
"integer",
"null"
],
"description": "minimum price per night
optional field
the currency of this value depends on the currency field
example:100"
},
"max_price": {
"type": [
"integer",
"null"
],
"description": "maximum price per night
optional field
the currency of this value depends on the currency field
example:600"
},
"free_cancellation": {
"type": [
"boolean",
"null"
],
"description": "hotels with a free cancellation
optional field
set this field to true if you want to get the list of hotels with free cancellation of reservations
default value: false"
},
"is_vacation_rentals": {
"type": [
"boolean",
"null"
],
"description": "search for vacation rentals
optional field
set this field to true if you want to get the list of vacation rentals instead of hotels
default value: false"
},
"amenities": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel amenities
optional field
you can use this field to specify different hotel amenities
example: [
\"free_parking\",
\"pets_allowed\"
]
possible values:\"air_conditioning\","
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
\"all_inclusive_available\",
\"bar\",
\"free_breakfast\",
\"fitness_center\",
\"kid_friendly\",
\"free_parking\",
\"pets_allowed\",
\"pool\",
\"restaurant\",
\"room_service\",
\"spa\",
\"free_wifi\",
\"parking\",
\"indoor_pool\",
\"outdoor_pool\",
\"wheelchair_accessible\",
\"beach_access\"
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleHotelSearchesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleHotelSearchesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID \nformat"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_BusinessDataGoogleMyBusinessInfoLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)
this field will contain the cid parameter if you specified it in the keyword field when setting a task;
example:cid:2946633002421908862
learn more about the parameter in this help center article"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain as specified in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "item types
types of search engine results encountered in the items array;
possible item types: google_business_info"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "item types
the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessInfo"
}
]
},
"description": "encountered item types
types of search engine results encountered in the items array;
possible item types: google_business_info"
}
}
},
"Response463397119C53_GoogleBusinessInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the elements"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP
the name of the business entity for which the results are collected"
},
"original_title": {
"type": [
"string",
"null"
],
"description": "original title of the element
original title not translated by Google"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the element in SERP
the description of the business entity for which the results are collected"
},
"category": {
"type": [
"string",
"null"
],
"description": "business category
Google My Business general category that best describes the services provided by the business entity"
},
"category_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "global category IDs
universal category IDs that do not change based on the selected country"
},
"additional_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "additional business categories
additional Google My Business categories that describe the services provided by the business entity in more detail"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment;
can be used with Google Reviews API to get a full list of reviews
learn more about the identifier in this help center article"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the element in SERP
learn more about the identifier in this help center article"
},
"address": {
"type": [
"string",
"null"
],
"description": "address of the business entity"
},
"address_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AddressInfo"
}
],
"description": "object containing address components of the business entity"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "unique place identifier
place id of the local establishment featured in the element
learn more about the identifier in this help center article"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number of the business entity"
},
"url": {
"type": [
"string",
"null"
],
"description": "absolute url of the business entity"
},
"contact_url": {
"type": [
"string",
"null"
],
"description": "URL of the preferred contact page"
},
"contributor_url": {
"type": [
"string",
"null"
],
"description": "URL of the user's or entity's Local Guides profile, if available"
},
"book_online_url": {
"type": [
"string",
"null"
],
"description": "URL in the 'book online' button of the element
URL directing users to the online booking or order page of the business entity"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the business entity"
},
"logo": {
"type": [
"string",
"null"
],
"description": "URL of the logo featured in Google My Business profile"
},
"main_image": {
"type": [
"string",
"null"
],
"description": "URL of the main image featured in Google My Business profile"
},
"total_photos": {
"type": [
"integer",
"null"
],
"description": "total count of images featured in Google My Business profile",
"format": "int64"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information on the business entity"
},
"latitude": {
"type": [
"number",
"null"
],
"description": "latitude coordinate of the local establishments in google maps
example:\"latitude\": 51.584091"
},
"longitude": {
"type": [
"number",
"null"
],
"description": "longitude coordinate of the local establishment in google maps
example:\"longitude\": -0.31365919999999997"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "shows whether the entity is verified by its owner on Google Maps"
},
"questions_and_answers_count": {
"type": [
"integer",
"null"
]
},
"attributes": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataAttributesInfo"
}
],
"description": "service details in a form of user-reviewed checks;
service details of a business entity displayed in a form of checks and based on user feedback and business category"
},
"place_topics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "keywords mentioned in customer reviews
contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword
example:
\"place_topics\": {
\"egg roll\": 48,
\"birthday\": 33
}
the popularity rate based on reviews and displayed in SERP"
},
"hotel_rating": {
"type": [
"number",
"null"
],
"description": "hotel class rating
class ratings range between 1-5 stars, learn more
if there is no hotel class rating information, the value will be null"
},
"price_level": {
"type": [
"string",
"null"
],
"description": "property price level
can take values: inexpensive, moderate, expensive, very_expensive
if there is no price level information, the value will be null"
},
"rating_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "Int64"
},
"description": "the distribution of ratings of the business entity
the object displays the number of 1-star to 5-star ratings, as reviewed by users"
},
"people_also_search": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PeopleAlsoSearch"
}
]
},
"description": "related business entities"
},
"work_time": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessWorkHoursInfo"
}
],
"description": "work time details
information related to operational hours of the business entity"
},
"popular_times": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PopularTimes"
}
],
"description": "popular times
information related to busy hours of the business entity"
},
"local_business_links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseLocalBusinessLink"
}
]
},
"description": "available interactions with the business
list of options to interact with the business directly from search results"
},
"is_directory_item": {
"type": [
"boolean",
"null"
],
"description": "business establishment is a part of the directory
indicates whether the business establishment is a part of the directory;
if true, the item is a part of the larger directory of businesses with the same address (e.g., a mall or a business centre);
note: if the business establishment is a parent item in the directory, the value will be null"
},
"directory": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDirectoryInfo"
}
],
"description": "items of the directory
includes information about businesses that are located within the target business establishment and have the same address"
},
"services": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataServiceInfo"
}
]
},
"description": "list of services offered by the business"
}
}
},
"Response463397119C53_BusinessDirectoryInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element
domain of the online menu system"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MapsSearch"
}
]
},
"description": "encountered item types
types of search engine results encountered in the items array;
possible item types: google_business_info"
}
}
},
"Response463397119C53_MapsSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from the rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the elements"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the business entity"
},
"title": {
"type": [
"string",
"null"
],
"description": "directory title
can take the following values: At this place, Directory"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to view the menu"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element's rating
the popularity rate based on reviews and displayed in SERP"
},
"rating_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "Int64"
},
"description": "the distribution of ratings of the business entity\nthe object displays the number of 1-star to 5-star ratings, as reviewed by users"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information about the business entity"
},
"address": {
"type": [
"string",
"null"
],
"description": "address of the business entity"
},
"address_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AddressInfo"
}
],
"description": "object containing address components of the business entity"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "unique place identifier
place id of the local establishment featured in the element
learn more about the identifier in this help center article"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number of the business entity"
},
"main_image": {
"type": [
"string",
"null"
],
"description": "URL of the main image featured in Google My Business profile"
},
"total_photos": {
"type": [
"string",
"null"
],
"description": "total count of images featured in Google My Business profile",
"format": "int64"
},
"category": {
"type": [
"string",
"null"
],
"description": "business category
Google My Business general category that best describes the services provided by the business entity"
},
"additional_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "additional business categories
additional Google My Business categories that describe the services provided by the business entity in more detail"
},
"price_level": {
"type": [
"string",
"null"
],
"description": "property price level
can take values: inexpensive, moderate, expensive, very_expensive
if there is no price level information, the value will be null"
},
"hotel_rating": {
"type": [
"string",
"null"
],
"description": "hotel class rating
class ratings range between 1-5 stars, learn more
if there is no hotel class rating information, the value will be null"
},
"category_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "global category IDs
universal category IDs that do not change based on the selected country"
},
"work_hours": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessWorkHoursInfo"
}
],
"description": "open hours
information about work hours of the local establishment"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the element in SERP
learn more about the identifier in this help center article"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment;
can be used with Google Reviews API to get a full list of reviews
learn more about the identifier in this help center article"
},
"latitude": {
"type": [
"number",
"null"
],
"description": "latitude coordinate of the local establishments in google maps
example:\"latitude\": 51.584091"
},
"longitude": {
"type": [
"number",
"null"
],
"description": "longitude coordinate of the local establishment in google maps
example:\"longitude\": -0.31365919999999997"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "shows whether the entity is verified by its owner on Google Maps"
},
"local_justifications": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Google local justifications
snippets of text that “justify” why the business is showing up for search query"
},
"is_directory_item": {
"type": [
"boolean",
"null"
],
"description": "business establishment is a part of the directory
indicates whether the business establishment is a part of the directory;
if true, the item is a part of the larger directory of businesses with the same address (e.g., a mall or a business centre);
note: if the business establishment is a parent item in the directory, the value will be null"
}
}
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)
this field will contain the cid parameter if you specified it in the keyword field when setting a task;
example:cid:2946633002421908862
learn more about the parameter in this help center article"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain as specified in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "item types
types of search engine results encountered in the items array;
possible item types: google_business_info"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "item types
the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessInfo"
}
]
},
"description": "array of directory items"
}
}
},
"Provider463397119C53_BusinessDataGoogleMyBusinessInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessInfoTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessInfoTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)
this field will contain the cid parameter if you specified it in the keyword field when setting a task;
example:cid:2946633002421908862
learn more about the parameter in this help center article"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain as specified in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"business_updates_id": {
"type": [
"string",
"null"
],
"description": "identifier of the business updates element in SERP"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment
learn more about the cid identifier in this help center article"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the element in SERP
learn more about the identifier in this help center article"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "item types
types of search engine results encountered in the items array;
possible item types: google_business_post"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "item types
the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessPost"
}
]
},
"description": "encountered item types
types of search engine results encountered in the items array;
possible item types: google_business_post"
}
}
},
"Response463397119C53_GoogleBusinessPost": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed updates
absolute position among all present elements"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values: right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"author": {
"type": [
"string",
"null"
],
"description": "author of the post"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional content of a post"
},
"post_text": {
"type": [
"string",
"null"
],
"description": "main content of a post"
},
"url": {
"type": [
"string",
"null"
],
"description": "url of a post"
},
"images_url": {
"type": [
"string",
"null"
],
"description": "url of an image included in the post"
},
"post_date": {
"type": [
"string",
"null"
],
"description": "date when a post was published
in the following format:\"mm/dd/yyyy hh:mm:ss\""
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "time when a post was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "links included in the post"
}
}
},
"Response463397119C53_LinkElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
}
},
"Provider463397119C53_BusinessDataGoogleMyBusinessUpdatesTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;this field can also be used to pass cid (unique, google-defined id of the business entity) or place_id (identifier of the business entity in Google Maps) parameters
example:cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of updates in SERP
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten updates in a row
please note that Google returns 4490 updates maximum
default value: 10"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleMyBusinessUpdatesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_BusinessDataGoogleQuestionsAndAnswersLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 20
max value: 100
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "Los Angeles,California,United States",
"keyword": "The Last Bookstore"
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)
this field will contain the cid parameter if you specified it in the keyword field when setting a task;
example:cid:2946633002421908862
learn more about the parameter in this help center article"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain as specified in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment;
learn more about the identifier in this help center article"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": " unique identifier of the SERP feature"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "item types
types of search engine results encountered in the items array;
possible item types: google_business_question_item"
},
"items_without_answers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessQuestionItem"
}
]
},
"description": "array of google business question items without answers"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessQuestionItem"
}
]
},
"description": "array of items
items within google_business_question_item"
}
}
},
"Response463397119C53_GoogleBusinessQuestionItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the elements"
},
"question_id": {
"type": [
"string",
"null"
],
"description": "ID of the question"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the question"
},
"profile_image_url": {
"type": [
"string",
"null"
],
"description": "URL of the user's profile image"
},
"profile_url": {
"type": [
"string",
"null"
],
"description": "URL of the user's profile"
},
"profile_name": {
"type": [
"string",
"null"
],
"description": "displayed name of the user"
},
"question_text": {
"type": [
"string",
"null"
],
"description": "current text of the question"
},
"original_question_text": {
"type": [
"string",
"null"
],
"description": "original text of the question"
},
"time_ago": {
"type": [
"string",
"null"
],
"description": "estimated time when the question was posted"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "exact time when the question was posted"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessAnswerElement"
}
]
},
"description": "array of items
items within google_business_question_item"
}
}
},
"Response463397119C53_GoogleBusinessAnswerElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"answer_id": {
"type": [
"string",
"null"
],
"description": "ID of the answer"
},
"profile_image_url": {
"type": [
"string",
"null"
],
"description": "URL of the user's profile image"
},
"profile_url": {
"type": [
"string",
"null"
],
"description": "URL of the user's profile"
},
"profile_name": {
"type": [
"string",
"null"
],
"description": "displayed name of the user"
},
"answer_text": {
"type": [
"string",
"null"
],
"description": "current text of the answer"
},
"original_answer_text": {
"type": [
"string",
"null"
],
"description": "original text of the answer"
},
"time_ago": {
"type": [
"string",
"null"
],
"description": "estimated time when the answer was posted"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "exact time when the answer was posted"
}
}
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)
this field will contain the cid parameter if you specified it in the keyword field when setting a task;
example:cid:2946633002421908862
learn more about the parameter in this help center article"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain as specified in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment;
learn more about the identifier in this help center article"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": " unique identifier of the SERP feature"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "item types
types of search engine results encountered in the items array;
possible item types: google_business_question_item"
},
"items_without_answers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessQuestionItem"
}
]
},
"description": "array of google business question items without answers"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleBusinessQuestionItem"
}
]
},
"description": " array of items within google_business_question_item
contains answers to the google business questions;
the maximum number of answers returned for each question: 5
possible item types google_business_answer_element"
}
}
},
"Provider463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of question rows in the result
default value: 20
max value: 700
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "Los Angeles,California,United States",
"keyword": "The Last Bookstore"
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleQuestionsAndAnswersTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_BusinessDataGoogleReviewsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleReviewsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleReviewsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the 'reviews' element in SERP
the name of the local establishment for which the reviews are collected"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "subtitle of the 'reviews' element in SERP
additional information (e.g., address) on the 'reviews' element for which the reviews are collected"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the corresponding local establishment
popularity rate based on reviews and displayed in SERP"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the 'reviews' element in SERP
learn more about the identifier in this help center article"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "unique identifier of a business location assigned by Google
learn more about the identifier in this help center article"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment
learn more about the identifier in this help center article"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleReviewsSearch"
}
]
},
"description": "found reviews
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_GoogleReviewsSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the review"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "the content of the review"
},
"original_review_text": {
"type": [
"string",
"null"
],
"description": "original content of the review
the original content of the review, no auto-translate applied"
},
"original_language": {
"type": [
"string",
"null"
],
"description": "original language of the review text"
},
"time_ago": {
"type": [
"string",
"null"
],
"description": "the time of publication
indicates the time (in the 'time ago' format) when the review was listed"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when a review was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "total number of reviews submitted by the reviewer",
"format": "int64"
},
"photos_count": {
"type": [
"integer",
"null"
],
"description": "total number of photos submitted by the reviewer",
"format": "int64"
},
"local_guide": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the reviewer has a 'local guide' status"
},
"profile_name": {
"type": [
"string",
"null"
],
"description": "profile name of the reviewer"
},
"profile_url": {
"type": [
"string",
"null"
],
"description": "URL of the reviewer's profile"
},
"review_url": {
"type": [
"string",
"null"
],
"description": "the URL of the review"
},
"profile_image_url": {
"type": [
"string",
"null"
],
"description": "URL of the reviewer's profile image"
},
"owner_answer": {
"type": [
"string",
"null"
],
"description": "text of the owner's response
the owner's response to the review"
},
"original_owner_answer": {
"type": [
"string",
"null"
],
"description": "original text of the owner's response
the original response to the review, no auto-translate applied"
},
"owner_time_ago": {
"type": [
"string",
"null"
],
"description": "publication time
indicates the time (in the 'time ago' format) when the owner submitted the response to the review"
},
"owner_timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the owner's reply to the review
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"review_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of a review on Google
example:ChZDSUhNMG9nS0VJQ0FnSUMxbHFyMFlnEAE"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images submitted by the reviewer"
},
"review_highlights": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ReviewHighlights"
}
]
},
"description": "review highlights
contains highlighted review criteria and assessments"
}
}
},
"Provider463397119C53_BusinessDataGoogleReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field if you don't specify cid or place_id
the keyword you specify should indicate the name of the local establishment;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation errorkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"cid": {
"type": "string",
"description": "unique, google-defined id of the business entity
required field if you don't specify keyword or place_id
example:194604053573767737
learn more about the identifier in this help center article"
},
"place_id": {
"type": "string",
"description": "identifier of the business entity in Google Maps
required field if you don't specify keyword or cid
example:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the identifier in this help center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews in SERP
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row
default value: 10
maximum value: 4490
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:newest – sort by newest firsthighest_rating – sort by highest ratinglowest_rating – sort by lowest ratingrelevant – sort by relevance
default value: relevant"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleReviewsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataGoogleReviewsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataGoogleReviewsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: google"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_BusinessDataTripadvisorReviewsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorReviewsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorReviewsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTaskGetResultInfo": {
"type": "object",
"properties": {
"url_path": {
"type": [
"string",
"null"
],
"description": "URL path received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the 'reviews' element in SERP
the name of the local establishment for which the reviews are collected"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the local establishment
address of the local establishment for which the reviews are collected"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "rating of the corresponding local establishment
popularity rate based on reviews and displayed in SERP"
},
"rating_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "Int64"
},
"description": "rating distribution by votes
the distribution of votes across the rating in the range from 1 to 5"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TripadvisorReviewSearch"
}
]
},
"description": "found reviews
you can get more results by using the depth parameter when setting a task"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
}
}
},
"Response463397119C53_TripadvisorReviewSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: right"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the review"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
},
"date_of_visit": {
"type": [
"string",
"null"
],
"description": "date of the reviewer's visit to the local establishment
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the review was published
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"review_id": {
"type": [
"string",
"null"
],
"description": "ID of the review"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the review"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "content of the review"
},
"language": {
"type": [
"string",
"null"
],
"description": "language of the review text"
},
"original_language": {
"type": [
"string",
"null"
],
"description": "language of the untranslated review text"
},
"review_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ImageUrlInfo"
}
]
},
"description": "contains URLs of the images used in the review"
},
"user_profile": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataUserProfileInfo"
}
],
"description": "information from the reviewer's profile"
},
"responses": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ReviewResponseItemInfo"
}
]
},
"description": "contains information about the owner's response"
},
"review_highlights": {
"type": [
"object",
"null"
],
"description": "review highlights
contains highlighted review criteria and assessments"
}
}
},
"Response463397119C53_ImageUrlInfo": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "URL of the image used in the review"
}
}
},
"Response463397119C53_BusinessDataUserProfileInfo": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"location": {
"type": [
"string",
"null"
]
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "total number of reviews submitted by the reviewer",
"format": "int64"
}
}
},
"Response463397119C53_ReviewResponseItemInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "the title of response"
},
"text": {
"type": [
"string",
"null"
],
"description": "the content of response"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "the time of publication"
}
}
},
"Provider463397119C53_BusinessDataTripadvisorReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"url_path": {
"type": "string",
"description": "URL path of the business entity
required field if you do not specify keyword
URL path to the Tripadvisor page of the business entity;
examples:Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.htmlhttps://www.tripadvisor.com/Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html"
},
"keyword": {
"type": "string",
"description": "keyword
required field if you do not specify url_path
the keyword you specify should indicate a name of an existing business or prominent place on Tripadvisor;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or url_path
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or url_path
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:1003854"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
if you use this field, your account will be charged for one extra request
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/languages
example:English
You will be additionally charged for setting a language parameter in this endpoint.
The cost can be calculated on the Pricing page."
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
if you use this field, your account will be charged for one extra request
you can receive the list of available languages with language_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/languages
example:en
You will be additionally charged for setting a language parameter in this endpoint.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews in SERP;
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row;
default value: 10;
max value: 4490
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"ratings": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Tripadvisor traveler rating for a place of interest
optional field
rating based on the written reviews by a traveler after they visited a place.
possible values: excellent, very_good, average, poor, terrible
you can specify several values at once"
},
"visit_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "filter by type of travelers who left a review
optional field
possible values: families, couples, solo, business, friends
you can specify several values at once"
},
"months": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "filter by months when a traveler made a visit
optional field
possible values: january, february, march, april, may, april, june, july, august, september, october, november, december
you can specify several values at once"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:most_recentdetailed_reviews"
},
"translate_reviews": {
"type": [
"boolean",
"null"
],
"description": "translate reviews according to the URL path
optional field
if set to true, returned reviews will be translated to the language matching the specified url_path;
for example, if url_path contains tripadvisor.it and translate_reviews is true, reviews will be translated to the Italian language;
default value: true
you can learn more about how reviews are translated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorReviewsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorReviewsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorReviewsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: tripadvisor"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_BusinessDataTripadvisorSearchTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorSearchTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorSearchTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
this field will contain the alias parameter if it was specified in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Tripadvisor results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "item types encountered in the result
possible item types: tripadvisor_search_organic"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "the total number of results",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TripadvisorSearchOrganic"
}
]
},
"description": "Tripadvisor search listing results
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_TripadvisorSearchOrganic": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed results
absolute position among all reviews on the list"
},
"title": {
"type": [
"string",
"null"
],
"description": "name of the business entity"
},
"url_path": {
"type": [
"string",
"null"
],
"description": "URL path of the business entity
URL path to the Tripadvisor page of the business entity
you can use this identifier to collect reviews for the business entity using Tripadvisor Reviews"
},
"is_sponsored": {
"type": [
"boolean",
"null"
],
"description": "indicates a sponsored placement
if true, related tripadvisor_search_organic item is a paid advertising on Tripadvisor"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"category": {
"type": [
"string",
"null"
],
"description": "place category"
},
"price_rate": {
"type": [
"string",
"null"
],
"description": "average price rate"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score of the establishment submitted by the reviewers"
}
}
},
"Provider463397119C53_BusinessDataTripadvisorSearchTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate a business category, company name, or a prominent place;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:1003854"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of search results to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of thirty because our systems processes thirty search results in a row;
default value: 30;
maximum value: 210
Setting depth above 30 may result in additional charges if the search engine returns more than 30 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorSearchTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTripadvisorSearchTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTripadvisorSearchTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: tripadvisor"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_BusinessDataTrustpilotReviewsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotReviewsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotReviewsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTaskGetResultInfo": {
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the business entity"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the 'reviews' element on Trustpilot
the name of the business entity for which the reviews are collected"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the business entity as specified on Trustpilot
address of the business entity for which the reviews are collected"
},
"reviews_count": {
"type": [
"string",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"description": "rating of the corresponding business entity
popularity rate based on reviews and displayed in SERP"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TrustpilotReviewSearch"
}
]
},
"description": "found reviews
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_TrustpilotReviewSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: right"
},
"url": {
"type": [
"string",
"null"
],
"description": "the URL of the review"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the review has the \"Verified\" mark"
},
"language": {
"type": [
"string",
"null"
],
"description": "the language of the review"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when a review was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "the title of the review"
},
"review_text": {
"type": [
"string",
"null"
],
"description": "the content of the review"
},
"review_images": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "images submitted by the reviewer
displays URLs to the images provided by the author of the review;
please note that Trustpilot doesn't allow adding images to reviews, so the review_images parameter will always equal null"
},
"user_profile": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataUserProfileInfo"
}
],
"description": "user profile of the reviewer"
},
"responses": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ReviewResponseItemInfo"
}
]
},
"description": "owner's response to the submitted review"
}
}
},
"Provider463397119C53_BusinessDataTrustpilotReviewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "domain of the local establishment
required field
domain of the local establishment on Trustpilot;
you can find the domain in the URL of every business listed on Trustpilot
example:www.thepearlsource.comhttps://www.trustpilot.com/review/www.thepearlsource.com"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameter
optional field
you can use this field to sort the results;
possible sorting parameters:recency — most recent reviews first;relevance — most relevant reviews first;
default value: relevance"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of twenty, because our system processes twenty reviews in a row
default value: 20
maximum value: 200
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotReviewsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotReviewsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotReviewsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: trustpilot"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_BusinessDataTrustpilotSearchTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotSearchTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotSearchTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of items in the results array
you can get more results by using the depth parameter when setting a task",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TrustpilotSearchOrganic"
}
]
},
"description": "found reviews
you can get more results by using the depth parameter when setting a task"
}
}
},
"Response463397119C53_TrustpilotSearchOrganic": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the establishment"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the establishment"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the establishment"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the total number of reviews",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score of the establishment submitted by reviewers"
}
}
},
"Provider463397119C53_BusinessDataTrustpilotSearchTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
the keyword you specify should indicate a business category or company name;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of search results to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of twenty because our systems processes twenty search results in a row;
default value: 10;
maximum value: 140
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotSearchTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BusinessDataTrustpilotSearchTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_BusinessDataTrustpilotSearchTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task
can take the following values: trustpilot"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Response463397119C53_ContentAnalysisAvailableFiltersResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisAvailableFiltersTaskInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_ContentAnalysisAvailableFiltersTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisAvailableFiltersResultInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_ContentAnalysisAvailableFiltersResultInfo": {
"type": "object",
"properties": {
"search": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
}
},
"Response463397119C53_ContentAnalysisCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisCategoriesResultInfo": {
"type": "object",
"properties": {
"category_code": {
"type": [
"integer",
"null"
],
"description": "category code"
},
"category_name": {
"type": [
"string",
"null"
],
"description": "full name of the category"
},
"category_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate category
example:\"category_code\": 10178,
\"category_name\": \"Apparel Accessories\",
\"category_code_parent\": 10021
where category_code_parent
corresponds to: \"category_code\": 10178,"
}
}
},
"Provider463397119C53_ContentAnalysisCategoryTrendsLiveRequestInfo": {
"type": "object",
"properties": {
"category_code": {
"type": [
"integer",
"null"
],
"description": "target category code
\"category_name\": \"Apparel Accessories\"
required field
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns data on all citations for the target category_codeone_per_domain - returns data on one citation of the category_code per domain
default value: as_is"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"date_from": {
"type": "string",
"description": "starting date of the time range
required field
minimum value: 2022-10-31
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_group": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint;
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"category_code": 10994,
"search_mode": "as_is",
"date_from": "2022-09-01",
"date_group": "month"
}
]
},
"Response463397119C53_ContentAnalysisCategoryTrendsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoryTrendsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisCategoryTrendsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoryTrendsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisCategoryTrendsLiveResultInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date for which the data is provided"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in our database relevant to your request",
"format": "int64"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank of all URLs citing the keyword
normalized sum of ranks of all URLs citing the target keyword for the given date"
},
"top_domains": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopDomainInfo"
}
]
},
"description": "top domains citing the target keyword
contains objects with top domains citing the target category and citation count per each domain"
},
"sentiment_connotations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "sentiment connotations
contains sentiments (emotional reactions) related to the target category citation and the number of citations per each sentiment
possible connotations: \"anger\", \"fear\", \"happiness\", \"love\", \"sadness\", \"share\", \"neutral\", \"fun\""
},
"connotation_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "connotation types
contains types of sentiments (sentiment polarity) related to the category citation and citation count per each sentiment type
possible connotation types: \"positive\", \"negative\", \"neutral\""
},
"text_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesInfo"
}
]
},
"description": "text categories
contains objects with text categories and citation count in each text category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesInfo"
}
]
},
"description": "page categories
contains objects with page categories and citation count in each page category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "page types
contains page types and citation count per each page type"
},
"countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "countries
contains countries and citation count in each country
to obtain a full list of available countries, refer to the Locations endpoint"
},
"languages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "languages
contains languages and citation count in each language
to obtain a full list of available languages, refer to the Languages endpoint"
}
}
},
"Response463397119C53_TopDomainInfo": {
"properties": {
"domain": {
"type": [
"string",
"null"
]
},
"count": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
},
"Response463397119C53_ContentAnalysisCategoriesInfo": {
"properties": {
"category": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
}
},
"count": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
},
"Response463397119C53_ContentAnalysisLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisLanguagesResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
]
},
"location_name": {
"type": [
"string",
"null"
]
},
"location_code_parent": {
"type": [
"integer",
"null"
]
},
"country_iso_code": {
"type": [
"string",
"null"
]
},
"location_type": {
"type": [
"string",
"null"
]
}
}
},
"Response463397119C53_ContentAnalysisLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisLocationsResultInfo": {
"type": "object",
"properties": {
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
}
}
},
"Provider463397119C53_ContentAnalysisPhraseTrendsLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example: \"keyword\": \"\\\"tesla palo alto\\\"\"keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}`"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns data on all citations for the target keywordone_per_domain - returns data on one citation of the keyword per domain
default value: as_is"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"date_from": {
"type": "string",
"description": "starting date of the time range
required field
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_group": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint;
you can add several filters at once (8 filters maximum);
you should set a logical operator and, or between the conditions;
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters;
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "logitech",
"search_mode": "as_is",
"date_from": "2022-09-01",
"date_group": "month"
}
]
},
"Response463397119C53_ContentAnalysisPhraseTrendsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisPhraseTrendsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisPhraseTrendsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisPhraseTrendsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisPhraseTrendsLiveResultInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date for which the data is provided"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in our database relevant to your request",
"format": "int64"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank of all URLs citing the keyword
normalized sum of ranks of all URLs citing the target keyword for the given date"
},
"top_domains": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopDomainInfo"
}
]
},
"description": "top domains citing the target keyword
contains objects with top domains citing the target keyword and citation count per each domain"
},
"sentiment_connotations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "sentiment connotations
contains sentiments (emotional reactions) related to the target keyword citation and the number of citations per each sentiment
possible connotations: \"anger\", \"happiness\", \"love\", \"sadness\", \"share\", \"fun\""
},
"connotation_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "connotation types
contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type
possible connotation types: \"positive\", \"negative\", \"neutral\""
},
"text_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesInfo"
}
]
},
"description": "text categories
contains objects with text categories and citation count in each text category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesInfo"
}
]
},
"description": "page categories
contains objects with page categories and citation count in each page category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "page types
contains page types and citation count per each page type"
},
"countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "countries
contains countries and citation count in each country
to obtain a full list of available countries, refer to the Locations endpoint"
},
"languages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "languages
contains languages and citation count in each language
to obtain a full list of available languages, refer to the Languages endpoint"
}
}
},
"Provider463397119C53_ContentAnalysisRatingDistributionLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example: \"keyword\": \"\\\"tesla palo alto\\\"\"keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}`"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns all citations for the target keywordone_per_domain - returns one citation of the keyword per domain
default value: as_is"
},
"positive_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "positive connotation threshold
optional field
specified as the probability index threshold for positive sentiment related to the citation content
if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4"
},
"sentiments_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "sentiment connotation threshold
optional field
specified as the probability index threshold for sentiment connotations related to the citation content
if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "logitech",
"search_mode": "as_is",
"internal_list_limit": 10
}
]
},
"Response463397119C53_ContentAnalysisRatingDistributionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisRatingDistributionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisRatingDistributionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisRatingDistributionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisRatingDistributionLiveResultInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"min": {
"type": [
"number",
"null"
],
"description": "min rating on a distribution scale"
},
"max": {
"type": [
"number",
"null"
],
"description": "max rating on a distribution scale"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
],
"description": "contains rating distribution metrics"
}
}
},
"Response463397119C53_ContentAnalysisSummaryInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"rank": {
"type": [
"integer",
"null"
],
"description": "rank of all URLs citing the keyword
normalized sum of ranks of all URLs citing the target keyword"
},
"top_domains": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopDomainInfo"
}
]
},
"description": "top domains citing the target keyword
contains objects with top domains citing the target keword and citation count per each domain"
},
"sentiment_connotations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "sentiment connotations
contains sentiments (emotional reactions) related to the target keyword citation and the number of citations per each sentiment
possible sentiment connotations: anger, happiness, love, sadness, share, fun"
},
"connotation_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "connotation types
contains types of sentiments (sentiment polarity) related to the keyword citation and citation count per each sentiment type
possible sentiment connotation types: positive, negative, neutral"
},
"text_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesInfo"
}
]
},
"description": "text categories
contains objects with text categories and citation count in each text category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisCategoriesInfo"
}
]
},
"description": "page categories
contains objects with page categories and citation count in each page category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "page types
contains page types and citation count per each page type"
},
"countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "countries
contains countries and citation count in each country
to obtain a full list of available countries, refer to the Locations endpoint"
},
"languages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "languages
contains languages and citation count in each language
to obtain a full list of available languages, refer to the Languages endpoint"
}
}
},
"Provider463397119C53_ContentAnalysisSearchLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword\": \"\\\"tesla palo alto\\\"\"`keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}\"`"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns all citations for the target keywordone_per_domain - returns one citation of the keyword per domain
default value: as_is"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned citations
optional field
default value: 100
maximum value: 1000"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"country\",\"=\", \"US\"][[\"domain_rank\",\">\",800],\"and\",[\"content_info.connotation_types.negative\",\">\",0.9]][[\"domain_rank\",\">\",800],
\"and\",
[[\"page_types\",\"has\",\"ecommerce\"],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"content_info.sentiment_connotations.anger,desc\"]
default rule:[\"content_info.sentiment_connotations.anger,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"content_info.sentiment_connotations.anger,desc\",\"keyword_data.keyword_info.cpc,desc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned citations
optional field
default value: 0
if you specify the 10 value, the first ten citations in the results array will be omitted and the data will be provided for the successive citations
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
optional field
provided in the identical field of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task
learn more about this parameter on our Help Center"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the domain_rank, and url_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword_fields": {
"snippet": "logitech"
},
"keyword": "logitech",
"page_type": [
"ecommerce",
"news",
"blogs",
"message-boards",
"organization"
],
"search_mode": "as_is",
"filters": [
"main_domain",
"=",
"reviewfinder.ca"
],
"order_by": [
"content_info.sentiment_connotations.anger,desc"
],
"limit": 10
}
]
},
"Response463397119C53_ContentAnalysisSearchLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSearchLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisSearchLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSearchLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisSearchLiveResultInfo": {
"type": "object",
"properties": {
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
you can use the string provided in this field to get the subsequent results of the initial task;
note: offset_token values are unique for each subsequent task"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSearchLiveItem"
}
]
},
"description": "contains citations and related data"
}
}
},
"Response463397119C53_ContentAnalysisSearchLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL where the citation was found"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain name"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "main domain"
},
"url_rank": {
"type": [
"integer",
"null"
],
"description": "rank of the url
this value is based on backlink data for the given URL from DataForSEO Backlink Index;url_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"spam_score": {
"type": [
"integer",
"null"
],
"description": "backlink spam score of the url
this value is based on backlink data for the given URL from DataForSEO Backlink Index;
learn more about how the metric is calculated on this help center page"
},
"domain_rank": {
"type": [
"integer",
"null"
],
"description": "rank of the domain
this value is based on backlink data for the given domain from DataForSEO Backlink Index;domain_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article"
},
"fetch_time": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler visited the page
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2017-01-24 13:20:59 +00:00"
},
"country": {
"type": [
"string",
"null"
],
"description": "country code of the domain registration
to obtain a full list of available countries, refer to the Locations endpoint"
},
"language": {
"type": [
"string",
"null"
],
"description": "main language of the domain
to obtain a full list of available languages, refer to the Languages endpoint"
},
"score": {
"type": [
"number",
"null"
],
"description": "citation prominence score
this value is based on url_rank, domain_rank, keyword presence in title, main_title, url, snippet
the higher the score, the more value the related citation has"
},
"page_category": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "contains all relevant page categories
product and service categories relevant for the page
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "page types"
},
"ratings": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContententRatingInfo"
}
]
},
"description": "ratings found on the page
all ratings found on the page based on microdata"
},
"social_metrics": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SocialMetricsInfo"
}
]
},
"description": "social media engagement metrics
data on social media interactions associated with the content based on website embeds developed and supported by social media platforms"
},
"content_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AnalysisContentInfo"
}
],
"description": "contains data on citations from the given url"
}
}
},
"Response463397119C53_ContententRatingInfo": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "rating name\nhere you can find the following elements: Max5, Percents, CustomMax"
},
"rating_value": {
"type": [
"number",
"null"
],
"description": "the value of the rating",
"format": "double"
},
"rating_count": {
"type": [
"integer",
"null"
],
"description": "number of votes",
"format": "int64"
},
"max_rating_value": {
"type": [
"number",
"null"
],
"description": "maximum value for the rating name",
"format": "double"
},
"relative_rating": {
"type": [
"number",
"null"
],
"description": "relative rating",
"format": "double"
}
}
},
"Response463397119C53_SocialMetricsInfo": {
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"like_count": {
"type": [
"integer",
"null"
],
"description": "likes count",
"format": "int64"
}
}
},
"Response463397119C53_AnalysisContentInfo": {
"type": "object",
"properties": {
"content_type": {
"type": [
"string",
"null"
],
"description": "type of content
example:page_content, comment"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result"
},
"main_title": {
"type": [
"string",
"null"
],
"description": "page title"
},
"previous_title": {
"type": [
"string",
"null"
],
"description": "title of the previous content block"
},
"level": {
"type": [
"integer",
"null"
],
"description": "title heading level
indicates h-tag level from 1 (top) to 6 (bottom)"
},
"author": {
"type": [
"string",
"null"
],
"description": "author of the content"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "content snippet"
},
"snippet_length": {
"type": [
"integer",
"null"
],
"description": "character length of the snippet"
},
"social_metrics": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SocialMetricsInfo"
}
]
},
"description": "social media engagement metrics
data on social media interactions associated with the content based on website embeds developed and supported by social media platforms"
},
"highlighted_text": {
"type": [
"string",
"null"
],
"description": "highlighted text from the snippet"
},
"language": {
"type": [
"string",
"null"
],
"description": "main language of the domain
to obtain a full list of available languages, refer to the Languages endpoint"
},
"sentiment_connotations": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "sentiment connotations
contains sentiments (emotional reactions) related to the given citation and probability index per each sentiment
possible sentiment connotations: anger, happiness, love, sadness, share, fun"
},
"connotation_types": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "connotation types
contains types of sentiments (sentiment polarity) related to the given citation and probability index per each sentiment type
possible sentiment connotation types: positive, negative, neutral"
},
"text_category": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "text category
to obtain a full list of available categories, refer to the Categories endpoint"
},
"date_published": {
"type": [
"string",
"null"
],
"description": "date and time when the content was published
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2017-01-24 13:20:59 +00:00"
},
"content_quality_score": {
"type": [
"integer",
"null"
],
"description": "content quality score
this value is calculated based on the number of words, sentences and characters the content contains"
},
"semantic_location": {
"type": [
"string",
"null"
],
"description": "semantic location
indicates semantic element in HTML where the target keyword citation is located
example:article, header"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContententRatingInfo"
}
],
"description": "content rating
rating related to content_info"
},
"group_date": {
"type": [
"string",
"null"
],
"description": "citation group date and time
indicates content publication date or date and time when our crawler visited the page for the first time;
this field can be used to group citations by date and display citation trends;
date and time are provided in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2017-01-24 13:20:59 +00:00"
}
}
},
"Provider463397119C53_ContentAnalysisSentimentAnalysisLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "target keyword\nrequired field\nUTF-8 encoding\nthe keywords will be converted to a lowercase format;\nNote: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;\nexample:\n\"keyword\": \"\\\"tesla palo alto\\\"\"\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords\noptional field\nuse this parameter to filter the dataset by keywords that certain fields should contain;\nfields you can specify: title, main_title, previous_title, snippet\nyou can indicate several fields;\nNote: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;\nexample:\n\"keyword_fields\": {\n \"snippet\": \"\\\"logitech mouse\\\"\",\n \"main_title\": \"sale\"\n}"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types\noptional field\nuse this parameter to filter the dataset by page types\npossible values:\n\"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays\noptional field\nyou can use this field to limit the number of elements within the following arrays:\ntop_domains\ntext_categories\npage_categories\ncountries\nlanguages\ndefault value: 1\nmaximum value: 20"
},
"positive_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "positive connotation threshold\noptional field\nspecified as the probability index threshold for positive sentiment related to the citation content\nif you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value\npossible values: from 0 to 1\ndefault value: 0.4"
},
"sentiments_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "sentiment connotation threshold\noptional field\nspecified as the probability index threshold for sentiment connotations related to the citation content\nif you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value\npossible values: from 0 to 1\ndefault value: 0.4"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters\noptional field\ninitial filtering parameters that apply to fields in the Search endpoint\nyou can add several filters at once (8 filters maximum)\nyou should set a logical operator and, or between the conditions\nthe following operators are supported:\nregex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match\nyou can use the % operator with like and not_like to match any string of zero or more characters\nexample:\n[\"domain\",\"<>\", \"logitech.com\"]\n[[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]]\n[[\"domain\",\"<>\",\"logitech.com\"]],\n\"and\",\n[[\"content_info.connotation_types.negative\",\">\",1000],\n\"or\",\n[\"content_info.text_category\",\"has\",10994]]]\nfor more information about filters, please refer to Content Analysis API – Filters\nlearn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values\noptional field\nyou can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale\npossible values:\none_hundred — rank values are displayed on a 0–100 scale\none_thousand — rank values are displayed on a 0–1000 scale\ndefault value: one_thousand\nlearn more about how this parameter works in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "logitech",
"internal_list_limit": 1
}
]
},
"Response463397119C53_ContentAnalysisSentimentAnalysisLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSentimentAnalysisLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisSentimentAnalysisLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSentimentAnalysisLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_ContentAnalysisSentimentAnalysisLiveResultInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"positive_connotation_distribution": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PositiveConnotationDistribution"
}
],
"description": "citation distribution by sentiment connotation types\ncontains objects with citation counts and relevant data distributed by types of sentiments (sentiment polarity);\npossible sentiment connotation types: positive, negative, neutral"
},
"sentiment_connotation_distribution": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SentimentConnotationDistribution"
}
],
"description": "citation distribution by sentiment connotations\ncontains objects with citation counts and relevant data distributed by sentiments (emotional reactions);\npossible sentiment connotation types: anger, happiness, love, sadness, share, fun"
}
}
},
"Response463397119C53_PositiveConnotationDistribution": {
"type": "object",
"properties": {
"positive": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"negative": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"neutral": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
}
}
},
"Response463397119C53_SentimentConnotationDistribution": {
"type": "object",
"properties": {
"anger": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"happiness": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"love": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"sadness": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"share": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"fun": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
}
}
},
"Provider463397119C53_ContentAnalysisSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "target keyword
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example: \"keyword\": \"\\\"tesla palo alto\\\"\"keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:\"keyword_fields\": {"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"positive_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "positive connotation threshold
optional field
specified as the probability index threshold for positive sentiment related to the citation content
if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4"
},
"sentiments_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "sentiment connotation threshold
optional field
specified as the probability index threshold for sentiment connotations related to the citation content
if you specify this field, sentiment_connotations object in the response will only contain data on citations where the
probability per each sentiment is more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "logitech",
"page_type": [
"ecommerce",
"news",
"blogs",
"message-boards",
"organization"
],
"internal_list_limit": 8,
"positive_connotation_threshold": 0.5
}
]
},
"Response463397119C53_ContentAnalysisSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_ContentAnalysisSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentAnalysisSummaryInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Provider463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
the keywords will be converted to lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the following locations and languages only:Australia - 2036, enAustria - 2040, deCanada - 2124, enEgypt - 2818, arFrance - 2250, frGermany - 2276, deIndia - 2356, enItaly - 2380, itMexico - 2484, esNetherlands - 2528, nlSaudi Arabia - 2682, arSingapore - 2702, enSpain - 2724, esUnited Arab Emirates - 2784, arUnited Kingdom - 2826, enUnited States - 2840, en
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports these locations and languages only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
Note: this endpoint currently supports these locations and languages only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
Note: this endpoint currently supports these locations and languages only;
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"buy laptop",
"cheap laptops for sale",
"purchase laptop"
],
"location_code": 2840,
"language_code": "en"
}
]
},
"Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveItem"
}
]
},
"description": "contains keyword search volume data data"
}
}
},
"Response463397119C53_DataforseoLabsAmazonBulkSearchVolumeLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "average monthly search volume rate
represents the (approximate) number of searches for the returned keyword on Amazon",
"format": "int64"
}
}
},
"Provider463397119C53_DataforseoLabsAmazonProductCompetitorsLiveRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "product ID
required field
unique product identifier (ASIN) on Amazon;
you can receive the asin parameter by making a separate request to the Amazon Products endpoint"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of products in the results array
optional field
default value: 100;
maximum value: 1000"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, ilike, not_ilike, like, not_like, match, not_match
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:[\"full_metrics.amazon_serp.pos_1\",\">\", 20]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"full_metrics.amazon_serp.pos_1,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"full_metrics.amazon_serp.pos_1,desc\",\"avg_position,desc\"]
default rule:[\"ranked_serp_element.serp_item.rank_group,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned product competitors
optional field
default value: 0
if you specify the 10 value, the first ten product competitors in the results array will be omitted and the data will be provided for the successive product competitors"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"asin": "019005476X",
"location_code": 2840,
"language_code": "en"
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveItem"
}
]
},
"description": "contains detected Amazon product competitors and related data"
}
}
},
"Response463397119C53_DataforseoLabsAmazonProductCompetitorsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN in a POST array"
},
"avg_position": {
"type": [
"number",
"null"
],
"description": "average position of the product in Amazon SERP
Note: average position is calculated for intersected keywords only;
the value for a given product may differ when combined with different target products",
"format": "float"
},
"sum_position": {
"type": [
"integer",
"null"
],
"description": "sum of all product positions in Amazon SERP
Note: average position is calculated for intersected keywords only;
the value for a given product may differ when combined with different target products"
},
"intersections": {
"type": [
"integer",
"null"
],
"description": "number of intersecting keywords"
},
"competitor_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonMetricsBundleInfo"
}
],
"description": "metrics for intersecting keywords
ranking data relevant to the keywords that the provided asin shares with the target asin;
Note: in this object ranking data is provided for the returned competitor's asin"
},
"full_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonMetricsBundleInfo"
}
],
"description": "metrics for all keywords of the product
full overview of ranking data relevant to all keywords that the provided asin is ranking for"
}
}
},
"Response463397119C53_AmazonMetricsBundleInfo": {
"type": "object",
"properties": {
"amazon_serp": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppMetricsInfo"
}
],
"description": "ranking data from Amazon organic SERP"
},
"amazon_paid": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppMetricsInfo"
}
],
"description": "ranking data from Amazon paid SERP"
}
}
},
"Response463397119C53_AppMetricsInfo": {
"type": "object",
"properties": {
"pos_1": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the product ranks #1"
},
"pos_2_3": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the product ranks #2-3"
},
"pos_4_10": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the product ranks #4-10"
},
"pos_11_100": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the product ranks #11-100"
},
"count": {
"type": [
"integer",
"null"
],
"description": "total count of Amazon organic SERPs that contain the product",
"format": "int64"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "total search volume of the product's ranking keywords in organic SERP",
"format": "int64"
}
}
},
"Provider463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveRequestInfo": {
"type": "object",
"properties": {
"asins": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "asins of target products
required field
product IDs of the products for which you need to find keyword intersections;
specify the ASINs as in the following example:\"asins\": {
\"1\": \"019005476X\",
\"2\": \"0190074442\"
}
the maximum number of ASINs you can specify in this object is 20;
learn more about the parameter on this help center page"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request tohttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of products in the results array
optional field
default value: 100;
maximum value: 1000"
},
"intersection_mode": {
"type": [
"string",
"null"
],
"description": "mode for finding asin intersections
optional field
possible values: union, intersect;
default value: intersect;
learn more about the parameter in this help center guide"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, ilike, not_ilike, like, not_like, match, not_match
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:[\"avg_position\",\"<\", 10]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"sum_position,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"intersections,desc\",\"avg_position,asc\"]
default rule:[\"intersections,desc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"asins": {
"1": "B09172433Z",
"2": "B07GBZ4Q68",
"3": "B07GCKQD77"
},
"language_name": "English",
"location_code": 2840
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"asins": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "ASINs in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveItem"
}
]
},
"description": "contains detected Amazon product competitors and related data"
}
}
},
"Response463397119C53_DataforseoLabsAmazonProductKeywordIntersectionsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonKeywordData"
}
],
"description": "keyword data for the returned keyword"
},
"intersection_result": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonInfo"
}
]
},
"description": "data on the intersection"
}
}
},
"Response463397119C53_AmazonKeywordData": {
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "related keyword"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array",
"format": "int64"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonKeywordInfo"
}
],
"description": "keyword info for the returned keyword"
}
}
},
"Response463397119C53_AmazonKeywordInfo": {
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nexample: '2019-11-15 12:57:46 +00:00'"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "average monthly search volume rate\nrepresents the (approximate) number of searches for the provided keyword idea on Amazon",
"format": "int64"
}
}
},
"Response463397119C53_AmazonInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in Amazon SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Amazon SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "Amazon domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the product page"
},
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN in a POST array"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the product image featured in the results"
},
"price_from": {
"type": [
"number",
"null"
],
"description": "the regular price of a product
example:49.98"
},
"price_to": {
"type": [
"number",
"null"
],
"description": "the upper limit of the product price range
example:384.99"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"special_offers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "special offer details
contains special offer details, including coupon and Subscribe & Save discounts"
},
"is_best_seller": {
"type": [
"boolean",
"null"
],
"description": "\"Best Seller\" label
if the value is true, the product is marked with the \"Best Seller\" label"
},
"is_amazon_choice": {
"type": [
"boolean",
"null"
],
"description": "\"Amazon's choice\" label
if the value is true, the product is marked with the \"Amazon's choice\" label"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "the value of the rating",
"format": "float"
}
},
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonDeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"bought_past_month": {
"type": [
"integer",
"null"
]
}
}
},
"Response463397119C53_AmazonDeliveryInfo": {
"type": "object",
"properties": {
"delivery_message": {
"type": [
"string",
"null"
],
"description": "message accompanying the delivery information as posted by the seller"
},
"delivery_date_from": {
"type": [
"string",
"null"
],
"description": "the earliest date when the product can be shipped"
},
"delivery_date_to": {
"type": [
"string",
"null"
],
"description": "the latest date when the product can be delivered"
},
"fastest_delivery_date_from": {
"type": [
"string",
"null"
],
"description": "the earliest date when the product can be delivered with a fast delivery option"
},
"fastest_delivery_date_to": {
"type": [
"string",
"null"
],
"description": "the latest date when the product can be delivered with a fast delivery option"
},
"delivery_price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price for the delivery\nprice of the delivery based on the location you specified in the POST request;\nif free delivery is available, the value is null"
}
}
},
"Provider463397119C53_DataforseoLabsAmazonProductRankOverviewLiveRequestInfo": {
"type": "object",
"properties": {
"asins": {
"type": "array",
"items": {
"type": "string"
},
"description": "product IDs to compare
required field
product IDs to receive ranking data for;
the maximum number of ASINs you can specify in this array is 1000;
you can receive the asin parameter by making a separate request to the Amazon Products endpoint
example:B01LW2SL7R"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"asins": [
"B001TJ3HUG",
"B01LW2SL7R"
],
"language_name": "English",
"location_code": 2840
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveItem"
}
]
},
"description": "contains detected Amazon product competitors and related data"
}
}
},
"Response463397119C53_DataforseoLabsAmazonProductRankOverviewLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN of the product
unique product identifier on Amazon;
for more information, refer to this help center guide"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonMetricsBundleInfo"
}
],
"description": "average keyword position of the product"
}
}
},
"Provider463397119C53_DataforseoLabsAmazonRankedKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "product ID
required field
unique product identifier (ASIN) on Amazon;
you can receive the asin parameter by making a separate request to the Amazon Products endpoint"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request tohttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of products in the results array
optional field
default value: 100;
maximum value: 1000"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to true only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]];
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"keyword_data.keyword_info.competition,desc\"]
default rule:[\"ranked_serp_element.serp_item.rank_group,asc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"asin": "B00R92CL5E",
"location_code": 2840,
"language_code": "en"
}
]
},
"Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveItem"
}
]
},
"description": "contains detected Amazon product competitors and related data"
}
}
},
"Response463397119C53_DataforseoLabsAmazonRankedKeywordsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"ranked_serp_element": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonRankedSerpElement"
}
],
"description": "contains data on the products's SERP element found for the returned keyword"
}
}
},
"Response463397119C53_KeywordDataInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "returned keyword idea"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfo"
}
],
"description": "keyword data for the returned keyword idea"
},
"keyword_info_normalized_with_bing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfoNormalizedWithInfo"
}
],
"description": "contains keyword search volume normalized with Bing search volume"
},
"keyword_info_normalized_with_clickstream": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfoNormalizedWithInfo"
}
],
"description": "contains keyword search volume normalized with clickstream data
"
},
"clickstream_keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ClickstreamKeywordInfo"
}
],
"description": "clickstream data for the returned keyword
to retrieve results for this field, the parameter include_clickstream_data must be set to true"
},
"keyword_properties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordProperties"
}
],
"description": "additional information about the keyword"
},
"serp_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpInfo"
}
],
"description": "SERP data
the value will be null if you didn't set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database"
},
"avg_backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvgBacklinksInfo"
}
],
"description": "backlink data for the returned keyword
this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 webpages ranking organically for the keyword"
},
"search_intent_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchIntentInfo"
}
],
"description": "search intent info for the returned keyword
learn about search intent in this help center article"
}
}
},
"Response463397119C53_KeywordInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword. This value is based on Google Ads data and can be between 0 and 1 (inclusive)"
},
"competition_level": {
"type": [
"string",
"null"
],
"description": "competition level
represents the relative level of competition associated with the given keyword in paid SERP only;
possible values: LOW, MEDIUM, HIGH
if competition level is unknown, the value is null;
learn more about the metric in this help center article"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "average monthly search volume rate
represents the (approximate) number of searches for the given keyword idea on google.com",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "product and service categories
you can download the full list of possible categories"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations"
},
"search_volume_trend": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeTrend"
}
],
"description": "search volume trend changes
represents search volume change in percent compared to the previous period"
}
}
},
"Response463397119C53_SearchVolumeTrend": {
"type": "object",
"properties": {
"monthly": {
"type": [
"integer",
"null"
],
"description": "search volume change in percent compared to the previous month"
},
"quarterly": {
"type": [
"integer",
"null"
],
"description": "search volume change in percent compared to the previous quarter"
},
"yearly": {
"type": [
"integer",
"null"
],
"description": "search volume change in percent compared to the previous year"
}
}
},
"Response463397119C53_KeywordInfoNormalizedWithInfo": {
"type": "object",
"properties": {
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when the dataset was updated\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nexample:\n2019-11-15 12:57:46 +00:00"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "current search volume rate of a keyword"
},
"is_normalized": {
"type": [
"boolean",
"null"
],
"description": "keyword info is normalized\nif true, values are normalized with Bing data"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly search volume rates\narray of objects with search volume rates in a certain month of a year"
}
}
},
"Response463397119C53_ClickstreamKeywordInfo": {
"type": "object",
"properties": {
"search_volume": {
"type": [
"integer",
"null"
],
"description": "average monthly search volume rate
represents the (approximate) number of searches for the given keyword idea on google.com",
"format": "int64"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"gender_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of estimated clickstream-based metrics by gender
learn more about how the metric is calculated in this help center article"
},
"age_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of clickstream-based metrics by age
learn more about how the metric is calculated in this help center article"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations"
}
}
},
"Response463397119C53_KeywordProperties": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"core_keyword": {
"type": [
"string",
"null"
],
"description": "main keyword in a group
contains the main keyword in a group determined by the synonym clustering algorithm
if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword"
},
"synonym_clustering_algorithm": {
"type": [
"string",
"null"
],
"description": "the algorithm used to identify synonyms
possible values:keyword_metrics - indicates the algorithm based on keyword_info parameterstext_processing - indicates the text-based algorithm
if the value is null, our database does not contain any keywords the corresponding algorithm could identify as synonymous with keyword"
},
"keyword_difficulty": {
"type": [
"integer",
"null"
],
"description": "difficulty of ranking in the first top-10 organic results for a keyword
indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100;
calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP;
learn more about the metric in this help center guide"
},
"detected_language": {
"type": [
"string",
"null"
],
"description": "detected language of the keyword
indicates the language of the keyword as identified by our system"
},
"is_another_language": {
"type": [
"boolean",
"null"
],
"description": "detected language of the keyword is different from the set language
if true, the language set in the request does not match the language determined by our system for a given keyword"
},
"words_count": {
"type": [
"integer",
"null"
],
"description": "number of words in the keyword
indicates how many words the keyword consists of",
"format": "int64"
}
}
},
"Response463397119C53_SerpInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"serp_item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP
possible item types:answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview;
note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "number of search results for the returned keyword",
"format": "int64"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"previous_updated_time": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date and time when SERP data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-10-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_AvgBacklinksInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"backlinks": {
"type": [
"number",
"null"
],
"description": "average number of backlinks"
},
"dofollow": {
"type": [
"number",
"null"
],
"description": "average number of dofollow links"
},
"referring_pages": {
"type": [
"number",
"null"
],
"description": "average number of referring pages"
},
"referring_domains": {
"type": [
"number",
"null"
],
"description": "average number of referring domains"
},
"referring_main_domains": {
"type": [
"number",
"null"
],
"description": "average number of referring main domains"
},
"rank": {
"type": [
"number",
"null"
],
"description": "average rank
learn more about the metric and its calculation formula in this help center article"
},
"main_domain_rank": {
"type": [
"number",
"null"
],
"description": "average main domain rank
learn more about the metric and its calculation formula in this help center article"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_SearchIntentInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"main_intent": {
"type": [
"string",
"null"
],
"description": "main search intent
possible values: informational, navigational, commercial, transactional"
},
"foreign_intent": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "supplementary search intents
possible values: informational, navigational, commercial, transactional"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_AmazonRankedSerpElement": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"serp_item": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonInfo"
}
],
"description": "contains data on the SERP element
the list of supported SERP elements can be found below"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure that we provided accurate results"
},
"serp_item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "direct URL to Amazon results
contains types of all search results (items) found in the returned SERP;
possible item types:amazon_serp, amazon_paid, editorial_recommendations, top_rated_from_our_brands, related_searches"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in Amazon SERP",
"format": "int64"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"previous_updated_time": {
"type": [
"string",
"null"
],
"description": "previous to the most recent update of SERP data
in the ISO 8601 format: “YYYY-MM-DDThh:mm:ss.sssssssZ”
example:2020-09-12T00:07:43.0733218Z"
}
}
},
"Provider463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
UTF-8 encoding
the keywords should be specified in the lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "keyword search depth
optional field
default value: 1;
number of the returned results depends on the value you set in this field;
you can specify a level from 0 to 4;
estimated number of keywords for each level (maximum):
0 - the keyword set in the keyword field
1 – 6 keywords
2 – 42 keywords
3 – 258 keywords
4 – 1554 keywords"
},
"include_seed_keyword": {
"type": [
"boolean",
"null"
],
"description": "include data for the seed keyword
optional field
if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response
default value: false"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to_true only core keywords will be returned, all highly similar keywords will be excluded;
default value: falsen"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "computer mouse",
"language_name": "English",
"location_code": 2840,
"limit": 5,
"include_seed_keyword": true
}
]
},
"Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"seed_keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"seed_keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonKeywordData"
}
],
"description": "keyword data for the seed keyword
fields in the object are identical to that of keyword_data"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveItem"
}
]
},
"description": "contains objects with keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsAmazonRelatedKeywordsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonKeywordData"
}
],
"description": "keyword data for the returned keyword"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "keyword search depth"
},
"related_keywords": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "list of related keywords
represents the list of search queries which are related to the keyword returned in the array above"
}
}
},
"Provider463397119C53_DataforseoLabsAppleAppCompetitorsLiveRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in
example:[\"intersections\",\">\",500][[\"competitor_metrics.app_store_search_organic.pos_1\",\"<>\",10],\"and\",[\"avg_position\",\">=\",\"10\"]][[[\"intersections\",\">=\",50],\"and\",[\"competitor_metrics.app_store_search_organic.pos_1\",\"in\",[1,5]]],
\"or\",
[\"sum_position\",\">=\",\"10000\"]]
optional field
you can use the same values as in the filters array to sort the results;
possible sorting types:asc - results will be sorted in the ascending order;desc - results will be sorted in the descending order;
you should use a comma to specify a sorting type;
example:[\"intersections,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"intersections,desc\",\"sum_position,asc\"][\"intersections,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned apps
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten apps in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_id": "686449807",
"language_name": "English",
"location_code": 2840,
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsAppleAppCompetitorsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleAppCompetitorsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleAppCompetitorsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleAppCompetitorsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleAppCompetitorsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsleAppCompetitorsLiveItem"
}
]
},
"description": "contains data related to the app_id and competitor applications"
}
}
},
"Response463397119C53_DataforseoLabsleAppCompetitorsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"avg_position": {
"type": [
"number",
"null"
],
"description": "average position of the app in Google Play SERP
Note: average position is calculated for intersected keywords only;
the value for a given application may differ when combined with different target applications",
"format": "float"
},
"sum_position": {
"type": [
"integer",
"null"
],
"description": "sum of all app positions in Google Play SERP
Note: sum position is calculated for intersected keywords only;
the value for a given application may differ when combined with different target applications"
},
"intersections": {
"type": [
"integer",
"null"
],
"description": "number of intersecting keywords"
},
"competitor_metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_AppMetricsInfo"
},
"description": "metrics for intersecting keywords
ranking data relevant to the keywords that the provided competitor application shares with the app in a POST request;
note: in this array ranking data is provided for the returned competitor's app_id"
},
"full_metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_AppMetricsInfo"
},
"description": "metrics for all keywords of the application
full overview of ranking data relevant to all keywords that the provided app_id is ranking for"
}
}
},
"Provider463397119C53_DataforseoLabsAppleAppIntersectionLiveRequestInfo": {
"type": "object",
"properties": {
"app_ids": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "ids of the target apps
required field
IDs of the target mobile applications on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320;
the ids should be specified the following way:
`\"app_ids\": {
\"1\": \"686449807\",
\"2\": \"382617920\"
}`
if you specify a single ID here, the API will return results only for one application;
the maximum number of app IDs you can specify in this object is 20"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in
example:[\"keyword_data.keyword_info.search_volume\",\">\",500][[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[intersection_result.382617920.rank_group\",\">=\",\"10\"]]
optional field
you can use the same values as in the filters array to sort the results;
possible sorting types:asc - results will be sorted in the ascending order;desc - results will be sorted in the descending order;
you should use a comma to specify a sorting type;
example:[\"intersection_result.382617920.rank_absolute,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"intersection_result.382617920.rank_absolute,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:[\"keyword_data.keyword_info.search_volume,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_ids": {
"1": "686449807",
"2": "382617920"
},
"language_name": "English",
"location_code": 2840,
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsAppleAppIntersectionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleAppIntersectionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleAppIntersectionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleAppIntersectionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleAppIntersectionLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_ids": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "ids of the apps in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsleAppIntersectionLiveItem"
}
]
},
"description": "contains data related to the ranking keywords for the app specified in the app_id field"
}
}
},
"Response463397119C53_DataforseoLabsleAppIntersectionLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"intersection_result": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlaySearchOrganic"
}
]
},
"description": "contains SERP data for the returned keyword
data will be provided in separate arrays for each app ID you specified in the app_ids object when setting a task;
depending on the number of specified app IDs, it can contain from 1 to 20 arrays named respectively"
}
}
},
"Provider463397119C53_DataforseoLabsAppleBulkAppMetricsLiveRequestInfo": {
"type": "object",
"properties": {
"app_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "ids of the apps
required field
IDs of mobile applications on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320;
the maximum number of IDs you can specify in this field is 1000"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_ids": [
"686449807",
"382617920"
],
"language_name": "English",
"location_code": 2840
}
]
},
"Response463397119C53_DataforseoLabsAppleBulkAppMetricsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleBulkAppMetricsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleBulkAppMetricsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleBulkAppMetricsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleBulkAppMetricsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsleBulkAppMetricsLiveItem"
}
]
},
"description": "contains data related to the ranking app metrics of the specified application"
}
}
},
"Response463397119C53_DataforseoLabsleBulkAppMetricsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_AppMetricsInfo"
},
"description": "metrics for the ranking keywords of the app
ranking data relevant to the keywords that the provided application ranks for on Google Play"
}
}
},
"Provider463397119C53_DataforseoLabsAppleKeywordsForAppLiveRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in
example:[\"keyword_data.keyword_info.search_volume\",\">\",500][[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[\"ranked_serp_element.serp_item.rank_group\",\">=\",\"10\"]]
optional field
you can use the same values as in the filters array to sort the results;
possible sorting types:asc - results will be sorted in the ascending order;desc - results will be sorted in the descending order;
you should use a comma to specify a sorting type;
example:[\"ranked_serp_element.serp_item.rank_group,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"ranked_serp_element.serp_item.rank_group,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:[\"keyword_data.keyword_info.search_volume,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_id": "686449807",
"language_name": "English",
"location_code": 2840,
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveItem"
}
]
},
"description": "contains data related to the ranking keywords for the app specified in the app_id field"
}
}
},
"Response463397119C53_DataforseoLabsAppleKeywordsForAppLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"ranked_serp_element": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppleRankedSerpElementInfo"
}
],
"description": "contains data on the domain's SERP element found for the returned keyword"
}
}
},
"Response463397119C53_AppleRankedSerpElementInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"serp_item": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppStoreSearchOrganic"
}
],
"description": "contains data on the SERP element
the list of supported SERP elements can be found below"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "number of search results for the returned keyword"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"previous_updated_time": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date and time when SERP data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-10-15 12:57:46 +00:00;
in this case, will equal null"
}
}
},
"Response463397119C53_DataforseoLabsAvailableFiltersResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAvailableFiltersTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAvailableFiltersTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsAvailableFiltersResultInfo"
}
]
},
"description": "array of results
contains the full list of available parameters that can be used for data filtration
the parameters are grouped by the endpoint they can be used with"
}
}
}
]
},
"Response463397119C53_DataforseoLabsAvailableFiltersResultInfo": {
"type": "object",
"properties": {
"related_keywords": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"keyword_suggestions": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"ranked_keywords": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"keyword_ideas": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"serp_competitors": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"relevant_pages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"subdomains": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"competitors_domain": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"categories_for_domain": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"keywords_for_categories": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"domain_intersection": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"page_intersection": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"top_searches": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"domain_metrics_by_categories": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"keywords_for_site": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"product_competitors": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"product_keyword_intersections": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"app_intersection": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"app_competitors": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"keywords_for_app": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"database_rows_count": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
}
},
"Provider463397119C53_DataforseoLabsGoogleAppCompetitorsLiveRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the app
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in
example:[\"intersections\",\">\",500][[\"competitor_metrics.google_play_search_organic.pos_1\",\"<>\",10],\"and\",[\"avg_position\",\">=\",\"10\"]][[[\"intersections\",\">=\",50],\"and\",[\"competitor_metrics.google_play_search_organic.pos_1\",\"in\",[1,5]]],
\"or\",
[\"sum_position\",\">=\",\"10000\"]]
optional field
you can use the same values as in the filters array to sort the results;
possible sorting types:asc - results will be sorted in the ascending order;desc - results will be sorted in the descending order;
you should use a comma to specify a sorting type;
example:[\"intersections,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"intersections,desc\",\"sum_position,asc\"][\"intersections,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned apps
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten apps in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_id": "org.telegram.messenger",
"language_name": "English",
"location_code": 2840,
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsGoogleAppCompetitorsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleAppCompetitorsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleAppCompetitorsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleAppCompetitorsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleAppCompetitorsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsleAppCompetitorsLiveItem"
}
]
},
"description": "contains data related to the app_id and competitor applications"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleAppIntersectionLiveRequestInfo": {
"type": "object",
"properties": {
"app_ids": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "ids of the target apps
required field
IDs of the target mobile applications on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger;;
the ids should be specified the following way:\"app_ids\": {
\"1\": \"org.telegram.messenger\",
\"2\": \"com.zhiliaoapp.musically\"
}
if you specify a single ID here, the API will return results only for one application;
the maximum number of app IDs you can specify in this object is 20"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in
example:[\"keyword_data.keyword_info.search_volume\",\">\",500][[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[intersection_result.382617920.rank_group\",\">=\",\"10\"]]
optional field
you can use the same values as in the filters array to sort the results;
possible sorting types:asc - results will be sorted in the ascending order;desc - results will be sorted in the descending order;
you should use a comma to specify a sorting type;
example:[\"intersection_result.382617920.rank_absolute,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"intersection_result.382617920.rank_absolute,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:[\"keyword_data.keyword_info.search_volume,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_ids": {
"1": "686449807",
"2": "382617920"
},
"language_name": "English",
"location_code": 2840,
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsGoogleAppIntersectionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleAppIntersectionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleAppIntersectionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleAppIntersectionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleAppIntersectionLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_ids": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "ids of the apps in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsleAppIntersectionLiveItem"
}
]
},
"description": "contains data related to the ranking keywords for the app specified in the app_id field"
}
}
},
"Response463397119C53_DataforseoLabsGoogleAvailableHistoryResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleAvailableHistoryTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleAvailableHistoryTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleAvailableHistoryResultInfo"
}
]
},
"description": "array of objects containing results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleAvailableHistoryResultInfo": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"description": "available dateindicates the date of the range available for setting in the Domain Metrics by Categories endpointexample:2022-05-16"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleBulkAppMetricsLiveRequestInfo": {
"type": "object",
"properties": {
"app_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "ids of the app
required field
IDs of the mobile applications on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger;
the maximum number of IDs you can specify in this field is 1000"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_ids": [
"org.telegram.messenger",
"com.zhiliaoapp.musically"
],
"language_name": "English",
"location_code": 2840
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkAppMetricsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkAppMetricsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkAppMetricsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkAppMetricsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkAppMetricsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsleBulkAppMetricsLiveItem"
}
]
},
"description": "contains data related to the ranking app metrics of the specified application"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000
the keywords will be converted to lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if don't specify location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if don't specify location_name
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"keywords": [
"dentist new york",
"pizza brooklyn",
"car dealer los angeles"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveItem"
}
]
},
"description": "contains keywords and related keyword difficulty scores"
}
}
},
"Response463397119C53_DataforseoLabsGoogleBulkKeywordDifficultyLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"keyword_difficulty": {
"type": [
"integer",
"null"
],
"description": "difficulty of ranking in the first top-10 organic results for a keyword
indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100;
calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP;
learn more about the metric in this help center guide"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "target domains, subdomains, and webpages
required field
you can specify domains, subdomains, and webpages in this field;
domains and subdomains should be specified without https:// and www.;
pages should be specified with absolute URL, including https:// and www.;
you can set up to 1000 domains, subdomains or webpages"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
if you use this field, you don't have to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
if you use this field, you don't have to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
if you use this field, you don’t need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
if you use this field, you don’t need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:en"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the responseitem_types array contains item types that are different from organic, the results will be ordered by the first item type in the array[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value: [\"organic\", \"paid\"]"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to_true, only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"dataforseo.com",
"cnn.com",
"forbes.com"
],
"location_code": 2840,
"language_code": "en",
"item_types": [
"organic",
"paid"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveItem"
}
]
},
"description": "array of items with relevant traffic estimation data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleBulkTrafficEstimationLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BulkMetricsBundleInfo"
}
],
"description": "traffic data relevant to the specified domain"
}
}
},
"Response463397119C53_BulkMetricsBundleInfo": {
"type": "object",
"properties": {
"organic": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BulkMetricsInfo"
}
],
"description": "traffic data from organic search"
},
"paid": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BulkMetricsInfo"
}
],
"description": "traffic data from paid search"
},
"local_pack": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BulkMetricsInfo"
}
],
"description": "traffic data from the local pack results in SERP"
},
"featured_snippet": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BulkMetricsInfo"
}
],
"description": "traffic data from the featured snippet results in Google SERP"
}
}
},
"Response463397119C53_BulkMetricsInfo": {
"type": "object",
"properties": {
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for
learn more about how the metric is calculated in this help center article"
},
"count": {
"type": [
"integer",
"null"
],
"description": "total count of organic SERPs that contain the domain",
"format": "int64"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain or subdomain
required field
the domain or subdomain name of the target website
the domain or subdomain should be specified without https:// and www."
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"include_subcategories": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subcategories will be included in the search
optional field
if set to false, the subcategories will be ignored
default value: false
learn more about the parameter in this help center article"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to_true, you will receive clickstream_etv, clickstream_gender_distribution, and_clickstream_age_distribution_fields with clickstream data in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
you can use this field to filter the results;
possible types of filtering:live — return metrics for SERPs in which the specified target currently has ranking results;lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn't have them during the last check;all — return metrics for both types of SERPs.
default value: live"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the responseitem_types array contains item types that are different from the organic object, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value: [\"organic\", \"paid\"]"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in
example:[\"metrics.organic.pos_1,\">\",0][[[\"metrics.organic.count\",\">=\",100],\"and\",[\"metrics.organic.pos_1\",\">\",0]],
\"or\",
[\"metrics.organic.etv\",\"in\",[10,100]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to specify a sorting type
example:[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"][\"metrics.organic.count,desc\"]
Note: if the item_types array contains item types that are different from the organic object, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned categories
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned categories
optional field
default value: 0
if you specify the 10 value, the first ten categories in the results array will be omitted and the data will be provided for the successive categories"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"language_code": "en",
"location_name": "United States",
"item_types": [
"paid",
"organic",
"featured_snippet",
"local_pack"
],
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain or subdomain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveItem"
}
]
},
"description": "contains relevant categories and related ranking data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForDomainLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "product and service categories
you can download the full list of possible categories"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "ranking data relevant to the specified domain or subdomain"
}
}
},
"Response463397119C53_DataforseoLabsMetricsInfo": {
"type": "object",
"properties": {
"pos_1": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #1"
},
"pos_2_3": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #2-3"
},
"pos_4_10": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #4-10"
},
"pos_11_20": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #11-20"
},
"pos_21_30": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #21-30"
},
"pos_31_40": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #31-40"
},
"pos_41_50": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #41-50"
},
"pos_51_60": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #51-60"
},
"pos_61_70": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #61-70"
},
"pos_71_80": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #71-80"
},
"pos_81_90": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #81-90"
},
"pos_91_100": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain or subdomain ranks #91-100"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
estimated organic monthly traffic to the domain or subdomain
calculated as the product of CTR (click-through-rate) and search volume values of all keywords in the category that the domain or subdomain ranks for
learn more about how the metric is calculated in this help center article"
},
"count": {
"type": [
"integer",
"null"
],
"description": "total count of organic SERPs that contain the domain or subdomain",
"format": "int64"
},
"estimated_paid_traffic_cost": {
"type": [
"number",
"null"
],
"description": "estimated cost of converting organic search traffic into paid
represents the estimated monthly cost (USD) of running ads for all keywords in the category that the domain or subdomain ranks for
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search
learn more about how the metric is calculated in this help center article"
},
"is_new": {
"type": [
"integer",
"null"
],
"description": "number of new ranked elements
indicates how many new ranked elements were found for the indicated target"
},
"is_up": {
"type": [
"integer",
"null"
],
"description": "rank went up
indicates how many ranked elements of the indicated target went up"
},
"is_down": {
"type": [
"integer",
"null"
],
"description": "rank went down
indicates how many ranked elements of the indicated target went down"
},
"is_lost": {
"type": [
"integer",
"null"
],
"description": "lost ranked elements
indicates how many ranked elements of the indicated target were previously presented in SERPs, but weren't found during the last check"
},
"clickstream_etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume based on clickstream data
calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for
to retrieve results for this field, the parameter include_clickstream_data must be set to true
learn more about how the metric is calculated in this help center article",
"format": "double"
},
"clickstream_gender_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of estimated clickstream-based metrics by gender
to retrieve results for this field, the parameter include_clickstream_data must be set to true
learn more about how the metric is calculated in this help center article"
},
"clickstream_age_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of clickstream-based metrics by age
to retrieve results for this field, the parameter include_clickstream_data must be set to true
learn more about how the metric is calculated in this help center article"
}
}
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000
the keywords will be converted to lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if don't specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if don't specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/google/categories_for_keywords/languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"keywords": [
"dentist new york",
"pizza brooklyn",
"car dealer los angeles"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveItem"
}
]
},
"description": "contains keywords and related keyword difficulty scores"
}
}
},
"Response463397119C53_DataforseoLabsGoogleCategoriesForKeywordsLiveItem": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "product and service categories
you can download the full list of possible categories"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain
required field
the domain name of the target website
the domain should be specified without https:// and www.
you can specify page URL, but the results will be specific to the domain in the specified URL"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the responseitem_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value: [\"organic\", \"paid\"]"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to_true, you will receive clickstream_etv, clickstream_gender_distribution, and_clickstream_age_distribution_fields with clickstream data in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in
example:[\"metrics.organic.count\",\">\",50][[[\"metrics.organic.count\",\">=\",50],\"and\",[\"metrics.organic.pos_1\",\"in\",[1,5]]],
\"or\",
[\"metrics.organic.etv\",\">=\",\"100\"]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to specify a sorting type
example:[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"][\"metrics.organic.count,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"max_rank_group": {
"type": [
"integer",
"null"
],
"description": "maximum rank up to which competitors will be considered
optional field
default value: 10010 here, we will extract competitors from the top 10 Google search results only"
},
"exclude_top_domains": {
"type": [
"boolean",
"null"
],
"description": "indicates whether to exclude world's largest websites
optional field
default value: false
set to true if you want to get highly-relevant competitors excluding the websites listed below:wikipedia.org"
},
"exclude_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "exclude domains from the results
pinterest.com
amazon.com
google.com
facebook.com
wordpress.com
medium.com
quora.com
reddit.com
youtube.com
ebay.com
uol.com.br
instagram.com
olx.com
twitter.com
linkedin.com
slideshare.net
optional field
use this parameter to exclude specific domains from the results
Note: you can specify up to 1000 domains in this array\"exclude_domains\": ["
},
"intersecting_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "additional domains for improving results accuracy
\"reddit.com\",
\"youtube.com\"
]
optional field
to improve the accuracy of the result, you can specify domains that are known to intersect with the target in SERPs;
if you use this array, metrics in the result will be based on SERPs where both target website and intersecting_domains appear;
Note: you can specify up to 20 domains in this array"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to_true, only core keywords will be returned, all highly similar keywords will be excluded;
default value: falsen"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "newmouth.com",
"intersecting_domains": [
"dentaly.org",
"health.com",
"trysnow.com"
],
"language_name": "English",
"location_code": 2840,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveItem"
}
]
},
"description": "contains data related to the target and competitor domains"
}
}
},
"Response463397119C53_DataforseoLabsGoogleCompetitorsDomainLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain name"
},
"avg_position": {
"type": [
"number",
"null"
],
"description": "average position of the domain in SERP
Note: average position is calculated for intersected keywords only;
the value for a given domain may differ when combined with different target websites",
"format": "float"
},
"sum_position": {
"type": [
"integer",
"null"
],
"description": "sum of all domain positions in SERP
Note: average position is calculated for intersected keywords only;
the value for a given domain may differ when combined with different target websites"
},
"intersections": {
"type": [
"integer",
"null"
],
"description": "number of intersecting keywords"
},
"full_domain_metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "metrics for all keywords of the domain
full overview of ranking and traffic data relevant to all keywords that the provided domain is ranking for"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "metrics for intersecting keywords
ranking and traffic data relevant to the keywords that the provided domain shares with the target domain
note: in this array ranking and traffic data is provided for the target considering the keywords target shares in search with the competitor's domain"
},
"competitor_metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "metrics for intersecting keywords
ranking and traffic data relevant to the keywords that the provided domain shares with the target domain
note: in this array ranking and traffic data is provided for the returned competitor's domain"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleDomainIntersectionLiveRequestInfo": {
"type": "object",
"properties": {
"target1": {
"type": "string",
"description": "domain required field the domain name of the first target website the domain should be specified without https:// and www."
},
"target2": {
"type": "string",
"description": "domain required field the domain name of the second target website the domain should be specified without https:// and www."
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location required field if you don't specify location_code Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code required field if you don't specify location_name Note: it is required to specify either location_name or location_code you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: 2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language required field if you don't specify language_code Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code required field if you don't specify language_name Note: it is required to specify either language_name or language_code you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages example: en"
},
"intersections": {
"type": [
"boolean",
"null"
],
"description": "domain intersections in SERP optional field if you set intersections to true, you will get the keywords for which both target domains specified as target1 and target2 have results within the same SERP; the corresponding SERP elements for both domains will be provided in the results array Note: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million if you specify intersections: false, you will get the keywords for which the domain specified as target1 has results in SERP, and the domain specified as target2 doesn't; thus, the corresponding SERP elements and other data will be provided for the domain specified as target1only default value: true"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "search results type indicates type of search results included in the response optional field possible values: [\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"] default value: [\"organic\", \"paid\"]"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword optional field if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result optional field if the parameter is set to true, you will receive clickstream_keyword_info, clickstream_etv, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response default value: false with this parameter enabled, you will be charged double the price for the request learn more about how clickstream-based metrics are calculated in this help center article"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords optional field default value: 100 maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the items array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters optional field you can add several filters at once (8 filters maximum) you should set a logical operator and, or between the conditions the following operators are supported: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters example: [\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]] [[\"first_domain_serp_element.etv\",\">\",0],\"and\",[\"first_domain_serp_element.description\",\"like\",\"%goat%\"]] [[\"keyword_data.keyword_info.search_volume\",\">\",100], \"and\", [[\"first_domain_serp_element.description\",\"like\",\"%goat%\"], \"or\", [\"second_domain_serp_element.type\",\"=\",\"organic\"]]] for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc - results will be sorted in the ascending order desc - results will be sorted in the descending order you should use a comma to set up a sorting parameter example: [\"keyword_data.keyword_info.competition,desc\"] default rule: [\"keyword_data.keyword_info.search_volume,desc\"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: [\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target1": "mom.com",
"target2": "quora.com",
"language_code": "en",
"location_code": 2840,
"include_serp_info": true,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target1": {
"type": [
"string",
"null"
],
"description": "the first target domain in a POST array"
},
"target2": {
"type": [
"string",
"null"
],
"description": "the second target domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveItem"
}
]
},
"description": "contains keywords, relevant SERP elements and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleDomainIntersectionLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"first_domain_serp_element": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
],
"description": "contains data on the first domain's SERP element found for the returned keyword the list of supported SERP elements can be found below"
},
"second_domain_serp_element": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
],
"description": "contains data on the second domain's SERP element found for the returned keyword the list of supported SERP elements can be found below"
}
}
},
"Response463397119C53_BaseDataforseoLabsApiElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:
left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"organic": "#/components/schemas/Response463397119C53_DataLabsOrganicSerpElementItem",
"featured_snippet": "#/components/schemas/Response463397119C53_DataLabsFeaturedSnippetSerpElementItem",
"paid": "#/components/schemas/Response463397119C53_DataLabsPaidSerpElementItem",
"local_pack": "#/components/schemas/Response463397119C53_DataLabsLocalPackSerpElementItem",
"answer_box": "#/components/schemas/Response463397119C53_DataLabsAnswerBoxSerpElementItem",
"carousel": "#/components/schemas/Response463397119C53_DataLabsCarouselSerpElementItem",
"multi_carousel": "#/components/schemas/Response463397119C53_DataLabsMultiCarouselSerpElementItem",
"google_flights": "#/components/schemas/Response463397119C53_DataLabsGoogleFlightsSerpElementItem",
"google_reviews": "#/components/schemas/Response463397119C53_DataLabsGoogleReviewsSerpElementItem",
"google_posts": "#/components/schemas/Response463397119C53_DataLabsGooglePostsSerpElementItem",
"images": "#/components/schemas/Response463397119C53_DataLabsImagesSerpElementItem",
"jobs": "#/components/schemas/Response463397119C53_DataLabsJobsSerpElementItem",
"knowledge_graph": "#/components/schemas/Response463397119C53_DataLabsKnowledgeGraphSerpElementItem",
"hotels_pack": "#/components/schemas/Response463397119C53_DataLabsHotelsPackSerpElementItem",
"map": "#/components/schemas/Response463397119C53_DataLabsMapSerpElementItem",
"people_also_ask": "#/components/schemas/Response463397119C53_DataLabsPeopleAlsoAskSerpElementItem",
"related_searches": "#/components/schemas/Response463397119C53_DataLabsRelatedSearchesSerpElementItem",
"people_also_search": "#/components/schemas/Response463397119C53_DataLabsPeopleAlsoSearchSerpElementItem",
"shopping": "#/components/schemas/Response463397119C53_DataLabsShoppingSerpElementItem",
"top_stories": "#/components/schemas/Response463397119C53_DataLabsTopStoriesSerpElementItem",
"twitter": "#/components/schemas/Response463397119C53_DataLabsTwitterSerpElementItem",
"video": "#/components/schemas/Response463397119C53_DataLabsVideoSerpElementItem",
"events": "#/components/schemas/Response463397119C53_DataLabsEventsSerpElementItem",
"recipes": "#/components/schemas/Response463397119C53_DataLabsRecipesSerpElementItem",
"top_sights": "#/components/schemas/Response463397119C53_DataLabsTopSightsSerpElementItem",
"scholarly_articles": "#/components/schemas/Response463397119C53_DataLabsScholarlyArticlesSerpElementItem",
"popular_products": "#/components/schemas/Response463397119C53_DataLabsPopularProductsSerpElementItem",
"questions_and_answers": "#/components/schemas/Response463397119C53_DataLabsQuestionsAndAnswersSerpElementItem",
"find_results_on": "#/components/schemas/Response463397119C53_DataLabsFindResultsOnSerpElementItem",
"stocks_box": "#/components/schemas/Response463397119C53_DataLabsStocksBoxSerpElementItem",
"commercial_units": "#/components/schemas/Response463397119C53_DataLabsCommercialUnitsSerpElementItem",
"local_services": "#/components/schemas/Response463397119C53_DataLabsLocalServicesSerpElementItem",
"google_hotels": "#/components/schemas/Response463397119C53_DataLabsGoogleHotelsSerpElementItem",
"math_solver": "#/components/schemas/Response463397119C53_DataLabsMathSolverSerpElementItem",
"mention_carousel": "#/components/schemas/Response463397119C53_DataLabsMentionCarouselSerpElementItem",
"podcasts": "#/components/schemas/Response463397119C53_DataLabsPodcastsSerpElementItem",
"visual_stories": "#/components/schemas/Response463397119C53_DataLabsVisualStoriesSerpElementItem",
"found_on_web": "#/components/schemas/Response463397119C53_DataLabsFoundOnWebSerpElementItem",
"explore_brands": "#/components/schemas/Response463397119C53_DataLabsExploreBrandsSerpElementItem",
"courses": "#/components/schemas/Response463397119C53_DataLabsCoursesSerpElementItem"
}
}
},
"Response463397119C53_DataLabsOrganicSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "subdomain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "relevant website name in SERP"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an image
Note: this check no longer appears in SERP"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video
Note: this check no longer appears in SERP"
},
"is_featured_snippet": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is a featured_snippet
Note: this check no longer appears in SERP"
},
"is_malicious": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as malicious
Note: this check no longer appears in SERP"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of properties detected for the SERP element
lists the properties that are true for this element
each value in the array represents a detected property
example:
if is_image is present in the array, the element contains an image
possible values in the array:is_image, is_video, is_featured_snippet, amp_version, is_malicious, is_web_story, is_highly_cited
equals null if none of the properties are detected for the element
learn more about the checks array in this Help Center article"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"pre_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended before the result description in SERP"
},
"extended_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended after the result description in SERP"
},
"amp_version": {
"type": [
"boolean",
"null"
],
"description": "Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version
Note: this check no longer appears in SERP"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
},
"about_this_result": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AboutThisResultElement"
}
],
"description": "contains information from the 'About this result' panel
'About this result' panel provides additional context about why Google returned this result for the given query;
this feature appears after clicking on the three dots next to most results",
"deprecated": true
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "primary domain name in SERP"
},
"relative_url": {
"type": [
"string",
"null"
],
"description": "URL in SERP that does not specify the HTTPs protocol and domain name"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
estimated organic monthly traffic to the domain or webpage;
calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain or webpage rank for;
learn more about how the metric is calculated in this help center article"
},
"estimated_paid_traffic_cost": {
"type": [
"number",
"null"
],
"description": "estimated cost of converting organic search traffic into paid
represents the estimated monthly cost of running ads for all keywords that a domain or webpage ranks for;
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search;
learn more about how the metric is calculated in this help center article"
},
"clickstream_etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume based on clickstream data
calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain or webpage ranks for;
to retrieve results for this field, the parameter include_clickstream_data must be set to true;
learn more about how the metric is calculated in this help center article",
"format": "double"
},
"rank_changes": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankChanges"
}
],
"properties": {
"previous_rank_absolute": {
"type": [
"number",
"null"
],
"description": "previous absolute rank in SERP\nindicates previous rank of the element in Google SERP;\nif this element is new, the value will be null"
},
"is_new": {
"type": "boolean",
"description": "element was previously present in SERP\nif the value is true, previously collected SERP didn’t contain this element"
},
"is_up": {
"type": "boolean",
"description": "rank of this element went up\nif the value is true, position of the element in SERP is higher compared to the previous check"
},
"is_down": {
"type": "boolean",
"description": "rank of this element went down\nif the value is true, position of the element in SERP is lower compared to the previous check"
}
},
"description": "changes in rankings
contains information about the ranking changes of the SERP element since the previous_updated_time"
},
"backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksInfo"
}
],
"description": "backlinks information for the relevant page URL"
},
"rank_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankInfo"
}
],
"description": "page and domain rank information"
}
}
}
]
},
"Response463397119C53_AboutThisResultElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "result’s URL"
},
"source": {
"type": [
"string",
"null"
],
"description": "source of additional information about the result"
},
"source_info": {
"type": [
"string",
"null"
],
"description": "additional information about the result\ndescription of the website from Wikipedia or another additional context"
},
"source_url": {
"type": [
"string",
"null"
],
"description": "URL to full information from the 'source'"
},
"language": {
"type": [
"string",
"null"
],
"description": "the language of the result"
},
"location": {
"type": [
"string",
"null"
],
"description": "location for which the result is relevant"
},
"search_terms": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "matching search terms that appear in the result"
},
"related_terms": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "related search terms that appear in the result"
}
},
"deprecated": true
},
"Response463397119C53_RankChanges": {
"type": "object",
"properties": {
"previous_rank_absolute": {
"type": [
"integer",
"null"
],
"description": "previous absolute rank in SERP
indicates previous rank of the element in Google SERP;
if this element is new, the value will be null"
},
"is_new": {
"type": [
"boolean",
"null"
],
"description": "number of new ranked elements
indicates how many new ranked elements were found for this domain or webpage"
},
"is_up": {
"type": [
"boolean",
"null"
],
"description": "rank went up
indicates how many ranked elements of this target went up in Google Search"
},
"is_down": {
"type": [
"boolean",
"null"
],
"description": "rank went down
indicates how many ranked elements of this target went down in Google Search"
}
}
},
"Response463397119C53_BacklinksInfo": {
"type": "object",
"properties": {
"referring_domains": {
"type": [
"integer",
"null"
],
"description": "average number of referring domains",
"format": "int64"
},
"referring_main_domains": {
"type": [
"integer",
"null"
],
"description": "average number of referring main domains",
"format": "int64"
},
"referring_pages": {
"type": [
"integer",
"null"
],
"description": "average number of referring pages",
"format": "int64"
},
"dofollow": {
"type": [
"integer",
"null"
],
"description": "average number of dofollow links",
"format": "int64"
},
"backlinks": {
"type": [
"integer",
"null"
],
"description": "average number of backlinks",
"format": "int64"
},
"time_update": {
"type": [
"string",
"null"
],
"description": "date and time when backlink data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:
2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_RankInfo": {
"type": "object",
"properties": {
"page_rank": {
"type": [
"integer",
"null"
],
"description": "page rank
page_rank is calculated based on the method for node ranking in a linked database - a principle used in the original Google PageRank algorithm;
learn more about the metric and how it is calculated in this help center article"
},
"main_domain_rank": {
"type": [
"integer",
"null"
],
"description": "average main domain rank
learn more about the metric and its calculation formula in this help center article"
}
}
},
"Response463397119C53_DataLabsFeaturedSnippetSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "subdomain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"featured_title": {
"type": [
"string",
"null"
],
"description": "the title of the featured snippets source page"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "results table
if there are none, equals null"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "primary domain name in SERP"
},
"relative_url": {
"type": [
"string",
"null"
],
"description": "URL in SERP that does not specify the HTTPs protocol and domain name"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
estimated organic monthly traffic to the domain or webpage;
calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain or webpage rank for;
learn more about how the metric is calculated in this help center article"
},
"estimated_paid_traffic_cost": {
"type": [
"number",
"null"
],
"description": "estimated cost of converting organic search traffic into paid
represents the estimated monthly cost of running ads for all keywords that a domain or webpage ranks for;
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search;
learn more about how the metric is calculated in this help center article"
},
"clickstream_etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume based on clickstream data
calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain or webpage ranks for;
to retrieve results for this field, the parameter include_clickstream_data must be set to true;
learn more about how the metric is calculated in this help center article",
"format": "double"
},
"rank_changes": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankChanges"
}
],
"properties": {
"previous_rank_absolute": {
"type": [
"number",
"null"
],
"description": "previous absolute rank in SERP\nindicates previous rank of the element in Google SERP;\nif this element is new, the value will be null"
},
"is_new": {
"type": "boolean",
"description": "element was previously present in SERP\nif the value is true, previously collected SERP didn’t contain this element"
},
"is_up": {
"type": "boolean",
"description": "rank of this element went up\nif the value is true, position of the element in SERP is higher compared to the previous check"
},
"is_down": {
"type": "boolean",
"description": "rank of this element went down\nif the value is true, position of the element in SERP is lower compared to the previous check"
}
},
"description": "changes in rankings
contains information about the ranking changes of the SERP element since the previous_updated_time"
},
"backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksInfo"
}
],
"description": "backlinks information for the relevant page URL"
},
"rank_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankInfo"
}
],
"description": "page and domain rank information"
}
}
}
]
},
"Response463397119C53_DataLabsPaidSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "subdomain in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL in SERP"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of properties detected for the SERP elementlists the properties that are true for this elementeach value in the array represents a detected property example:if is_image is present in the array, the element contains an imagepossible values in the array:is_image, is_video, is_featured_snippet, amp_version, is_malicious, is_web_story, is_highly_citedequals null if none of the properties are detected for the elementlearn more about the checks array in this Help Center article"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"extra": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"description_rows": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extended description if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AdLinkElement"
}
]
},
"description": "sitelinks the links shown below some of Google's search results if there are none, equals null"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "primary domain name in SERP"
},
"relative_url": {
"type": [
"string",
"null"
],
"description": "URL in SERP that does not specify the HTTPs protocol and domain name"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of the returned keyword learn more about how the metric is calculated in this help center article"
},
"estimated_paid_traffic_cost": {
"type": [
"number",
"null"
],
"description": "estimated cost of paid monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values learn more about how the metric is calculated in this help center article"
},
"clickstream_etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article",
"format": "double"
},
"rank_changes": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankChanges"
}
],
"properties": {
"previous_rank_absolute": {
"type": [
"number",
"null"
],
"description": "previous absolute rank in SERP\nindicates previous rank of the element in Google SERP;\nif this element is new, the value will be null"
},
"is_new": {
"type": "boolean",
"description": "element was previously present in SERP\nif the value is true, previously collected SERP didn’t contain this element"
},
"is_up": {
"type": "boolean",
"description": "rank of this element went up\nif the value is true, position of the element in SERP is higher compared to the previous check"
},
"is_down": {
"type": "boolean",
"description": "rank of this element went down\nif the value is true, position of the element in SERP is lower compared to the previous check"
}
},
"description": "changes in rankings contains information about the ranking changes of the SERP element since the previous_updated_time"
},
"backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksInfo"
}
],
"description": "backlinks information for the ranked website"
},
"rank_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankInfo"
}
],
"description": "page and domain rank information"
}
}
}
]
},
"Response463397119C53_AdLinkElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the link"
},
"url": {
"type": [
"string",
"null"
],
"description": "reference page URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"ad_aclk": {
"type": [
"string",
"null"
],
"description": "the identifier of the ad"
}
}
},
"Response463397119C53_DataLabsLocalPackSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "subdomain in SERP"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL in SERP"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is an ad"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating the popularity rate based on reviews and displayed in SERP"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "primary domain name in SERP"
},
"relative_url": {
"type": [
"string",
"null"
],
"description": "URL in SERP that does not specify the HTTPs protocol and domain name"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume estimated organic monthly traffic to the domain calculated as the product of CTR (click-through-rate) and search volume values of the returned keyword learn more about how the metric is calculated in this help center article"
},
"estimated_paid_traffic_cost": {
"type": [
"number",
"null"
],
"description": "estimated cost of paid monthly search traffic represents the estimated cost of paid monthly traffic (USD) based on etv and cpc values learn more about how the metric is calculated in this help center article"
},
"clickstream_etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume based on clickstream data calculated as the product of click-through-rate and clickstream search volume values of all keywords the domain ranks for to retrieve results for this field, the parameter include_clickstream_data must be set to true learn more about how the metric is calculated in this help center article",
"format": "double"
},
"rank_changes": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankChanges"
}
],
"properties": {
"previous_rank_absolute": {
"type": [
"number",
"null"
],
"description": "previous absolute rank in SERP\nindicates previous rank of the element in Google SERP;\nif this element is new, the value will be null"
},
"is_new": {
"type": "boolean",
"description": "element was previously present in SERP\nif the value is true, previously collected SERP didn’t contain this element"
},
"is_up": {
"type": "boolean",
"description": "rank of this element went up\nif the value is true, position of the element in SERP is higher compared to the previous check"
},
"is_down": {
"type": "boolean",
"description": "rank of this element went down\nif the value is true, position of the element in SERP is lower compared to the previous check"
}
},
"description": "changes in rankings contains information about the ranking changes of the SERP element since the previous_updated_time"
},
"backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksInfo"
}
],
"description": "backlinks information for the ranked website"
},
"rank_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankInfo"
}
],
"description": "page and domain rank information"
}
}
}
]
},
"Response463397119C53_DataLabsAnswerBoxSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "text
if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_DataLabsCarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsCarouselElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_DataforseoLabsCarouselElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "subtitle of the item"
}
}
},
"Response463397119C53_DataLabsMultiCarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MultiCarouselElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_MultiCarouselElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"multi_carousel_snippets": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpApiCarouselElement"
}
]
},
"description": "multi_carousel_snippet results
if there are none, equals null"
}
}
},
"Response463397119C53_SerpApiCarouselElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the element"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
}
}
},
"Response463397119C53_DataLabsGoogleFlightsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFlightsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_GoogleFlightsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
}
}
},
"Response463397119C53_DataLabsGoogleReviewsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "the identifier of a place"
},
"feature": {
"type": [
"string",
"null"
],
"description": "the additional feature of the review"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
}
}
}
]
},
"Response463397119C53_DataLabsGooglePostsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"posts_id": {
"type": [
"string",
"null"
],
"description": "the identifier of the google_posts feature"
},
"feature": {
"type": [
"string",
"null"
],
"description": "the additional feature of the review"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
}
}
}
],
"deprecated": true
},
"Response463397119C53_DataLabsImagesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "historical SERPs and related data found in the database"
},
"related_image_searches": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedImageSearchesElement"
}
],
"description": "contains keywords and images related to the specified search term
if there are none, equals null",
"deprecated": true
}
}
}
]
},
"Response463397119C53_RelatedImageSearchesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"alt": {
"type": [
"string",
"null"
],
"description": "alt tag of the image"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
}
},
"deprecated": true
},
"Response463397119C53_DataLabsJobsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_JobsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_JobsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"location": {
"type": [
"string",
"null"
],
"description": "location for which the job vacancy is posted"
},
"author": {
"type": [
"string",
"null"
],
"description": "author"
},
"job_posted_time": {
"type": [
"string",
"null"
],
"description": "the time when the job was posted"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"contract_type": {
"type": [
"string",
"null"
],
"description": "contract type"
},
"salary": {
"type": [
"string",
"null"
],
"description": "salary"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
}
}
},
"Response463397119C53_DataLabsKnowledgeGraphSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "subtitle of the item"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"card_id": {
"type": [
"string",
"null"
],
"description": "card id"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image from knowledge graph"
},
"logo_url": {
"type": [
"string",
"null"
],
"description": "URL of the logo from knowledge graph"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:
left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"knowledge_graph_images_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphImagesItemElementItem",
"knowledge_graph_carousel_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphCarouselItemElementItem",
"knowledge_graph_description_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphDescriptionItemElementItem",
"knowledge_graph_list_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphListItemElementItem",
"knowledge_graph_part_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphPartItemElementItem",
"knowledge_graph_expanded_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphExpandedItemElementItem",
"knowledge_graph_row_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphRowItemElementItem",
"knowledge_graph_shopping_item": "#/components/schemas/Response463397119C53_DataforseoLabsKnowledgeGraphShoppingItemElementItem"
}
}
},
"Response463397119C53_DataforseoLabsKnowledgeGraphImagesItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphImagesElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphImagesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL of the Ad element in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"alt": {
"type": [
"string",
"null"
],
"description": "alt tag of the image"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
}
},
"Response463397119C53_DataforseoLabsKnowledgeGraphCarouselItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:
action:listen_artist"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphListElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphListElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the item"
},
"url": {
"type": [
"string",
"null"
],
"description": "sitelink URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
}
},
"Response463397119C53_DataforseoLabsKnowledgeGraphDescriptionItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "description content"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphLinkElementInfo"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphLinkElementInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
}
},
"Response463397119C53_DataforseoLabsKnowledgeGraphListItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:
action:listen_artist"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphListElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_DataforseoLabsKnowledgeGraphPartItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:
action:listen_artist"
},
"text": {
"type": [
"string",
"null"
],
"description": "description content"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_DataforseoLabsKnowledgeGraphExpandedItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:
action:listen_artist"
},
"expanded_element": {
"type": [
"object",
"null"
],
"description": "link of the element"
}
}
}
]
},
"Response463397119C53_DataforseoLabsKnowledgeGraphRowItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:
action:listen_artist"
},
"text": {
"type": [
"string",
"null"
],
"description": "description content"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_DataforseoLabsKnowledgeGraphShoppingItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:
action:listen_artist"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphShoppingElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphShoppingElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing details
contains the pricing details of the product or service featured in the result;
if there is none, equals null"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"marketplace": {
"type": [
"string",
"null"
],
"description": "merchant account provider
ecommerce site that hosts products or websites of individual sellers under the same merchant account
example:by Google"
},
"marketplace_url": {
"type": [
"string",
"null"
],
"description": "URL to the merchant account provider
ecommerce site that hosts products or websites of individual sellers under the same merchant account"
}
}
},
"Response463397119C53_DataLabsHotelsPackSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of stay
in the format “year-month-date”
example:
2019-11-15"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of stay
in the format “year-month-date”
example:
2019-11-17"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelsPackElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_HotelsPackElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price indicated in the element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"hotel_identifier": {
"type": [
"string",
"null"
],
"description": "unique hotel identifier
unique hotel identifier assigned by Google;
example: \"CgoIjaeSlI6CnNpVEAE\""
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is an ad"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
}
}
},
"Response463397119C53_DataLabsMapSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
}
}
}
]
},
"Response463397119C53_DataLabsPeopleAlsoAskSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PeopleAlsoAskElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_PeopleAlsoAskElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"seed_question": {
"type": [
"string",
"null"
],
"description": "question that triggered additional expanded elements"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"expanded_element": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiPeopleAlsoAskExpandedElementItem"
}
]
},
"description": "expanded element"
}
}
},
"Response463397119C53_BaseSerpApiPeopleAlsoAskExpandedElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"people_also_ask_expanded_element": "#/components/schemas/Response463397119C53_SerpApiPeopleAlsoAskExpandedElementItem",
"people_also_ask_ai_overview_expanded_element": "#/components/schemas/Response463397119C53_SerpApiPeopleAlsoAskAiOverviewExpandedElementItem"
}
}
},
"Response463397119C53_SerpApiPeopleAlsoAskExpandedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiPeopleAlsoAskExpandedElementItem"
}
]
},
{
"type": "object",
"properties": {
"featured_title": {
"type": [
"string",
"null"
],
"description": "the title of the featured snippets source page"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "source domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the carousel item"
},
"description": {
"type": [
"string",
"null"
],
"description": "description"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "results table
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiPeopleAlsoAskAiOverviewExpandedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiPeopleAlsoAskExpandedElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
"description": "items present in the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "additional references relevant to the item
includes references to webpages that may have been used to generate the ai_overview"
},
"asynchronous_ai_overview": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is loaded asynchronously
if true, the people_also_ask_ai_overview_expanded_element element is loaded asynchronously;
if false, the people_also_ask_ai_overview_expanded_element element is loaded from cache"
}
}
}
]
},
"Response463397119C53_BaseSerpApiAiOverviewElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"ai_overview_element": "#/components/schemas/Response463397119C53_SerpApiAiOverviewElementItem",
"ai_overview_expanded_element": "#/components/schemas/Response463397119C53_SerpApiAiOverviewExpandedElementItem",
"ai_overview_video_element": "#/components/schemas/Response463397119C53_SerpApiAiOverviewVideoElementItem",
"ai_overview_table_element": "#/components/schemas/Response463397119C53_SerpApiAiOverviewTableElementItem"
}
}
},
"Response463397119C53_SerpApiAiOverviewElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"text": {
"type": [
"string",
"null"
],
"description": "additional text of the element in SERP"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "website links featured in the element"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there is none, equals null"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
}
]
},
"Response463397119C53_AiModeAiOverviewReferenceInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain name of the reference"
},
"url": {
"type": [
"string",
"null"
],
"description": "link URL"
},
"title": {
"type": [
"string",
"null"
],
"description": "link anchor text"
},
"text": {
"type": [
"string",
"null"
],
"description": "text of the component"
}
}
},
"Response463397119C53_SerpApiAiOverviewExpandedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"text": {
"type": [
"string",
"null"
],
"description": "additional text of the element in SERP"
},
"components": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOverviewExpandedComponent"
}
]
},
"description": "array of components of the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
}
]
},
"Response463397119C53_AiOverviewExpandedComponent": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "reference page title"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
},
"Response463397119C53_SerpApiAiOverviewVideoElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information for the video"
},
"url": {
"type": [
"string",
"null"
],
"description": "reference page URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in link"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image"
},
"source": {
"type": [
"string",
"null"
],
"description": "web source of the shopping element
indicates the source of information included in the element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date when the video was published or indexed
example: Apr 26, 2024"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the video was published or indexed
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_SerpApiAiOverviewTableElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table element"
}
}
}
]
},
"Response463397119C53_DataLabsRelatedSearchesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_DataLabsPeopleAlsoSearchSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_DataLabsShoppingSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ShoppingElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_ShoppingElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price indicated in the element"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"marketplace": {
"type": [
"string",
"null"
],
"description": "merchant account provider
commerce site that hosts products or websites of individual sellers under the same merchant account
example:by Google"
},
"marketplace_url": {
"type": [
"string",
"null"
],
"description": "relevant marketplace URL
URL of the page on the marketplace website where the product is hosted"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
}
}
},
"Response463397119C53_DataLabsTopStoriesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopStoriesElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_TopStoriesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"date": {
"type": [
"string",
"null"
],
"description": "the date when the page source of the element was published"
},
"amp_version": {
"type": [
"boolean",
"null"
],
"description": "Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version
Note: this check no longer appears in SERP"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"badges": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "badges relevant to the element"
}
}
},
"Response463397119C53_DataLabsTwitterSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TwitterElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_TwitterElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"tweet": {
"type": [
"string",
"null"
],
"description": "tweet message"
},
"date": {
"type": [
"string",
"null"
],
"description": "the date when the page source of the element was published"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
}
}
},
"Response463397119C53_DataLabsVideoSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_VideoElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_VideoElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"source": {
"type": [
"string",
"null"
],
"description": "URL to the video source"
},
"preview": {
"type": [
"string",
"null"
],
"description": "URL to the video preview image"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
}
}
},
"Response463397119C53_DataLabsEventsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_EventsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_EventsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
}
}
},
"Response463397119C53_DataLabsRecipesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RecipesElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_RecipesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"time": {
"type": [
"string",
"null"
],
"description": "the total time it takes to prepare the cook the dish"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
}
}
},
"Response463397119C53_DataLabsTopSightsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopSightsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_TopSightsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
}
}
},
"Response463397119C53_DataLabsScholarlyArticlesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ScholarlyArticlesElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_ScholarlyArticlesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"author": {
"type": [
"string",
"null"
],
"description": "author"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
}
}
},
"Response463397119C53_DataLabsPopularProductsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PopularProductsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_PopularProductsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"more_sellers": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the product is sold by multiple sellers"
},
"seller": {
"type": [
"string",
"null"
],
"description": "seller of the product"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price indicated in the element"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
},
"product_identifiers": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ProductIdentifiers"
}
],
"description": "identifiers of the product
can include the following identifiers: product_id, data_docid, gid"
}
}
},
"Response463397119C53_ProductIdentifiers": {
"type": "object",
"properties": {
"product_id": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Google Shopping
example:4485466949985702538
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": [
"string",
"null"
],
"description": "unique identifier of the SERP data element
example:17363035694596624076"
},
"gid": {
"type": [
"string",
"null"
],
"description": "global product identifier on Google Shopping
example:4702526954592161872
learn more about the parameter in this help center guide"
}
}
},
"Response463397119C53_DataLabsQuestionsAndAnswersSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_QuestionsAndAnswersElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_QuestionsAndAnswersElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"question_text": {
"type": [
"string",
"null"
],
"description": "question included in the item"
},
"answer_text": {
"type": [
"string",
"null"
],
"description": "answer included in the item"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"votes": {
"type": [
"integer",
"null"
],
"description": "answer upvotes from the source"
}
}
},
"Response463397119C53_DataLabsFindResultsOnSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FindResultsOnElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_FindResultsOnElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
}
}
},
"Response463397119C53_DataLabsStocksBoxSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"source": {
"type": [
"string",
"null"
],
"description": "source of additional information about the result"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price of booking a place for the specified dates of stay"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table element"
},
"graph": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Graph"
}
],
"description": "contains data provided in the graph of the element"
}
}
}
]
},
"Response463397119C53_Graph": {
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GraphElement"
}
]
},
"description": "contains arrays of elements available in the list"
},
"previous_items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GraphElement"
}
]
},
"description": "previous close data
contains stock price data based on the preceding time period"
}
}
},
"Response463397119C53_GraphElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date when the video was published or indexed
example: Apr 26, 2024"
},
"value": {
"type": [
"number",
"null"
],
"description": "the value of the rating"
}
}
},
"Response463397119C53_DataLabsCommercialUnitsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CommercialUnitsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_CommercialUnitsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price indicated in the element"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
}
}
},
"Response463397119C53_DataLabsLocalServicesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"items": {
"type": [
"object",
"null"
],
"description": "historical SERPs and related data found in the database"
}
}
}
]
},
"Response463397119C53_DataLabsGoogleHotelsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"hotel_identifier": {
"type": [
"string",
"null"
],
"description": "unique hotel identifier
unique hotel identifier assigned by Google;
example: \"CgoIjaeSlI6CnNpVEAE\""
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
}
}
}
]
},
"Response463397119C53_DataLabsMathSolverSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"result": {
"type": [
"string",
"null"
],
"description": "solution to the equation
solution to the mathematical equation specified in the keyword field when setting a task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MathSolverElement"
}
]
},
"description": "historical SERPs and related data found in the database"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_MathSolverElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"expanded_element": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MathSolverExpandedElement"
}
]
},
"description": "expanded element"
}
}
},
"Response463397119C53_MathSolverExpandedElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the carousel item"
},
"solution": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "solution of the element
displays steps to solve the mathematical equation as specified in the element"
}
}
},
"Response463397119C53_DataLabsMentionCarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MentionCarouselElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
],
"deprecated": true
},
"Response463397119C53_MentionCarouselElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price of the app element"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element’s rating \nthe popularity rate based on reviews and displayed in SERP"
},
"mentioned_in": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "additional elements in the mention_carousel item"
}
}
},
"Response463397119C53_DataLabsPodcastsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PodcastsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
],
"deprecated": true
},
"Response463397119C53_PodcastsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of element"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nexample:\n2019-11-15 12:57:46 +00:00"
},
"time_to_play": {
"type": [
"string",
"null"
],
"description": "the total time it will take to play an episode"
}
}
},
"Response463397119C53_DataLabsVisualStoriesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
],
"deprecated": true
},
"Response463397119C53_AmazonLabelElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
}
}
},
"Response463397119C53_DataLabsFoundOnWebSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"related_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "search queries related to the elment"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FoundOnWebElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
],
"deprecated": true
},
"Response463397119C53_FoundOnWebElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the element"
},
"image": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
],
"description": "image of the element"
}
}
},
"Response463397119C53_DataLabsExploreBrandsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ExploreBrandsElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
],
"deprecated": true
},
"Response463397119C53_ExploreBrandsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
}
},
"Response463397119C53_DataLabsCoursesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of course categories\ncontains a list of categories relevant to courses"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CoursesElement"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
}
],
"deprecated": true
},
"Response463397119C53_CoursesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"source": {
"type": [
"string",
"null"
],
"description": "source of the element\nindicates the source of information included in the top_stories_element"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"date": {
"type": [
"string",
"null"
],
"description": "the date when the page source of the element was published"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element’s rating \nthe popularity rate based on reviews and displayed in SERP"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveRequestInfo": {
"type": "object",
"properties": {
"category_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "product and service categories
required field
The maximum number of categories you can specify: 5
you can download the full list of possible categories"
},
"first_date": {
"type": "string",
"description": "first date of comparison period
required field
first date for which domain metrics will be provided;
date format: \"yyyy-mm-dd\";
example: \"2021-06-01\";
the list available dates is available through the available history endpoint;
Note: first_date cannot be greater than today's date;
Also note: the dates specified in first_date and second_date cannot point to the same month of the same year;
you can specify the dates in any order: first_date can be greater than second_date and vice versa;
minimum date: \"2020-10-01\""
},
"second_date": {
"type": "string",
"description": "second date of comparison period
required field
second date for which domain metrics will be provided;
date format: \"yyyy-mm-dd\";
example: \"2021-10-01\";
the list available dates is available through the available history endpoint;
Note: second_date cannot be greater than today's date;
Also note: the dates specified in first_date and second_date cannot point to the same month of the same year;
you can specify the dates in any order: second_date can be greater than first_date and vice versa;
minimum date: \"2020-10-01\""
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code;
you can receive the list of available locations with their location_name by making a separate request tohttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code;
you can receive the list of available locations with their location_code by making a separate request tohttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code;
you can receive the list of available languages with their language_name by making a separate request tohttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code;
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
example:en"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the response;item_types array contains item types that are different from the organic object, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"];
default value: [\"organic\", \"paid\"]"
},
"top_categories_count": {
"type": [
"integer",
"null"
],
"description": "number of additional domain categories
optional field
by using this parameter, you can receive domains relevant to additional categories that are not specified in category_codes above;
to learn more about the parameter, please refer to this help center article;
by default, top_categories_count is equal to the number of categories specified in the category_codes array;
Note: top_categories_count cannot be less than the number of categories in the category_codes array;
maximum value: 5",
"format": "int64"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "return subdomains in the API response
optional field
if false, the API response will contain main_domain only;
if true, the API will return main_domain plus its subdomains (if available);
default value: true"
},
"etv_min": {
"type": [
"integer",
"null"
],
"description": "minimum current organic ETV of the domain
optional field
if specified, the API will return only domains with organic_etv greater than the specified value"
},
"etv_max": {
"type": [
"integer",
"null"
],
"description": "maximum current organic ETV of the domain
optional field
if specified, the API will return only domains with organic_etv lesser than the specified value"
},
"correlate": {
"type": [
"boolean",
"null"
],
"description": "correlate data with previously obtained datasets
optional field
default value: true;
if you use this parameter, our system will correlate data you obtain now with previously obtained datasets;
this parameter is intended to mitigate any inconsistencies that may result from changes to our database;
Note: we do not recommend setting correlate to false"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of domains in the results array
optional field
default value: 100;
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0;
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum);
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like;
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters;
example:[\"metrics_history.202110.organic.pos_1\", \">\", 15];
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results;
default rule: [\"organic_etv,desc\"];
possible sorting types:asc - results will be sorted in ascending orderdesc - results will be sorted in descending order;
you should use a comma to set up a sorting type;
example:[\"organic_count,desc\"];
note that you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"organic_etv,desc\",\"organic_count,asc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255;
you can use this parameter to identify the task and match it with the result;
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"category_codes": [
"13418",
"11494"
],
"first_date": "2021-06-01",
"second_date": "2021-10-01",
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "categories in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveItem"
}
]
},
"description": "contains historical ranking and traffic data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleDomainMetricsByCategoriesLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"top_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
},
"description": "categories for which domains are collected"
},
"organic_etv": {
"type": [
"number",
"null"
],
"description": "current organic ETV of the domain"
},
"organic_count": {
"type": [
"integer",
"null"
],
"description": "current total count of organic SERPs that contain the domain",
"format": "int64"
},
"organic_is_lost": {
"type": [
"integer",
"null"
],
"description": "current number of lost ranked elements
indicates how many ranked elements of the domain were previously presented in SERPs, but weren’t found during the last check"
},
"organic_is_new": {
"type": [
"integer",
"null"
],
"description": "current number of new ranked elements
indicates how many new ranked elements were found for the domain"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain found for the specified category"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "primary domain"
},
"metrics_history": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
}
]
}
},
"description": "historical ranking and traffic data of the domain"
},
"metrics_difference": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "metrics difference between first_date and second_date
calculated by subtracting domain metrics as of the greater date from domain metrics as of the smaller date"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain
required field
the domain name of the target website
the domain should be specified without https:// and www."
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
optional field
if you use this field, you don't need to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:en"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to_true, all highly similar keywords will be excluded from the ranking and traffic calculations, the results will be based on data for main keywords from groups of synonyms
default value: falsen"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned results for domain
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned items
optional field
default value: 0
if you specify the 10 value, the first ten items in the results array will be omitted and the data will be provided for the successive items"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"language_name": "English",
"location_code": 2840
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveItem"
}
]
},
"description": "contains ranking and traffic data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleDomainRankOverviewLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "ranking data relevant to the specified domain"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveRequestInfo": {
"type": "object",
"properties": {
"targets": {
"type": "array",
"items": {
"type": "string"
},
"description": "target domains and subdomains
required field
you can specify domains and subdomains in this field;
domains and subdomains should be specified without https:// and www.;
you can set up to 1000 domains or subdomains"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
if you use this field, you don't have to specify location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
if you use this field, you don't have to specify location_name
you can receive the list of available locations with their location_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
if you use this field, you don’t need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
if you use this field, you don’t need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:en"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the data will be provided for the previous 12 months
minimal possible value: 2020-10-01
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2021-04-01\""
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to_true only core keywords will be returned, all highly similar keywords will be excluded;
default value: falsen"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the response;
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array;
possible values:[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value:[\"organic\", \"paid\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"dataforseo.com",
"cnn.com",
"forbes.com"
],
"location_code": 2840,
"language_code": "en",
"date_from": "2021-01-01",
"date_to": "2021-03-29",
"item_types": [
"organic",
"paid"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem"
}
]
},
"description": "array of items with relevant traffic estimation data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HistoricalMetricsBundleInfo"
}
],
"description": "traffic data relevant to the specified domain"
}
}
},
"Response463397119C53_HistoricalMetricsBundleInfo": {
"type": "object",
"properties": {
"organic": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HistoricalMetricsInfo"
}
]
},
"description": "traffic data from organic search"
},
"paid": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HistoricalMetricsInfo"
}
]
},
"description": "traffic data from paid search"
},
"local_pack": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HistoricalMetricsInfo"
}
]
},
"description": "traffic data from the local pack results in SERP"
},
"featured_snippet": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HistoricalMetricsInfo"
}
]
},
"description": "traffic data from the featured snippet results in Google SERP"
}
}
},
"Response463397119C53_HistoricalMetricsInfo": {
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "year for which the data is provided"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month for which the data is provided"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for
learn more about how the metric is calculated in this help center article"
},
"count": {
"type": [
"integer",
"null"
],
"description": "total count of organic SERPs that contain the domain",
"format": "int64"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 700
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase format, data will be provided in a separate array
you will not be charged for the keywords omitted in the resultskeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keywords": [
"iphone"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveItem"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleHistoricalKeywordDataLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"history": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_History"
}
]
},
"description": "array of objects with historical data for the keyword"
}
}
},
"Response463397119C53_History": {
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "year"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month"
},
"keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfo"
}
],
"description": "historical data for the keyword"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain
required field
the domain name of the target website
the domain should be specified without https:// and www."
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the data will be provided for the previous 6 months
minimal possible value: 2020-10-01
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2021-04-01\""
},
"correlate": {
"type": [
"boolean",
"null"
],
"description": "correlate data with previously obtained datasets
optional field
default value: true
if you use this parameter, our system will correlate data you obtain now with previously obtained datasets
this parameter is intended to mitigate any inconsistencies that may result from changes to our database
we recommend always setting correlate to true"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to true, only data based on core keywords will be returned, data for all highly similar keywords will be excluded;
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response;
default value: false;
with this parameter enabled, you will be charged double the price for the request;
learn more about how clickstream-based metrics are calculated in this help center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"location_code": 2840,
"language_code": "en",
"date_from": "2021-01-01",
"date_to": "2021-03-29"
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveItem"
}
]
},
"description": "contains historical ranking and traffic data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleHistoricalRankOverviewLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"year": {
"type": [
"integer",
"null"
],
"description": "year for which the data is provided"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month for which the data is provided"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "ranking data relevant to the specified domain"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords\nrequired field\nThe maximum number of keywords you can specify: 700\nThe maximum number of characters for each keyword: 80\nThe maximum number of words for each keyword phrase: 10\nthe specified keywords will be converted to lowercase format, data will be provided in a separate array\nnote that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn’t contain such keywords and cannot return data on them\nyou will not be charged for the keywords omitted in the results\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location\nrequired field if you don’t specify location_code\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nUnited Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code\nrequired field if you don’t specify location_name\nNote: it is required to specify either location_name or location_code\nyou can receive the list of available locations with their location_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\n2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language\nrequired field if you don’t specify language_code\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_name by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nEnglish"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code\nrequired field if you don’t specify language_name\nNote: it is required to specify either language_name or language_code\nyou can receive the list of available locations with their language_code by making a separate request to the\nhttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages\nexample:\nen"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword\noptional field\nif set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response\ndefault value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result\noptional field\nif the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response\ndefault value: false\nwith this parameter enabled, you will be charged double the price for the request\nlearn more about how clickstream-based metrics are calculated in this help center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"phone",
"watch"
],
"language_name": "English",
"location_code": 2840,
"include_serp_info": true
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveItem"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSearchVolumeLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword\nkeyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates data for Google and partner sites\nif true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;\nif false, the results are returned for Google search sites only"
},
"keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfo"
}
],
"description": "keyword data for the returned keyword idea"
},
"keyword_info_normalized_with_bing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfoNormalizedWithInfo"
}
],
"description": "contains keyword search volume normalized with Bing search volume"
},
"keyword_info_normalized_with_clickstream": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfoNormalizedWithInfo"
}
],
"description": "contains keyword search volume normalized with clickstream data"
},
"clickstream_keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ClickstreamKeywordInfo"
}
],
"description": "clickstream data for the returned keyword\nto retrieve results for this field, the parameter include_clickstream_data must be set to true"
},
"keyword_properties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordProperties"
}
],
"description": "additional information about the keyword"
},
"serp_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpInfo"
}
],
"description": "SERP data\nthe value will be null if you didn’t set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database"
},
"avg_backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvgBacklinksInfo"
}
],
"description": "backlink data for the returned keyword\nthis object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 websites ranking organically for the keyword"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the API will return all SERPs collected for 365 days starting from the current datetime value;
minimal possible value: 365 days from the current datetime value;
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default;
date format: \"yyyy-mm-dd\";
example:\"2021-09-01\""
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "albert einstein",
"datetime_from": "2026-09-22 05:48:19",
"datetime_to": "2026-10-02 05:48:19",
"location_code": 2840,
"language_code": "en",
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveResultInfo"
}
]
},
"description": "array of results
the array includes objects with SERPs for each month within the specified time frame"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type in a POST array"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "the total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveItem"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
},
"Response463397119C53_DataforseoLabsGoogleHistoricalSerpsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type in a POST array"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character ‘+’ will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:
answer_box, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
"description": "historical SERPs and related data found in the database"
}
}
},
"Response463397119C53_SpellInfo": {
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword obtained as a result of search engine autocorrection\n the results will be provided for the corrected keyword"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of autocorrection\n possible values:\n did_you_mean, showing_results_for, no_results_found_for, including_results_for\n note: Yahoo and Yandex support only the following autocorrection type:\n including_results_for"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleKeywordIdeasLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
UTF-8 encoding
The maximum number of keywords you can specify: 200.
The keywords will be converted to lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language"
},
"closely_variants": {
"type": [
"boolean",
"null"
],
"description": "search mode
optional field
if set to_true the results will be based on the phrase-match search algorithm
if set to false the results will be based on the broad-match search algorithm
default value: falsen"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to_true only core keywords will be returned, all highly similar keywords will be excluded;
default value: falsen"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
default value: 700
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like,as well as ilike, not_ilike to match any string of zero or more characters
note that you can not filter the results by relevance
example:[\"keyword_info.search_volume\",\">\",0][[\"keyword_info.search_volume\",\"in\",[0,1000]],
\"and\",
[\"keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_info.search_volume\",\">\",100],
\"and\",
[[\"keyword_info.cpc\",\"<\",0.5],
\"or\",
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter[\"relevance,desc\"]
relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint.
you should use a comma to separate several sorting rules
example:[\"relevance,desc\",\"keyword_info.search_volume,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"phone",
"watch"
],
"location_code": 2840,
"language_code": "en",
"include_serp_info": true,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordIdeasLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordIdeasLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordIdeasLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordIdeasLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordIdeasLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"seed_keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array
keywords are returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results relevant to your request in our database ",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "current offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
you can use the string provided in this field to get the subsequent results of the initial task;
note: offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
]
},
"description": "contains keyword ideas and related data"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleKeywordOverviewLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 700
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase format, data will be provided in a separate array
you will not be charged for the keywords omitted in the resultskeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"include_clickstream_data": true,
"include_serp_info": true,
"keywords": [
"iphone"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveItem"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleKeywordOverviewLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates data for Google and partner sites
if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;
if false, the results are returned for Google search sites only"
},
"keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfo"
}
],
"description": "keyword data for the returned keyword"
},
"keyword_info_normalized_with_bing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfoNormalizedWithInfo"
}
],
"description": "contains keyword search volume normalized with Bing search volume"
},
"keyword_info_normalized_with_clickstream": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordInfoNormalizedWithInfo"
}
],
"description": "contains keyword search volume normalized with clickstream data
"
},
"clickstream_keyword_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ClickstreamKeywordInfo"
}
],
"description": "clickstream data for the returned keyword
to retrieve results for this field, the parameter include_clickstream_data must be set to true"
},
"keyword_properties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordProperties"
}
],
"description": "additional information about the keyword"
},
"serp_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpInfo"
}
],
"description": "SERP data
the value will be null if you didn't set the field include_serp_info to true in the POST array or if there is no SERP data for this keyword in our database"
},
"avg_backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvgBacklinksInfo"
}
],
"description": "backlink data for the returned keyword
this object provides the average number of backlinks, referring pages and domains, as well as the average rank values among the top-10 websites ranking organically for the keyword"
},
"search_intent_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchIntentInfo"
}
],
"description": "search intent info for the returned keyword
learn about search intent in this help center article"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleKeywordSuggestionsLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
UTF-8 encoding
the keywords will be converted to lowercase format;keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
optional field
if you use this field, you don't need to specify location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations with their location_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language"
},
"include_seed_keyword": {
"type": [
"boolean",
"null"
],
"description": "include data for the seed keyword
optional field
if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response
default value: false"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
if set to true, the returned keywords will include the exact keyword phrase you specified, with potentially other words before or after that phrase
default value: false"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to true only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:[\"keyword_info.search_volume\",\">\",0][[\"keyword_info.search_volume\",\"in\",[0,1000]],
\"and\",
[\"keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_info.search_volume\",\">\",100],
\"and\",
[[\"keyword_info.cpc\",\"<\",0.5],
\"or\",
[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
a comma is used as a separator
example:[\"keyword_info.competition,desc\"]
default rule:[\"keyword_info.search_volume,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword_info.search_volume,desc\",\"keyword_info.cpc,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "phone",
"location_code": 2840,
"language_code": "en",
"include_serp_info": true,
"include_seed_keyword": true,
"limit": 1
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordSuggestionsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordSuggestionsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordSuggestionsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordSuggestionsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordSuggestionsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"seed_keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"seed_keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the seed keyword
fields in this object are identical to those of the items array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "current offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
you can use the string provided in this field to get the subsequent results of the initial task;
note: offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleKeywordsForAppLiveRequestInfo": {
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "id of the apps
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:United States"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the US location only;
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only;
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages;
Note: this endpoint currently supports the English language only
example:en"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in
example:[\"keyword_data.keyword_info.search_volume\",\">\",500][[\"keyword_data.keyword_info.search_volume\",\"<>\",500],\"and\",[\"ranked_serp_element.serp_item.rank_group\",\">=\",\"10\"]]
optional field
you can use the same values as in the filters array to sort the results;
possible sorting types:asc - results will be sorted in the ascending order;desc - results will be sorted in the descending order;
you should use a comma to specify a sorting type;
example:[\"ranked_serp_element.serp_item.rank_group,asc\"]
Note: you can set no more than three sorting rules in a single request;
you should use a comma to separate several sorting rules;
example:[\"ranked_serp_element.serp_item.rank_group,desc\",\"keyword_data.keyword_info.search_volume,asc\"]
default rule:[\"keyword_data.keyword_info.search_volume,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"app_id": "org.telegram.messenger",
"language_name": "English",
"location_code": 2840,
"limit": 10
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"app_id": {
"type": [
"string",
"null"
],
"description": "id of the app in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveItem"
}
]
},
"description": "contains data related to the ranking keywords for the app specified in the app_id field"
}
}
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForAppLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"ranked_serp_element": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlayRankedSerpElementInfo"
}
],
"description": "contains data on the domain's SERP element found for the returned keyword"
}
}
},
"Response463397119C53_GooglePlayRankedSerpElementInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"serp_item": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GooglePlaySearchOrganic"
}
],
"description": "contains data on the SERP element
the list of supported SERP elements can be found below"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "number of search results for the returned keyword"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"previous_updated_time": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date and time when SERP data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-10-15 12:57:46 +00:00;
in this case, will equal null"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleKeywordsForCategoriesLiveRequestInfo": {
"type": "object",
"properties": {
"category_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "product and service categories
required field
The maximum number of categories you can specify: 20
you can download the full list of possible categories"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"category_intersection": {
"type": [
"boolean",
"null"
],
"description": "category intersections
optional field
if set to true, you will get keywords featured in all specified categories;
if set to false, you will keywords that are specified in any of the specified categories;
default value: true"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
if set to true only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of keywords in the results array
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like,as well as ilike, not_ilike to match any string of zero or more characters
example:[\"keyword_info.search_volume\",\">\",0][[\"keyword_info.search_volume\",\"in\",[0,1000]],
\"and\",
[\"keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_info.search_volume\",\">\",100],
\"and\",
[[\"keyword_info.cpc\",\"<\",0.5],
\"or\",
[\"keyword_info.high_top_of_page_bid\",\"<=\",0.5]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"keyword_info.competition,desc\"]
default rule:[\"keyword_info.search_volume,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword_info.search_volume,desc\",\"keyword_info.competition,asc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"category_codes": [
"12191",
"12193"
],
"language_name": "English",
"location_code": 2840,
"include_serp_info": true,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForCategoriesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForCategoriesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForCategoriesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForCategoriesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForCategoriesLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"seed_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
},
"description": "categories in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "the total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "current offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
you can use the string provided in this field to get the subsequent results of the initial task;
note: offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
]
},
"description": "contains keyword ideas and related data"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleKeywordsForSiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain name or page url
required field
the domain name of the target website, subdomain or URL of the target webpage;
the domain name must be specified without https:// or www.;
the subdomain must be specified without https://;
the webpage URL must be specified with https:// or www.
Note: if you specify the webpage URL without https:// or www., the result will be returned for the entire domain rather than the specific page"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en
Note: if omitted, results default to the language with the most keyword records in the specified location;
refer to the available_languages.keywords field of the Locations and Languages endpoint to determine the default language"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to_true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
note that you can not filter the results by relevance
example:[\"keyword_info.search_volume\",\">\",0]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter[\"relevance,desc\"]
relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint.note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"relevance,desc\",\"keyword_info.search_volume,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "apple.com",
"language_code": "en",
"location_code": 2840,
"include_serp_info": true,
"include_subdomains": true,
"filters": [
"serp_info.se_results_count",
">",
0
],
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForSiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForSiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForSiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleKeywordsForSiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleKeywordsForSiteLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "current offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
you can use the string provided in this field to get the subsequent results of the initial task;
note: offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
]
},
"description": "contains keyword ideas and related data"
}
}
},
"Provider463397119C53_DataforseoLabsGooglePageIntersectionLiveRequestInfo": {
"type": "object",
"properties": {
"pages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target URLs of pagesrequired fieldyou can set up to 20 pages in this objectthe pages should be specified with absolute URLs (including http:// or https://)example:\"pages\": {\"1\":\"https://www.apple.com/mac/*\",\"2\":\"https://dataforseo.com/*\",\"3\":\"https://support.microsoft.com/\"}if you specify a single page here, we will return results only for this page;you can also use a wildcard ('') character to specify the search patternexample:\"example.com\"search for the exact URL\"example.com/eng/\"search for the example.com page and all its related URLs which start with '/eng/', such as \"example.com/eng/index.html\" and \"example.com/eng/help/\", etc.note: a wilcard should be placed after the slash ('/') character in the end of the URL, it is not possible to place it after the domain in the following way:https://dataforseo.comuse https://dataforseo.com/ insteadNote: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million"
},
"exclude_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "URLs of pages you want to excludeoptional fieldyou can set up to 10 pages in this arrayif you use this array, results will contain the keywords for which URLs from the pages object rank, but URLs from exclude_pages array do not;note that if you specify this field, the results will be based on the keywords any URL from pages ranks for regardless of intersections between them. However, you can set intersection_mode to intersect and results will contain the keywords all URLs from pages rank for in the same SERP and URLs from exclude_pages do not. use a wildcard ('*') character to specify the search patternexample:\"exclude_pages\":[\"https://www.apple.com/iphone/*\",\"https://dataforseo.com/apis/*\",\"https://www.microsoft.com/en-us/industry/services/\"]"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the locationrequired field if you don't specify location_codeNote: it is required to specify either location_name or location_codeyou can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languagesexample:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location coderequired field if you don't specify location_nameNote: it is required to specify either location_name or location_codeyou can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languagesexample:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the languagerequired field if you don't specify language_codeNote: it is required to specify either language_name or language_codeyou can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languagesexample:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language coderequired field if you don't specify language_nameNote: it is required to specify either language_name or language_codeyou can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languagesexample:en"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "search results typeindicates type of search results included in the responseoptional fieldpossible values: [\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]default value: [\"organic\", \"paid\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywordsoptional fielddefault value: 100maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the items array of returned keywordsoptional fielddefault value: 0if you specify 10 here, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains will be included in the searchoptional fieldif set to false, the subdomains will be ignoreddefault value: true"
},
"intersection_mode": {
"type": [
"string",
"null"
],
"description": "indicates whether to intersect keywordsoptional fielduse this field to intersect or merge results for the specified URLspossible values: union, intersectunion - results are based on all keywords any URL from pages rank for;intersect - results are based on the keywords all URLs from pages rank for in the same SERP:by default, results are based on the intersect mode if you specify only pages array. If you specify exclude_pages as well, results are based on the union mode"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keywordoptional fieldif set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the responsedefault value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the resultoptional fieldif the parameter is set to true, you will receive clickstream_keyword_info, clickstream_etv, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the responsedefault value: falsewith this parameter enabled, you will be charged double the price for the requestlearn more about how clickstream-based metrics are calculated in this help center article"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywordsoptional fieldif set to true only core keywords will be returned, all highly similar keywords will be excluded; default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parametersoptional fieldyou can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, ilike, not_ilike, like, not_like, match, not_matchyou can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more charactersnote that if you want to filter by any field in the intersection_result array you need to specify the number of corresponding pagefor instance, if you want to filter results by the ranking of the first specified URL, you should set the following filter:[intersection_result.1.rank_absolute,\"=\",1]if you want to filter results and receive only organic listings for the third specified URL, you should set the following filter:[intersection_result.3.type,\"=\",\"organic\"] , etc.example:[\"keyword_data.keyword_info.search_volume\",\"in\",[100,1000]][[\"intersection_result.1.etv\",\">\",0],\"and\",[\"intersection_result.1.description\",\"like\",\"%goat%\"]][[\"keyword_data.keyword_info.search_volume\",\">\",100],\"and\",[[\"intersection_result.2.description\",\"like\",\"%goat%\"],\"or\",[\"intersection_result.2.type\",\"=\",\"organic\"]]]for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rulesoptional fieldyou can use the same values as in the filters array to sort the resultspossible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending orderyou should use a comma to set up a sorting parameterexample:[\"keyword_data.keyword_info.competition,desc\"]default rule:[\"keyword_data.keyword_info.search_volume,desc\"]note that you can set no more than three sorting rules in a single requestyou should use a comma to separate several sorting rulesexample:[\"intersection_result.1.rank_group,asc\",\"intersection_result.2.rank_absolute,asc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"pages": {
"1": "https://forbes.com",
"2": "https://cnn.com/*"
},
"language_name": "English",
"location_code": 2840,
"include_serp_info": true,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGooglePageIntersectionLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGooglePageIntersectionLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGooglePageIntersectionLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGooglePageIntersectionLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGooglePageIntersectionLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"pages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "URLs you specified a POST array"
},
"exclude_pages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "URLs you specified in a POST array that will be excluded from the results"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGooglePageIntersectionLiveItem"
}
]
},
"description": "contains keywords, relevant SERP elements and related data"
}
}
},
"Response463397119C53_DataforseoLabsGooglePageIntersectionLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"intersection_result": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
]
},
"description": "contains data on the SERP elements found for the returned keyworddata will be provided in separate arrays for each URL you specified in the pages object when setting a task;depending on the number of specified URLs, it can contain from 1 to 20 arrays named respectively"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleRankedKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain name or page url
required field
the domain name of the target website, subdomain or URL of the target webpage;
the domain name must be specified without https:// or www.;
the subdomain must be specified without https://;
the webpage URL must be specified with https:// or www.
Note: if you specify the webpage URL without https:// or www., the result will be returned for the entire domain rather than the specific page"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
optional field
if you use this field, you don't need to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:en"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to true only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the responseitem_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\", \"ai_overview_reference\"]
default value: [\"organic\", \"paid\"]"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, clickstream_etv, clickstream_gender_distribution, clickstream_age_distribution, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"load_rank_absolute": {
"type": [
"boolean",
"null"
],
"description": "return rankings distribution by rank_absolute
optional field
default value: false
if set to true, we will return the field metrics_absolute containing rankings distribution by the rank_absolute parameter that indicates the result’s position among all SERP elements"
},
"historical_serp_mode": {
"type": [
"string",
"null"
],
"description": "data collection mode
optional field
you can use this field to filter the results;
possible types of filtering:live — return keywords for which the specified target currently has ranking results in SERP;lost — return keywords for which the specified target had previously had ranking results in SERP, but didn't have them during the last check;all — return both types of keywords.
default value: live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:[\"ranked_serp_element.serp_item.rank_group\",\"<=\",10][[\"ranked_serp_element.serp_item.rank_group\",\"<=\",10],
\"and\",
[\"ranked_serp_element.serp_item.type\",\"<>\",\"paid\"]][[\"keyword_data.keyword_info.search_volume\",\"<>\",0],
\"and\",
[[\"ranked_serp_element.serp_item.type\",\"<>\",\"paid\"],\"or\",[\"ranked_serp_element.serp_item.is_malicious\",\"=\",false]]]target field or filter by the ranked_serp_element.serp_item.relative_url parameter
example:[\"ranked_serp_element.serp_item.relative_url\", \"=\", \"/apis/rank-tracker-api\"]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"keyword_data.keyword_info.competition,desc\"]
default rule:[\"ranked_serp_element.serp_item.rank_group,asc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"language_name": "English",
"location_name": "United States",
"load_rank_absolute": true,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain or webpage in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "ranking data relevant to the specified domain or webpage
ranking data is provided by the rank_group parameters that show the result’s rank considering only equivalent SERP elements"
},
"metrics_absolute": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "ranking data relevant to the specified domain or webpage
ranking data is provided by the rank_absolute parameters that indicate the result’s position among all SERP elements"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveItem"
}
]
},
"description": "contains ranked keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleRankedKeywordsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the returned keyword"
},
"ranked_serp_element": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RankedSerpElement"
}
],
"description": "contains data on the domain's SERP element found for the returned keyword"
}
}
},
"Response463397119C53_RankedSerpElement": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"serp_item": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseDataforseoLabsApiElementItem"
}
],
"description": "contains data on the SERP element
the list of supported SERP elements can be found below"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"serp_item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP
possible item types:
answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, google_posts, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, recipes, top_sights, scholarly_articles, popular_products, podcasts, questions_and_answers, find_results_on, stocks_box, visual_stories, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, found_on_web, short_videos, refine_products, explore_brands, perspectives, discussions_and_forums, compare_sites, courses, ai_overview;
note that the actual results will be returned only for organic, paid, featured_snippet, and local_pack elements"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "number of search results for the returned keyword",
"format": "int64"
},
"keyword_difficulty": {
"type": [
"integer",
"null"
],
"description": "difficulty of ranking in the first top-10 organic results for a keyword
indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100;
calculated by analysing, among other parameters, link profiles of the first 10 pages in SERP;
learn more about the metric in this help center guide"
},
"is_lost": {
"type": [
"boolean",
"null"
],
"description": "lost ranked elements
indicates how many ranked elements of this target were previously presented in SERPs, but weren't found during the last check"
},
"last_updated_time": {
"type": [
"string",
"null"
],
"description": "date and time when keyword data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"previous_updated_time": {
"type": [
"string",
"null"
],
"description": "previous to the most recent date and time when SERP data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-10-15 12:57:46 +00:00"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
UTF-8 encoding
the keywords will be converted to lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "keyword search depth
optional field
default value: 1
you can specify a level from 0 to 4
estimated number of keywords for each level (maximum):
0 - the keyword set in the keyword field
1 – 8 keywords
2 – 72 keywords
3 – 584 keywords
4 – 4680 keywords"
},
"include_seed_keyword": {
"type": [
"boolean",
"null"
],
"description": "include data for the seed keyword
optional field
if set to true, data for the seed keyword specified in the keyword field will be provided in the seed_keyword_data array of the response
default value: false"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": ""
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": ""
},
"replace_with_core_keyword": {
"type": [
"boolean",
"null"
],
"description": "return data for core keyword
optional field
if true, serp_info and related_keywords will be returned for the main keyword in the group that the specified keyword belongs to;
if false, serp_info and related_keywords will be returned for the specified keyword (if available);
refer to this help center article for more details;
default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like,not_like
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:[\"keyword_data.keyword_info.search_volume\",\">\",0][[\"keyword_info.search_volume\",\"in\",[0,1000]],
\"and\",
[\"keyword_data.keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_data.keyword_info.search_volume\",\">\",100],
\"and\",
[[\"keyword_data.keyword_info.cpc\",\"<\",0.5],
\"or\",
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"keyword_data.keyword_info.competition,desc\"]
default rule:[\"keyword_data.keyword_info.search_volume,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword_data.keyword_info.search_volume,desc\",\"keyword_data.keyword_info.cpc,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "phone",
"language_name": "English",
"location_code": 2840,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"seed_keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"seed_keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"description": "keyword data for the seed keyword
fields in the array are identical to that of keyword_data"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveItem"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleRelatedKeywordsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"keyword_data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
],
"properties": {
"avg_backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvgBacklinksInfo"
}
]
},
"search_intent_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchIntentInfo"
}
]
}
},
"description": "keyword data for the returned keyword"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "keyword search depth"
},
"related_keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "list of related keywords
represents the list of search queries which are related to the keyword returned in the array above"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleRelevantPagesLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain
required field
the domain name of the target website
the domain should be specified without https:// and www."
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
optional field
if you use this field, you don't need to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:en"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the responseitem_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value: [\"organic\", \"paid\"]"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"historical_serp_mode": {
"type": [
"string",
"null"
],
"description": "data collection mode
optional field
you can use this field to filter the results;
possible types of filtering:live — return metrics for SERPs in which the specified target currently has ranking results;lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn't have them during the last check;all — return metrics for both types of SERPs.
default value: live"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to true, only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in[\"metrics.paid.count\",\">\",0][[\"metrics.organic.count\",\">\",50],\"and\",[\"metrics.organic.pos_1\",\"<>\",0]][[\"\"metrics.organic.count\",\">\",50\"],
\"and\",
[[\"metrics.organic.pos_1\",\"<>\",0],\"or\",[\"metrics.organic.pos_2_3\",\"<>\",0]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to specify a sorting type
example:[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"][\"metrics.organic.count,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "amazon.com",
"language_name": "English",
"location_code": 2840,
"filters": [
[
"metrics.organic.pos_1",
"<>",
0
],
"or",
[
"metrics.organic.pos_2_3",
"<>",
0
]
],
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is null"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveItem"
}
]
},
"description": "relevant pages and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleRelevantPagesLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"page_address": {
"type": [
"string",
"null"
],
"description": "absolute URL of the relevant page"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "rankings and traffic metrics for the relevant page"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleSearchIntentLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
the keywords will be converted to lowercase formatkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"login page",
"audi a7",
"elon musk",
"milk store new york"
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleSearchIntentLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSearchIntentLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleSearchIntentLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSearchIntentLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleSearchIntentLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSearchIntentLiveItem"
}
]
},
"description": "array of items with relevant traffic estimation data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleSearchIntentLiveItem": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "target keyword in a POST array"
},
"keyword_intent": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordIntentInfo"
}
],
"description": "search intent data relevant for the specified keyword"
},
"secondary_keyword_intents": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordIntentInfo"
}
]
},
"description": "contains objects with other possible search intents for the specified keyword"
}
}
},
"Response463397119C53_KeywordIntentInfo": {
"type": "object",
"properties": {
"label": {
"type": [
"string",
"null"
],
"description": "search intent name
possible values: informational, navigational, commercial, transactional"
},
"probability": {
"type": [
"number",
"null"
],
"description": "search intent probability1 indicates the highest probability"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords array
required field
the results will be based on the keywords you specify in this array
UTF-8 encoding;
the keywords will be converted to lowercase format;
you can specify the maximum of 200 keywordskeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with location_name parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_name parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "unique language identifier
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "search results type
indicates type of search results included in the response
optional field[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value: [\"organic\", \"paid\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
example:[\"median_position\",\"in\",[1,10]][[\"median_position\",\"in\",[1,10]],\"and\",[\"domain\",\"not_like\",\"%wikipedia.org%\"]][[\"domain\",\"not_like\",\"%wikipedia.org%\"],
\"and\",
[[\"relevant_serp_items\",\">\",0],\"or\",[\"median_position\",\"in\",[1,10]]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
the comma is used as a separator
example:[\"avg_position,asc\"]
default rule:[\"rating,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"avg_position,asc\",\"etv,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"phone"
],
"language_name": "English",
"location_code": 2840,
"item_types": [
"organic"
],
"limit": 5
}
]
},
"Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"seed_keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords specified in the request
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "the total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveItem"
}
]
},
"description": "contains detected SERP competitors and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleSerpCompetitorsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain name of the detected SERP competitor"
},
"avg_position": {
"type": [
"number",
"null"
],
"description": "the average position of the domain for the specified keywords
the arithmetic mean of values in the keywords_positions array",
"format": "float"
},
"median_position": {
"type": [
"number",
"null"
],
"description": "the median position of the domain for the specified keywords
the median of the values in the keywords_positions array"
},
"rating": {
"type": [
"number",
"null"
],
"description": "the margin between the greatest possible and actual keyword positions
represents the relative visibility rate of the domain in SERP for the specified keywords
calculated as sum(100-keywords_positions)"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
represents the estimated monthly traffic that specified keywords are driving to the website
calculated as the sum of the products of the specified keywords' search volume values and CTR (click-through-rate) rates at certain positions in SERP
learn more about how the metric is calculated in this help center article"
},
"keywords_count": {
"type": [
"integer",
"null"
],
"description": "the number of specified keywords the domain has positions for in SERPs",
"format": "int64"
},
"visibility": {
"type": [
"number",
"null"
],
"description": "SERP visibility rate
represents the website visibility rate based on the SERP positions of the specified keywords
Keywords with positions in the range from 1 to 10 are assigned the visibility index from 1 to 0.1, respectively
Keywords with positions in the range from 11 to 20 have the fixed visibility index of 0.05
keywords with positions from 20 to 100 have the visibility index equal to 0"
},
"relevant_serp_items": {
"type": [
"integer",
"null"
],
"description": "the number of SERP elements relevant to the domain
represents the number of search results in SERP relevant to the domain for the specified keywords"
},
"keywords_positions": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
}
},
"description": "keyword positions
SERP positions the related domain holds in SERP for the specified keywords"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleSubdomainsLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain
required field
the domain name of the target website
the domain should be specified without https:// and www."
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location
optional field
if you use this field, you don't need to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of the language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:en"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "display results by item type
optional field
indicates the type of search results included in the responseitem_types array contains item types that are different from organic, the results will be ordered by the first item type in the array; you will not be able to sort and filter results by the types of search results not included in the response;[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value: [\"organic\", \"paid\"]"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_etv, clickstream_gender_distribution, and clickstream_age_distribution fields with clickstream data in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
you can use this field to filter the results;
possible types of filtering:live — return metrics for SERPs in which the specified target currently has ranking results;lost — return metrics for SERPs in which the specified target had previously had ranking results, but didn't have them during the last check;all — return metrics for both types of SERPs.
default value: live"
},
"ignore_synonyms": {
"type": [
"boolean",
"null"
],
"description": "ignore highly similar keywords
optional field
if set to true, only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in
example:[\"metrics.paid.count\",\">\",0][[\"metrics.paid.count\",\">\",0],\"and\",[\"metrics.paid.etv\",\">\",\"50\"]][[\"metrics.organic.count\",\">\",\"10\"],
\"and\",
[[\"metrics.organic.pos_1\",\"<>\",0],\"or\",[\"metrics.organic.pos_2_3\",\"<>\",0]]]
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to specify a sorting type
example:[\"metrics.paid.etv,asc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"metrics.organic.etv,desc\",\"metrics.paid.count,asc\"][\"metrics.organic.count,desc\"]
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"language_name": "English",
"location_code": 2840,
"filters": [
[
"metrics.organic.pos_1",
"<>",
0
],
"or",
[
"metrics.organic.pos_2_3",
"<>",
0
]
]
}
]
},
"Response463397119C53_DataforseoLabsGoogleSubdomainsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSubdomainsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleSubdomainsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSubdomainsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleSubdomainsLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"target": {
"type": [
"string",
"null"
],
"description": "domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleSubdomainsLiveItem"
}
]
},
"description": "contains subdomains and related data"
}
}
},
"Response463397119C53_DataforseoLabsGoogleSubdomainsLiveItem": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"subdomain": {
"type": [
"string",
"null"
],
"description": "returned subdomain"
},
"metrics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsMetricsInfo"
},
"description": "ranking data relevant to subdomain"
}
}
},
"Provider463397119C53_DataforseoLabsGoogleTopSearchesLiveRequestInfo": {
"type": "object",
"properties": {
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_name by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code
required field if you don't specify language_name
Note: it is required to specify either language_name or language_code
you can receive the list of available locations with their language_code by making a separate request to the https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example:en"
},
"include_serp_info": {
"type": [
"boolean",
"null"
],
"description": "include data from SERP for each keyword
optional field
if set to true, we will return a serp_info array containing SERP data (number of search results, relevant URL, and SERP features) for every keyword in the response
default value: false"
},
"include_clickstream_data": {
"type": [
"boolean",
"null"
],
"description": "include or exclude data from clickstream-based metrics in the result
optional field
if the parameter is set to true, you will receive clickstream_keyword_info, keyword_info_normalized_with_clickstream, and keyword_info_normalized_with_bing fields in the response
default value: false
with this parameter enabled, you will be charged double the price for the request
optional field
if set to true only core keywords will be returned, all highly similar keywords will be excluded;
default value: false"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like,not_like
you can use the % operator with like and not_like,as well as ilike and not_ilike to match any string of zero or more characters
example:[\"keyword_info.search_volume\",\">\",0][[\"keyword_info.search_volume\",\"in\",[0,1000]],
\"and\",
[\"keyword_info.competition_level\",\"=\",\"LOW\"]][[\"keyword_info.search_volume\",\">\",100],
\"and\",
[[\"keyword_info.cpc\",\"<\",0.5],
\"or\",
for more information about filters, please refer to Dataforseo Labs - Filters or this help center guide"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"keyword_info.competition,desc\"]
default rule:[\"keyword_info.search_volume,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword_info.search_volume,desc\",\"keyword_info.cpc,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
note: you can get more than 1000 results by using the offset_token provided in the response to each subsequent request
default value: 1000
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned keywords
optional field
default value: 0
if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 10,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters except limit will not be taken into account when processing a task.
learn more about this parameter on our Help Center"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"limit": 3
}
]
},
"Response463397119C53_DataforseoLabsGoogleTopSearchesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleTopSearchesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleTopSearchesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsGoogleTopSearchesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsGoogleTopSearchesLiveResultInfo": {
"type": "object",
"properties": {
"se_type": {
"type": [
"string",
"null"
],
"description": "search engine type"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "current offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "offset token for subsequent requests
you can use the string provided in this field to get the subsequent results of the initial task;
note: offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordDataInfo"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_DataforseoLabsStatusResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsStatusTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DataforseoLabsStatusTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsStatusResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DataforseoLabsStatusResultInfo": {
"type": "object",
"properties": {
"google": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsStatusInfo"
}
],
"description": "update information for the Google endpoints"
},
"bing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsStatusInfo"
}
],
"description": "update information for the Bing endpoints"
},
"amazon": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoLabsStatusInfo"
}
],
"description": "update information for the Amazon endpoints"
}
}
},
"Response463397119C53_DataforseoLabsStatusInfo": {
"type": "object",
"properties": {
"date_update": {
"type": [
"string",
"null"
],
"description": "update date of the Google endpoints
indicates the last date when the Google endpoints of DataForSEO Labs API were updated;
example:2022-05-16"
}
}
},
"Provider463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveRequestInfo": {
"type": "object",
"properties": {
"group": {
"type": "string",
"description": "id of the target technology group
required field if you don't specify technology, category or keyword
at least one field (group, category, keyword, technology) must be set
you can find the full list of technology group ids on this page
example:\"marketing\""
},
"category": {
"type": "string",
"description": "id of the target technology category
required field if you don't specify group, keyword or technology
at least one field (group, category, keyword, technology) must be set
you can find the full list of technology category ids on this page
example:\"crm\""
},
"technology": {
"type": "string",
"description": "target technology
required field if you don't specify group, keyword or category
at least one field (group, category, keyword, technology) must be set
you can find the full list of technologies on this page
example:\"Salesforce\""
},
"keyword": {
"type": "string",
"description": "target keyword in the domain's meta keywords
required field if you don't specify group, category or technology
at least one field (group, category, keyword, technology) must be set
UTF-8 encoding
example:\"seo\"learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"mode": {
"type": [
"string",
"null"
],
"description": "search mode
optional field
possible search mode types:as_is - search for results exactly matching the specified group ids, category ids, or technology namesentry - search for results matching a part of the specified group ids, category ids, or technology names
default value: as_is"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in, like,not_like
you can use the % operator with like and not_like to match any string of zero or more characters
you can use the following parameters to filter the results: domain_rank, last_visited, country_iso_code, language_code, content_language_code
Note: all filtering parameters are taken from the domain_technology_item of the domain_technologies endpoint;
example:[[\"country_iso_code\",\"=\",\"US\"],for more information about filters, please refer to Domain Analytics Technologies API - Filters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
\"and\",
[\"domain_rank\",\">\",800]]
optional field
you can use the following values to sort the results: groups_count, categories_count, technologies_count
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"groups_count,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"groups_count,desc\",\"technologies_count,desc\"]
default value:[\"groups_count,desc\",\"categories_count,desc\",\"technologies_count,desc\"]"
},
"internal_groups_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of returned technology groups
optional field
you can use this field to limit the number of items with identical \"group\" in the results
default value: 5
minimum value: 1
maximum value: 10000"
},
"internal_categories_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of returned technology categories within the same group
optional field
you can use this field to limit the number of items with identical \"category\" in the results
default value: 5
minimum value: 1
maximum value: 10000"
},
"internal_technologies_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of returned technologies within the same category
optional field
you can use this field to limit the number of items with identical \"technology\" in the results
default value: 10
minimum value: 1
maximum value: 10000"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of items with identical \"category\", \"group\", and \"technology\"
optional field
if you use this field, the values specified in internal_groups_list_limit, internal_categories_list_limit and internal_technologies_list_limit will be ignored;
you can use this field to limit the number of items with identical \"category\", \"group\", or \"technology\"
default value: 10
minimum value: 1
maximum value: 10000"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned technologies
optional field
default value: 100
maximum value: 10000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
maximum value: 9999
if you specify the 10 value, the first ten technologies in the results array will be omitted and the data will be provided for the successive technologies"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"mode": "entry",
"technology": "Nginx",
"keyword": "WordPress",
"filters": [
[
"country_iso_code",
"=",
"US"
],
"and",
[
"domain_rank",
">",
800
]
],
"order_by": [
"groups_count,desc"
],
"limit": 10
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveItem"
}
]
}
}
}
},
"Response463397119C53_DomainAnalyticsTechnologiesAggregationTechnologiesLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"group": {
"type": [
"string",
"null"
],
"description": "technology group id"
},
"category": {
"type": [
"string",
"null"
],
"description": "technology category id"
},
"technology": {
"type": [
"string",
"null"
],
"description": "technology name"
},
"groups_count": {
"type": [
"integer",
"null"
],
"description": "technology groups count
number of domains that match the parameters you specified and are using technologies from the indicated group",
"format": "int64"
},
"categories_count": {
"type": [
"integer",
"null"
],
"description": "technology categories count
number of domains that match the parameters you specified and are using technologies from the indicated category",
"format": "int64"
},
"technologies_count": {
"type": [
"integer",
"null"
],
"description": "technologies count
number of domains that match the parameters you specified and are using the indicated technology",
"format": "int64"
}
},
"description": "items array"
},
"Response463397119C53_DomainAnalyticsTechnologiesAvailableFiltersResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesAvailableFiltersTaskInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesAvailableFiltersTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesAvailableFiltersResultInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesAvailableFiltersResultInfo": {
"type": "object",
"properties": {
"domains_by_technology": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"aggregation_technologies": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"technologies_summary": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"domains_by_html_terms": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
}
},
"Provider463397119C53_DomainAnalyticsTechnologiesDomainTechnologiesLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "target domain
required field
domain name of the website to analyze
Note: results will be returned for the specified domain only"
}
},
"example": [
{
"target": "dataforseo.com"
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainTechnologiesLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainTechnologiesLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainTechnologiesLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainTechnologiesLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainTechnologiesLiveResultInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "specified domain name"
},
"title": {
"type": [
"string",
"null"
],
"description": "domain meta title"
},
"description": {
"type": [
"string",
"null"
],
"description": "domain meta description"
},
"meta_keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "domain meta keywords"
},
"domain_rank": {
"type": [
"integer",
"null"
],
"description": "backlink rank of the target domain
learn more about the metric and how it is calculated in this help center article"
},
"last_visited": {
"type": [
"string",
"null"
],
"description": "most recent date when our crawler visited the domain
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2022-10-10 12:57:46 +00:00"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "domain ISO code
ISO code of the country that the target domain is determined to belong to"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "domain language
code of the language that the target domain is determined to be associated with"
},
"content_language_code": {
"type": [
"string",
"null"
],
"description": "content language
code of the language that content on the target domain is written in"
},
"phone_numbers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "phone numbers of the target
contact phone numbers indicated on the target website"
},
"emails": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "emails of the target
emails indicated on the target website"
},
"social_graph_urls": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "social media links and handles
social media URLs detected in the social graphs of the target website"
},
"technologies": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TechnologiesInfo"
}
],
"description": "technologies used by target domain
contains objects with the names of technologies used on the website
see the full list of available technologies structured by groups and categories"
}
}
},
"Response463397119C53_TechnologiesInfo": {
"type": "object",
"properties": {
"add_ons": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"analytics": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"web_development": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"security": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"business_tools": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"sales": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"other": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"user_generated_content": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"booking": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"privacy": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"servers": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"location": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"content": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"media": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"marketing": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"communication": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
},
"utilities": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
}
}
}
},
"Provider463397119C53_DomainAnalyticsTechnologiesDomainsByHtmlTermsLiveRequestInfo": {
"type": "object",
"properties": {
"search_terms": {
"type": "array",
"items": {
"type": "string"
},
"description": "target search terms
required field
specify target HTML elements, tags, attributes, their content or all of the above
if you specify more than one search term, you will receive only the domains containing all of the specified terms in the HTML code of their homepage
maximum number of search terms you can specify: 10
example:[\"data-attrid\"]"
},
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target keywords in the domain's title, description or meta keywords
optional field
UTF-8 encoding
maximum number of keywords you can specify: 10
example:[\"seo\",\"software\"]keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"mode": {
"type": [
"string",
"null"
],
"description": "search mode
optional field
possible search mode types:strict_entry - search for results exactly matching the order, intervals and separators in the specified search termsentry - search for results ignoring the order, intervals and separators in the specified search terms
default value: entry"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"domain\",\"like\",\"%seo%\"][[\"country_iso_code\",\"=\",\"US\"],
\"and\",
[\"domain_rank\",\">\",100]][[\"domain_rank\",\">\",100],
\"and\",
[[\"country_iso_code\",\"=\",\"US\"],\"or\",[\"country_iso_code\",\"=\",\"CA\"]]]
optional field
available fields: domain_rank, domain, last_visited, country_iso_code, language_code, content_language_code
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"last_visited,desc\"]
default rule:[\"domain_rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"last_visited,desc\",\"domain_rank,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 10000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains;
Note: the maximum value is 9999, the sum of limit and offset must not exceed 10000;
use the offset_token if you would like to offset more results"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
}
},
"example": [
{
"search_terms": [
"data-attrid"
],
"order_by": [
"last_visited,desc"
],
"limit": 10,
"offset": 0
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByHtmlTermsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainsByHtmlTermsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByHtmlTermsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainsByHtmlTermsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByHtmlTermsLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "specified offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
by specifying the unique offset_token when setting a new task, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainsByLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "specified domain name"
},
"title": {
"type": [
"string",
"null"
],
"description": "domain meta title"
},
"description": {
"type": [
"string",
"null"
],
"description": "domain meta description"
},
"meta_keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "domain meta keywords"
},
"domain_rank": {
"type": [
"integer",
"null"
],
"description": "backlink rank of the target domain
learn more about the metric and how it is calculated in this help center article"
},
"last_visited": {
"type": [
"string",
"null"
],
"description": "most recent date when our crawler visited the domain
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2022-10-10 12:57:46 +00:00"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "domain ISO code
ISO code of the country that target domain is determined to belong to"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "domain language
code of the language that target domain is determined to be associated with"
},
"content_language_code": {
"type": [
"string",
"null"
],
"description": "content language
code of the language that content on the target domain is written with"
},
"phone_numbers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "phone numbers of the target
contact phone numbers indicated on the target website"
},
"emails": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "emails of the target
emails indicated on the target website"
},
"social_graph_urls": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "social media links and handles
social media URLs detected in the social graphs of the target website"
},
"technologies": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TechnologiesInfo"
}
],
"description": "technologies used by target domain
contains objects with the names of technologies used on the website;
to get a full list of technologies and their structure, refer to the technologies endpoint"
}
},
"description": "items array"
},
"Provider463397119C53_DomainAnalyticsTechnologiesDomainsByTechnologyLiveRequestInfo": {
"type": "object",
"properties": {
"technology_paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "target technology paths
required field if you don't specify groups, technologies, keywords or categories
at least one field (technology_paths, groups, technologies, keywords or categories) must be set;
each technology path should be specified as a separate object containing \"path\" and \"name\", where \"path\" is specified as \"$group_id.$category_id\" and \"name\" - as the name of the target technology;
each object with a technology path should be separated with a comma
you can find the full list of technology group ids, category ids and technology names on this page
note: you can specify up to 10 technology paths in this array
example:[{\"path\": \"content.cms\",\"name\": \"wordpress\"}, {\"path\": \"marketing.crm\",\"name\": \"salesforce\"}]"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "ids of the target technology groups
required field if you don't specify technologies, technology_paths, keywords or categories
you can find the full list of technology group ids on this page
note: you can specify up to 10 technology groups in this array
example:[\"sales\", \"marketing\"]"
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "ids of the target technology categories
required field if you don't specify groups, technology_paths, keywords or technologies
you can find the full list of technology category ids on this page
note: you can specify up to 10 technology categories in this array
example:[\"payment_processors\",\"crm\"]"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "target technologies
required field if you don't specify groups, technology_paths, keywords or categories
you can find the full list of technologies you can specify here on this page
note: you can specify up to 10 technologies in this array
example:[\"Google Pay\",\"Salesforce\"]"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords in the domain's title, description or meta keywords
required field if you don't specify groups, technology_paths, technologies or categories
optional field
you can specify the maximum of 10 keywords;
UTF-8 encoding;
example:[\"seo\",\"software\"]keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"mode": {
"type": [
"string",
"null"
],
"description": "search mode
optional field
possible search mode types:as_is - search for results exactly matching the specified group ids, category ids, or technology namesentry - search for results matching a part of the specified group ids, category ids, or technology names
default value: as_is"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"country_iso_code\",\"=\",\"US\"][[\"country_iso_code\",\"=\",\"US\"],
\"and\",
[\"domain_rank\",\">\",100]][[\"domain_rank\",\">\",100],
\"and\",
[[\"country_iso_code\",\"=\",\"US\"],\"or\",[\"country_iso_code\",\"=\",\"CA\"]]]
optional field
available fields: domain_rank, domain, last_visited, country_iso_code, language_code, content_language_code
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"last_visited,desc\"]
default rule:[\"domain_rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"last_visited,desc\",\"domain_rank,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 10000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive domains;
Note: the maximum value is 9999, the sum of limit and offset must not exceed 10000;
use the offset_token if you would like to offset more results"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
}
},
"example": [
{
"technologies": [
"Nginx"
],
"filters": [
[
"country_iso_code",
"=",
"US"
],
"and",
[
"domain_rank",
">",
800
]
],
"order_by": [
"last_visited,desc"
],
"limit": 10
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByTechnologyLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainsByTechnologyLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByTechnologyLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainsByTechnologyLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesDomainsByTechnologyLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "specified offset value"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
by specifying the unique offset_token when setting a new task, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesDomainsByLiveItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_DomainAnalyticsTechnologiesLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_DomainAnalyticsTechnologiesLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesLocationsResultInfo": {
"type": "object",
"properties": {
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
}
}
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologiesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologiesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologiesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologiesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologiesResultInfo": {
"type": "object",
"properties": {
"groups": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Groups"
}
]
},
"description": "array of technology groups"
}
}
},
"Response463397119C53_Groups": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "id of the technology group
example:marketing, sales"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the technology group"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TechnologyCategoryInfo"
}
]
},
"description": "technology categories in this group"
}
}
},
"Response463397119C53_TechnologyCategoryInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "id of the technology category
example:crm, cart_abandonment"
},
"path": {
"type": [
"string",
"null"
],
"description": "path to the technology category
example:user_generated_content.content_curation"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the technology category"
},
"technologies": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "list of technologies in this category
example:\"Salesforce\", \"CareCart\""
}
}
},
"Provider463397119C53_DomainAnalyticsTechnologiesTechnologiesSummaryLiveRequestInfo": {
"type": "object",
"properties": {
"technology_paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "target technology paths
required field if you don't specify groups, technologies and categories
each technology path should be specified as a separate object containing \"path\" and \"name\", where \"path\" is specified as \"$group_id.$category_id\" and \"name\" - as the name of the target technology;
each object with a technology path should be separated with a comma
you can find the full list of technology group ids, category ids and technology names on this page
note: you can specify up to 10 technology paths in this array
example:[{\"path\": \"content.cms\",\"name\": \"wordpress\"}, {\"path\": \"marketing.crm\",\"name\": \"salesforce\"}]"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "ids of the target technology groups
required field if you don't specify technologies, technology_paths, categories, or keywords
you can find the full list of technology group ids on this page
note: you can specify up to 10 technology groups in this array
example:[\"sales\", \"marketing\"]"
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "ids of the target technology categories
required field if you don't specify groups, technology_paths, technologies, or keywords
you can find the full list of technology category ids on this page
note: you can specify up to 10 technology categories in this array
example:[\"payment_processors\",\"crm\"]"
},
"technologies": {
"type": "array",
"items": {
"type": "string"
},
"description": "target technologies
required field if you don't specify groups, technology_paths, categories, or keywords
you can find the full list of technologies you can specify here on this page
note: you can specify up to 10 technologies in this array
example:[\"Google Pay\",\"Salesforce\"]"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords in the domain's title, description or meta keywords
required field if you don't specify groups, technology_paths, categories, or technologies
you can specify the maximum of 10 keywords;
UTF-8 encoding;
example:[\"seo\",\"software\"]keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"mode": {
"type": [
"string",
"null"
],
"description": "search mode
optional field
possible search mode types:as_is - search for results exactly matching the specified group ids, category ids, or technology namesentry - search for results matching a part of the specified group ids, category ids, or technology names
default value: as_is"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:<, <=, >, >=, =, <>, in, not_in, like,not_like
you can use the % operator with like and not_like to match any string of zero or more characters
you can use the following parameters to filter the results: domain_rank, last_visited, country_iso_code, language_code, content_language_code
example:[[\"country_iso_code\",\"=\",\"US\"],
\"and\",
[\"domain_rank\",\">\",800]]
optional field
you can use this field to limit the number of elements within the following arrays:countries, languages, content_languages, keywords
default value: 10
minimum value: 1
maximum value: 10000"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"mode": "entry",
"technologies": [
"Ngi"
],
"keywords": [
"WordPress"
],
"filters": [
[
"country_iso_code",
"=",
"US"
],
"and",
[
"domain_rank",
">",
800
]
]
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologiesSummaryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologiesSummaryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologiesSummaryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologiesSummaryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologiesSummaryLiveResultInfo": {
"type": "object",
"properties": {
"countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by country
contains country codes and number of websites per country"
},
"languages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by language
contains language codes and number of websites per language"
},
"content_languages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by content language
contains content language codes and number of websites per language"
},
"keywords": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by keywords
contains keywords found in the websites' titles, descriptions or meta keywords, and number of websites using each keyword"
}
}
},
"Provider463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveRequestInfo": {
"type": "object",
"properties": {
"technology": {
"type": "string",
"description": "target technology
required field
you can find the full list of technologies you can specify here on this page
example:\"Salesforce\""
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimum value: 2022-10-31
if you don't specify this field, the minimum value will be used by default
date format: \"yyyy-mm-dd\"
example:\"2023-06-01\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2023-01-15\""
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"technology": "jQuery",
"date_from": "2022-10-31",
"date_to": "2023-06-01"
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveResultInfo": {
"type": "object",
"properties": {
"technology": {
"type": [
"string",
"null"
],
"description": "target technology"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range"
},
"items_count": {
"type": [
"integer",
"null"
]
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveItem"
}
]
}
}
}
},
"Response463397119C53_DomainAnalyticsTechnologiesTechnologyStatsLiveItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date": {
"type": [
"string",
"null"
],
"description": "date for which the data is provided"
},
"domains_count": {
"type": [
"integer",
"null"
],
"description": "number of domains that use the specified technology",
"format": "int64"
},
"countries": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by country
contains country codes and number of websites per country"
},
"languages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by language
contains language codes and number of websites per language"
},
"domains_rank": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "distribution of websites by backlink rank
contains domain rank ranges and number of websites per range
learn more about rank and how it is calculated in this help center article"
}
},
"description": "items array"
},
"Response463397119C53_DomainAnalyticsWhoisAvailableFiltersResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsWhoisAvailableFiltersTaskInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_DomainAnalyticsWhoisAvailableFiltersTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsWhoisAvailableFiltersResultInfo"
}
]
}
}
}
}
]
},
"Response463397119C53_DomainAnalyticsWhoisAvailableFiltersResultInfo": {
"type": "object",
"properties": {
"overview": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
}
},
"Provider463397119C53_DomainAnalyticsWhoisOverviewLiveRequestInfo": {
"type": "object",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned items
optional field
default value: 0
if you specify the 10 value, the first ten items in the results array will be omitted and the data will be provided for the successive items;
Note: we recommend using this parameter only when retrieving up to 10,000 results for retrieving over 10,000 results, use the offset_token instead"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
the comma is used as a separator
example:[\"metrics.organic.pos_1,desc\"]
default rule:[\"metrics.organic.count,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"expiration_datetime,asc\",\"metrics.organic.etv,desc\",\"metrics.organic.pos_1,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"limit": 2,
"filters": [
[
"epp_status_codes",
"in",
[
"client_transfer_prohibited",
"client_update_prohibited"
]
]
]
}
]
},
"Response463397119C53_DomainAnalyticsWhoisOverviewLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsWhoisOverviewLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsWhoisOverviewLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsWhoisOverviewLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_DomainAnalyticsWhoisOverviewLiveResultInfo": {
"type": "object",
"properties": {
"total_count": {
"type": [
"integer",
"null"
],
"description": "total amount of results in our database relevant to your request",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"offset": {
"type": [
"integer",
"null"
],
"description": " results offset value specified in POST request"
},
"offset_token": {
"type": [
"string",
"null"
]
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainAnalyticsWhoisOverviewLiveItem"
}
]
},
"description": "contains ranking and traffic data"
}
}
},
"Response463397119C53_DomainAnalyticsWhoisOverviewLiveItem": {
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain name"
},
"created_datetime": {
"type": [
"string",
"null"
],
"description": "date and time of registration
date and time (in the ISO 8601 format) when the domain was first registered
example: \"1997-03-29 03:00:00 +00:00\""
},
"changed_datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the domain entry was changed
date and time (in the ISO 8601 format) when the domain entry was last modified
example: \"2021-01-14 08:36:28 +00:00\""
},
"expiration_datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the domain will expire
date and time (in the ISO 8601 format) when the domain is due to expire
example: \"2022-11-26 17:21:23 +00:00\""
},
"updated_datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the domain was updated
date and time (in the ISO 8601 format) when the domain was last updated
example: \"2021-01-29 13:59:38 +00:00\""
},
"first_seen": {
"type": [
"string",
"null"
],
"description": "date and time when our crawler found the domain for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: \"2019-11-15 12:57:46 +00:00\""
},
"epp_status_codes": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extensive provisioning protocol status codes
the status of a domain name registration as defined by ICANN"
},
"tld": {
"type": [
"string",
"null"
],
"description": "top-level domain
top-level domain in the DNS root zone"
},
"registered": {
"type": [
"boolean",
"null"
],
"description": "domain registration status
if false, the domain name registration has expired
Note: expired domains will remain in the database for only a short period of time"
},
"registrar": {
"type": [
"string",
"null"
],
"description": "domain registrar
if null, the domain registrar is unknown
example:NameCheap, Inc."
},
"metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MetricsBundleInfo"
}
],
"description": "ranking data relevant to the specified domain"
},
"backlinks_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BacklinksInfo"
}
],
"description": "backlink data for the returned domain"
}
},
"description": "items array"
},
"Response463397119C53_MetricsBundleInfo": {
"type": "object",
"properties": {
"organic": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MetricsInfo"
}
],
"properties": {
"is_new": {
"type": [
"integer",
"null"
],
"description": "number of new ranked elements\nindicates how many new ranked elements were found for this domain",
"format": "int64"
},
"is_up": {
"type": [
"integer",
"null"
],
"description": "rank went up\nindicates how many ranked elements of this domain went up in Google Search",
"format": "int64"
},
"is_down": {
"type": [
"integer",
"null"
],
"description": "rank went down\nindicates how many ranked elements of this domain went down in Google Search",
"format": "int64"
},
"is_lost": {
"type": [
"integer",
"null"
],
"description": "lost ranked elements\nindicates how many ranked elements of this domain were previously presented in SERPs, but weren’t found during the last check",
"format": "int64"
}
},
"description": "ranking and traffic data from organic search"
},
"paid": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MetricsInfo"
}
],
"description": "ranking and traffic data from paid search"
}
}
},
"Response463397119C53_MetricsInfo": {
"type": "object",
"properties": {
"pos_1": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #1"
},
"pos_2_3": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #2-3"
},
"pos_4_10": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #4-10"
},
"pos_11_20": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #11-20"
},
"pos_21_30": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #21-30"
},
"pos_31_40": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #31-40"
},
"pos_41_50": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #41-50"
},
"pos_51_60": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #51-60"
},
"pos_61_70": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #61-70"
},
"pos_71_80": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #71-80"
},
"pos_81_90": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #81-90"
},
"pos_91_100": {
"type": [
"integer",
"null"
],
"description": "number of organic SERPs where the domain ranks #91-100"
},
"etv": {
"type": [
"number",
"null"
],
"description": "estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for
learn more about how the metric is calculated in this help center article"
},
"count": {
"type": [
"integer",
"null"
],
"description": "total count of organic SERPs that contain the domain",
"format": "int64"
},
"estimated_paid_traffic_cost": {
"type": [
"number",
"null"
],
"description": "estimated cost of converting organic search traffic into paid
represents the estimated monthly cost of running ads (USD) for all keywords a domain ranks for
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search
learn more about how the metric is calculated in this help center article"
},
"is_new": {
"type": [
"integer",
"null"
],
"description": "number of new ranked elements\nindicates how many new ranked elements were found for this domain",
"format": "int64"
},
"is_up": {
"type": [
"integer",
"null"
],
"description": "rank went up\nindicates how many ranked elements of this domain went up in Google Search",
"format": "int64"
},
"is_down": {
"type": [
"integer",
"null"
],
"description": "rank went down\nindicates how many ranked elements of this domain went down in Google Search",
"format": "int64"
},
"is_lost": {
"type": [
"integer",
"null"
],
"description": "lost ranked elements\nindicates how many ranked elements of this domain were previously presented in SERPs, but weren’t found during the last check",
"format": "int64"
}
}
},
"Response463397119C53_KeywordsDataBingAudienceEstimationIndustriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationIndustriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationIndustriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationIndustriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationIndustriesResultInfo": {
"type": "object",
"properties": {
"industry_id": {
"type": [
"integer",
"null"
],
"description": "ID of the industry",
"format": "int64"
},
"industry_name": {
"type": [
"string",
"null"
],
"description": "name of the industry"
}
}
},
"Response463397119C53_KeywordsDataBingAudienceEstimationJobFunctionsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationJobFunctionsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationJobFunctionsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationJobFunctionsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationJobFunctionsResultInfo": {
"type": "object",
"properties": {
"job_function_id": {
"type": [
"integer",
"null"
],
"description": "ID of the job function",
"format": "int64"
},
"job_function_name": {
"type": [
"string",
"null"
],
"description": "name of the job function"
}
}
},
"Provider463397119C53_KeywordsDataBingAudienceEstimationLiveRequestInfo": {
"type": "object",
"properties": {
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius (in km)\" format
the data will be provided for the country the specified coordinates belong to
example:29.6821525,-82.4098881,100"
},
"age": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "selection of age ranges for targeting
possible values: eighteen_to_twenty_four, fifty_to_sixty_four, sixty_five_and_above, thirteen_to_seventeen, thirty_five_to_forty_nine, twenty_five_to_thirty_four, unknown, zero_to_twelve"
},
"bid": {
"type": [
"number",
"null"
],
"description": "desired bid setting value in USD
maximum value: 1000"
},
"daily_budget": {
"type": [
"number",
"null"
],
"description": "daily campaign budget value in USD
maximum value: 10000"
},
"gender": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "gender to target
possible values: male, female, unknown"
},
"industry": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "industry of LinkedIn profile targeting806301758"
},
"job_function": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "job function of LinkedIn profile targeting806300451"
}
},
"example": [
{
"location_coordinate": "29.6821525,-82.4098881,100",
"age": [
"twenty_five_to_thirty_four",
"eighteen_to_twenty_four",
"unknown"
],
"bid": 1,
"daily_budget": 24,
"gender": [
"male"
],
"industry": [
"806303407",
"806301758"
],
"job_function": [
"806298607"
]
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationLiveResultInfo": {
"type": "object",
"properties": {
"est_impressions": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated impressions range"
},
"est_audience_size": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated reach user count range"
},
"est_clicks": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated click count range"
},
"est_spend": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated spending range"
},
"est_cost_per_event": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "indicates the estimated cost per event with range result"
},
"est_ctr": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "estimated click-through rate range"
},
"suggested_bid": {
"type": [
"number",
"null"
],
"description": "suggested bid value under the current targeting"
},
"suggested_budget": {
"type": [
"number",
"null"
],
"description": "suggested daily budget value under the current targeting and bid",
"format": "double"
},
"events_lost_to_bid": {
"type": [
"integer",
"null"
],
"description": "indicates event lost count due to insufficient input bid",
"format": "int64"
},
"events_lost_to_budget": {
"type": [
"integer",
"null"
],
"description": "indicates the event lost count due to insufficient input budget"
},
"est_reach_audience_size": {
"type": [
"integer",
"null"
],
"description": "monthly estimated user count",
"format": "int64"
},
"est_reach_impressions": {
"type": [
"integer",
"null"
],
"description": "monthly estimated impressions",
"format": "int64"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency nameUSDollar"
}
}
},
"Response463397119C53_AudienceEstimationInfo": {
"type": "object",
"properties": {
"high": {
"type": [
"number",
"null"
],
"description": "indicates the upper bound of the range result",
"format": "double"
},
"low": {
"type": [
"number",
"null"
],
"description": "indicates the lower bound of the range result",
"format": "double"
}
}
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTaskGetResultInfo": {
"type": "object",
"properties": {
"est_impressions": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated impressions range"
},
"est_audience_size": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated reach user count range"
},
"est_clicks": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated click count range"
},
"est_spend": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "monthly estimated spending range"
},
"est_cost_per_event": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "indicates the estimated cost per event with range result"
},
"est_ctr": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AudienceEstimationInfo"
}
],
"description": "estimated click-through rate range"
},
"suggested_bid": {
"type": [
"number",
"null"
],
"description": "suggested bid value under the current targeting"
},
"suggested_budget": {
"type": [
"number",
"null"
],
"description": "suggested daily budget value under the current targeting and bid",
"format": "double"
},
"events_lost_to_bid": {
"type": [
"integer",
"null"
],
"description": "indicates event lost count due to insufficient input bid",
"format": "int64"
},
"events_lost_to_budget": {
"type": [
"integer",
"null"
],
"description": "indicates the event lost count due to insufficient input budget"
},
"est_reach_audience_size": {
"type": [
"integer",
"null"
],
"description": "monthly estimated user count",
"format": "int64"
},
"est_reach_impressions": {
"type": [
"integer",
"null"
],
"description": "monthly estimated impressions",
"format": "int64"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency nameUSDollar"
}
}
},
"Provider463397119C53_KeywordsDataBingAudienceEstimationTaskPostRequestInfo": {
"type": "object",
"properties": {
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius (in km)\" format
the data will be provided for the country the specified coordinates belong to
example:29.6821525,-82.4098881,100"
},
"age": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "selection of age ranges for targeting
possible values: eighteen_to_twenty_four, fifty_to_sixty_four, sixty_five_and_above, thirteen_to_seventeen, thirty_five_to_forty_nine, twenty_five_to_thirty_four, unknown, zero_to_twelve"
},
"bid": {
"type": [
"number",
"null"
],
"description": "desired bid setting value in USD
maximum value: 1000"
},
"daily_budget": {
"type": [
"number",
"null"
],
"description": "daily campaign budget value in USD
maximum value: 10000"
},
"gender": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "gender to target
possible values: male, female, unknown"
},
"industry": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "industry of LinkedIn profile targeting806301758"
},
"job_function": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "job function of LinkedIn profile targeting806300451"
}
},
"example": [
{
"location_coordinate": "29.6821525,-82.4098881,100",
"age": [
"twenty_five_to_thirty_four",
"eighteen_to_twenty_four",
"unknown"
],
"bid": 1,
"daily_budget": 24,
"gender": [
"male"
],
"industry": [
"806303407",
"806301758"
],
"job_function": [
"806298607"
]
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingAudienceEstimationTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingAudienceEstimationTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
]
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
]
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the task"
}
}
},
"Provider463397119C53_KeywordsDataBingKeywordPerformanceLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase, data will be provided in a separate arraykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device typepossible values: desktop, mobile, tablet, all
default value: all"
},
"match": {
"type": [
"string",
"null"
],
"description": "keywords match type
optional field
can take the following values:aggregate returns data across all match types;broad returns data for all user queries containing the specified keyword with varying word order;phrase returns data for all user queries containing the specified keyword with identical word order;exact returns data for user query that matches the specified keyword;Note: the aggregate match type is applied by default"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:\"United States\""
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:\"en\""
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"keywords": [
"dataforseo",
"seo",
"ranking"
]
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"year": {
"type": [
"integer",
"null"
],
"description": "indicates the year for which the data is provided for
example:2020"
},
"month": {
"type": [
"integer",
"null"
],
"description": "indicates the month for which the data is provided for
example:10"
},
"keyword_kpi": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordKpi"
}
],
"description": "object containing keyword metrics
if there is no data, then the value is_nulln"
}
}
},
"Response463397119C53_KeywordKpi": {
"type": "object",
"properties": {
"desktop": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordKpiItemInfo"
}
]
},
"description": "keyword data aggregated for desktop devices
if there is no data, then the value is_nulln"
},
"mobile": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordKpiItemInfo"
}
]
},
"description": "keyword data aggregated for mobile devices
if there is no data, then the value is_nulln"
},
"tablet": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordKpiItemInfo"
}
]
},
"description": "keyword data aggregated for tablet devices
if there is no data, then the value is_nulln"
}
}
},
"Response463397119C53_KeywordKpiItemInfo": {
"type": "object",
"properties": {
"ad_position": {
"type": [
"string",
"null"
],
"description": "represents the position of the relevant ad in SERP
can take the following values:FirstPage1: The first ad to appear on the right side of the first search results pageFirstPage2: The second ad to appear on the right side of the first search results pageFirstPage3: The third ad to appear on the right side of the first search results pageFirstPage4: The fourth ad to appear on the right side of the first search results pageFirstPage5: The fifth ad to appear on the right side of the first search results pageFirstPage6: The sixth ad to appear on the right side of the first search results pageFirstPage7: The seventh ad to appear on the right side of the first search results pageFirstPage8: The eighth ad to appear on the right side of the first search results pageFirstPage9: The ninth ad to appear on the right side of the first search results pageFirstPage10: The tenth ad to appear on the right side of the first search results pageMainLine1: The first ad to appear at the top of the search results pageMainLine2: The second ad to appear at the top of the search results pageMainLine3: The third ad to appear at the top of the search results pageMainLine4: The fourth ad to appear at the top of the search results page"
},
"clicks": {
"type": [
"integer",
"null"
],
"description": "ad clicks
the number of clicks that the keyword and match type generated during the last month"
},
"impressions": {
"type": [
"integer",
"null"
],
"description": "ad impressions
the number of impressions that the keyword and match type generated during the last month"
},
"average_cpc": {
"type": [
"number",
"null"
],
"description": "average cost per click, USD
calculated by dividing the cost of all clicks by the number of clicks",
"format": "double"
},
"ctr": {
"type": [
"number",
"null"
],
"description": "click-through rate as a percentage
calculated by dividing the number of clicks by the number of impressions and multiplying the result by 100",
"format": "double"
},
"total_cost": {
"type": [
"number",
"null"
],
"description": "total cost of an ad, USD
the cost of using the specified keyword and match type during the last month",
"format": "int64"
},
"average_bid": {
"type": [
"number",
"null"
],
"description": "average bid of the keyword",
"format": "double"
}
}
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceLocationsAndLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceLocationsAndLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceLocationsAndLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceLocationsAndLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceLocationsAndLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code"
},
"available_locations": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvailableLocations"
}
]
},
"description": "supported locations
contains locations supported in combination with a specific language"
}
}
},
"Response463397119C53_AvailableLocations": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "location name"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
possible values:Country, Region"
}
}
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"year": {
"type": [
"integer",
"null"
],
"description": "indicates the year for which the data is provided for
example:2020monthn"
},
"month": {
"type": [
"integer",
"null"
]
},
"keyword_kpi": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordKpi"
}
],
"description": "object containing keyword metrics
if there is no data, then the value is_nulln"
}
}
},
"Provider463397119C53_KeywordsDataBingKeywordPerformanceTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the specified keywords will be converted to lowercase, data will be provided in a separate arraykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device typepossible values: desktop, mobile, tablet, all
default value: all"
},
"match": {
"type": [
"string",
"null"
],
"description": "keywords match type
optional field
can take the following values:aggregate returns data across all match types;broad returns data for all user queries containing the specified keyword with varying word order;phrase returns data for all user queries containing the specified keyword with identical word order;exact returns data for user query that matches the specified keyword;Note: the aggregate match type is applied by default"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:\"United States\""
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
you can receive the list of available locations and languages by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/keyword_performance/locations_and_languages
example:\"en\""
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"keywords": [
"dataforseo",
"seo",
"ranking"
]
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordPerformanceTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordPerformanceTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataBingKeywordsForKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
you can specify the maximum of 200 keywords with each keyword containing no more than 100 characters;
the specified keywords will be converted to lowercase, data will be provided in a separate arraykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:English, French, German"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:en, fr, de"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance"
},
"keywords_negative": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "keywords negative array
optional field
These keywords will be ignored in the results array;
You can specify a maximum of 200 terms that you want to exclude from the results;
the specified keywords will be converted to lowercase format"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device type;
possible values: all, mobile, desktop, tablet
default value: all"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_name": "United States",
"language_name": "English",
"keywords": [
"average page rpm adsense",
"adsense blank ads how long",
"leads and prospects"
]
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks is included in the response"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
indicates for what device type the data is provided;
possible values: all, mobile, desktop, tablet"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.
Possible values: 0.1, 0.5,0.90.1 - low competition,0.5 - medium competition,0.9 - high competition;
if there is no data the value is null"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is_nulln"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the keyword on the Bing search engine, depending on the user’s targetingsearch volume is rounded to the closest decimal valuesnulln",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product and service categories
legacy field, the value will always be null"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is_nulln"
}
}
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
]
},
"language_code": {
"type": [
"string",
"null"
]
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
indicates for what device type the data is provided;
possible values: all, mobile, desktop, tablet"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.
Possible values: 0.1, 0.5,0.9 0.1 - low competition,0.5 - medium competition, 0.9 - high competition;
if there is no data the value is null"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is_nulln"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the keyword on the Bing search engine, depending on the user’s targetingnulln",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product and service categories
legacy field, the value will always be null"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is_nulln"
}
}
},
"Provider463397119C53_KeywordsDataBingKeywordsForKeywordsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
you can specify the maximum of 200 keywords with each keyword containing no more than 100 characters;
the specified keywords will be converted to lowercase, data will be provided in a separate arraykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:English, French, German"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:en, fr, de"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance"
},
"keywords_negative": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "keywords negative array
optional field
These keywords will be ignored in the results array;
You can specify a maximum of 200 terms that you want to exclude from the results;
the specified keywords will be converted to lowercase format"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device type;
possible values: all, mobile, desktop, tablet
default value: all"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"keywords": [
"average page rpm adsense",
"adsense blank ads how long",
"leads and prospects"
]
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForKeywordsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataBingKeywordsForSiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain or URL
required field
the domain name or URL of the target website"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:English, French, German"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:en, fr, de"
},
"keywords_negative": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "keywords negative array
optional field
These keywords will be ignored in the results array;
You can specify a maximum of 200 terms that you want to exclude from the results;
the specified keywords will be converted to lowercase format"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device typepossible values: all, mobile, desktop, tablet
default value: all"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
note: we do not recommend using a custom time range for the past year's dates;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "Bing search partners type
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"target": "dataforseo.com"
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForSiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForSiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type in a POST array
if there is no data, then the value is_nulln"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.
Possible values: 0.1, 0.5,0.90.1 - low competition,0.5 - medium competition,0.9 - high competition;
if there is no data the value is null"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data, then the value is_nulln"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the keyword on the Bing search engine, depending on the user’s targetingsearch volume is rounded to the closest decimal valuesif there is no data, then the value is_nulln",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product and service categories
legacy field, the value will always be null"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword (as available for the past twelve months), targeted to the specified geographic locations.
if there is no data, then the value is_nulln"
}
}
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForSiteTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForSiteTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data the value is null"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type in a POST array
if there is no data, then the value is_nulln"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.
Possible values: 0.1, 0.5,0.9 0.1 - low competition,0.5 - medium competition, 0.9 - high competition;
if there is no data the value is null"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data the value is null"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the given keyword idea on Bing search engine depending on the user’s targeting
if there is no data then the value is_nulln",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product and service categories
legacy field, the value will always be null"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locationsnull"
}
}
},
"Provider463397119C53_KeywordsDataBingKeywordsForSiteTaskPostRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain or URL
required field
the URL of the webpage or the domain to scan for possible keywords"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:English, French, German"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:en, fr, de"
},
"keywords_negative": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "keywords negative array
optional field
These keywords will be ignored in the results array;
You can specify a maximum of 200 terms that you want to exclude from the results;
the specified keywords will be converted to lowercase format"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device type
possible values: all, mobile, desktop, tablet
default value: all"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"target": "dataforseo.com"
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingKeywordsForSiteTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingKeywordsForSiteTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_KeywordsDataBingLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:\"location_code\": 9041134,where
\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",
\"location_code_parent\": 20044location_code_parent corresponds to:\"location_code\": 20044,"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Provider463397119C53_KeywordsDataBingSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
\"location_name\": \"Lower Austria,Austria\"
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 100
the specified keywords will be converted to lowercase, data will be provided in a separate arraylearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:English, French, German"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:en, fr, de"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device type;
possible values: all, mobile, desktop, tablet
default value: all"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimal value: 24 months from today's date;
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"Note: we do not recommend using a custom time range for the past year's dates"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
note: we do not recommend using a custom time range for the past year's dates;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"Note: we do not recommend using a custom time range for the past year's dates"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "Bing search partners type
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_name": "United States",
"language_code": "en",
"keywords": [
"tom and jerry",
"silicon valley",
"spider man"
]
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type in a POST array
if there is no data, then the value is_nulln"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.
Possible values: 0.1, 0.5,0.90.1 - low competition,0.5 - medium competition,0.9 - high competition;
if there is no data the value is null"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data then the value is_nulln"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents either the (approximate) number of searches for the given keyword idea on bing search engine depending on the user’s targeting;
search volume is rounded to the nearest tens;
if there is no data, the value is_nulln",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product and service categories
our API doesn't return categories for this endpoint: the parameter will always equal null"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations
if there is no data then the value is_nulln"
}
}
},
"Response463397119C53_KeywordsDataBingSearchVolumeTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type in a POST array
if there is no data, then the value is_nulln"
},
"competition": {
"type": [
"number",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only. This value is based on Bing Ads data.
Possible values: 0.1, 0.5,0.9 0.1 - low competition,0.5 - medium competition, 0.9 - high competition;
if there is no data the value is null"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost-per-click
represents the average cost per click (USD) historically paid for the keyword.
if there is no data then the value is_nulln"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
search volume is rounded to the nearest tens",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product and service categories
our API doesn't return categories for this endpoint: the parameter will always equal null"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations
if there is no data then the value is_nulln"
}
}
},
"Provider463397119C53_KeywordsDataBingSearchVolumeTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 100
the specified keywords will be converted to lowercase, data will be provided in a separate arraykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
supported languages:English, French, German"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
supported languages:en, fr, de"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
specify this field if you want to get the data for a particular device typepossible values: all, mobile, desktop, tablet
default value: all"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by search_volume, cpc, competition or relevance in the descending order
default value: relevance"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, data will be provided for the last 12 months
minimal value: 24 months from today's date
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"
optional field
if you don't specify this field, data will be provided for the last 12 months;
minimum value: two years back from today’s date;
maximum value: one month from today's date;
note: we do not recommend using a custom time range for the past year's dates;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Bing, Yahoo, AOL and partner sites that host Bing, AOL, and Yahoo search.
default value: false - results are returned for Bing, AOL, and Yahoo search networks"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_name": "United States",
"language_name": "English",
"keywords": [
"average page rpm adsense",
"adsense blank ads how long",
"leads and prospects"
]
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataBingSearchVolumeHistoryLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 100
the specified keywords will be converted to lowercase, data will be provided in a separate arraylearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engines with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engines with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages"
},
"device": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "device types
optional field
specify this field if you want to get the data for a particular device types
possible values: mobile, desktop, tablet, non_smartphones
default value: [\"mobile\", \"desktop\", \"tablet\", \"non_smartphones\"]"
},
"period": {
"type": [
"string",
"null"
],
"description": "aggregates the returned data to a certain time period
optional field
specify this field if you want to get the data in monthly, weekly or daily formatpossible values: monthly, weekly, dailymonthly - returns data up to past 24 monthsweekly - returns data up to past 15 weeksdaily - returns data up to past 45 daysmonthly"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimum value: 24 months back from today’s date;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;\"yyyy-mm-dd\"
example:\"2020-01-01\"Note: we do not recommend using a custom time range;date_from and date_to parameters are not specified, the data will be returned for the past 24 months;period parameter:weekly, you will get results for the past 15 weeks;
with value daily, you will get results for the past 45 days"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional fieldminimum value: two years back from today’s date;
maximum value: one day from today's date;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"date_from and date_to parameters are not specified, the data will be returned for the past 24 monthsperiod parameter:weekly, you will get results for the past 15 weeks
with value daily, you will get results for the past 45 days"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"keywords": [
"10 minute timer"
]
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"device": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"period": {
"type": [
"string",
"null"
],
"description": "time period
indicates if returned data is aggregated to a certain time period
default value monthly"
},
"searches": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeHistorySearchInfo"
}
],
"description": "contains results distributed by device type
if the device parameter is not specified, the data will be returned for all available device types"
}
}
},
"Response463397119C53_SearchVolumeHistorySearchInfo": {
"type": "object",
"properties": {
"desktop": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeHistoryItemInfo"
}
]
},
"description": "device type = desktop
contains historical search volume data for searches made from desktop devices"
},
"non_smartphones": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeHistoryItemInfo"
}
]
},
"description": "device type = non-smartphones
contains historical search volume data for searches made from feature phones (non-smartphone mobile devices)"
},
"mobile": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeHistoryItemInfo"
}
]
},
"description": "device type = mobile
contains historical search volume data for searches made from mobile devices"
},
"tablet": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeHistoryItemInfo"
}
]
},
"description": "device type = tablet
contains historical search volume data for searches made from tablets"
}
}
},
"Response463397119C53_SearchVolumeHistoryItemInfo": {
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "year"
},
"month": {
"type": [
"integer",
"null"
],
"description": "month"
},
"day": {
"type": [
"integer",
"null"
],
"description": "day of the month"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "search volume rate",
"format": "int64"
}
},
"description": "device type = desktop\ncontains historical search volume data for searches made from desktop devices"
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryLocationsAndLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryLocationsAndLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryLocationsAndLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryLocationsAndLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryLocationsAndLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
},
"available_locations": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvailableLocations"
}
]
},
"description": "array of available locations for a certain language"
}
}
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"device": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"period": {
"type": [
"string",
"null"
]
},
"searches": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SearchVolumeHistorySearchInfo"
}
]
}
}
},
"Provider463397119C53_KeywordsDataBingSearchVolumeHistoryTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 100
the specified keywords will be converted to lowercase, data will be provided in a separate arraykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/bing/search_volume_history/locations_and_languages
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the data will be provided for the country the specified coordinates belong to
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
]
},
"language_code": {
"type": [
"string",
"null"
]
},
"device": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "device types
optional field
specify this field if you want to get the data for a particular device types
possible values: mobile, desktop, tablet, non_smartphones
default value: [\"mobile\", \"desktop\", \"tablet\", \"non_smartphones\"]"
},
"period": {
"type": [
"string",
"null"
],
"description": "aggregates the returned data to a certain time period
optional field
specify this field if you want to get the data in monthly, weekly or daily formatmonthly, weekly, dailymonthly - returns data up to past 24 monthsweekly - returns data up to past 15 weeksdaily - returns data up to past 45 daysmonthly"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimum value: two years back from today’s date
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior;
date format: \"yyyy-mm-dd\"
example:\"2020-01-01\"date_from and date_to parameters are not specified, the data will be returned for the past 24 monthsperiod parameter:weekly, you will get results for the past 15 weeks
with value daily, you will get results for the past 45 days"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
maximum value: one day from today's date;
date format: \"yyyy-mm-dd\"
example:\"2020-03-15\"date_from and date_to parameters are not specified, the data will be returned for the past 24 monthsperiod parameter:weekly, you will get results for the past 15 weeks
with value daily, you will get results for the past 45 days"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"keywords": [
"10 minute timer"
]
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataBingSearchVolumeHistoryTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataClickstreamDataBulkSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
each keyword should be at least 3 characters long;
the keywords will be converted to lowercase format;
Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:2840"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"tag": "test-tag",
"keywords": [
"you tube",
"youtube",
"youtub"
]
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataBulkSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataBulkSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataBulkSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataBulkSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataBulkSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataSearchVolumeLiveItem"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_KeywordsDataClickstreamDataSearchVolumeLiveItem": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword provided in the POST array"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "current search volume rate of a keyword",
"format": "int64"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly search volume rates
array of objects with search volume rates in a certain month of a year"
}
}
},
"Provider463397119C53_KeywordsDataClickstreamDataDataforseoSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000
the keywords will be converted to lowercase format
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don’t specify location_code
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don’t specify location_name
if you use this field, you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:2826"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if don’t specify language_code
you can receive the list of available languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if don’t specify language_name
you can receive the list of available languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/clickstream_data/locations_and_languages
example:en"
},
"use_clickstream": {
"type": [
"boolean",
"null"
],
"description": "use clickstream data to provide results
optional field
if set to true, you will get DataForSEO search volume values based on clickstream data;
if set to false, Bing search volume data will be used to calculate DataForSEO search volume;
default value: true;
Note: Bing search volume is available for locations provided in Bing Search Volume History Locations and Bing Ads Locations endpoints; search volume values for any other location are calculated based on clickstream data even if you set this parameter to false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"tag": "test-tag",
"keywords": [
"you tube",
"youtube",
"youtub"
]
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataDataforseoSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataDataforseoSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataDataforseoSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataDataforseoSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataDataforseoSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
Note:if the keyword in the POST array appears to be misspelled, data will be returned for the correctly spelled keyword;
we use the functionality of Google Ads API to check and validate the spelling of keywords, learn more by this link"
},
"use_clickstream": {
"type": [
"boolean",
"null"
],
"description": "indicates if the use_clickstream parameter is active
possible values: true, false"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "ithe number of results returned in the items array"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataSearchVolumeLiveItem"
}
]
},
"description": "array of keywords
contains keywords and their search volume rates"
}
}
},
"Provider463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "target keywords
required field
UTF-8 encoding
maximum number of keywords you can specify in this array: 1000;
each keyword should be at least 3 characters long;
the keywords will be converted to lowercase format;
Note: certain symbols and characters (e.g., UTF symbols, emojis) are not allowed
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"tag": "test-tag",
"keywords": [
"you tube",
"youtube",
"youtub"
]
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveItem"
}
]
},
"description": "contains keywords and related data"
}
}
},
"Response463397119C53_KeywordsDataClickstreamDataGlobalSearchVolumeLiveItem": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "clickstream-based average monthly search volume rate
represents the (approximate) number of searches for the given keyword idea based on clickstream
you can learn more about clickstream search volume in this Help Center article",
"format": "int64"
},
"country_distribution": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CountryDistribution"
}
]
},
"description": "distribution of clickstream by countries
represents clickstream-based search volume in available countries, as well as its respective percentage of global search volume"
}
}
},
"Response463397119C53_CountryDistribution": {
"type": "object",
"properties": {
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "country ISO code"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "clickstream-based average monthly search volume rate
represents the (approximate) number of searches for the given keyword idea based on clickstream
you can learn more about clickstream search volume in this Help Center article",
"format": "int64"
},
"percentage": {
"type": [
"number",
"null"
],
"description": "percentage of global search volume"
}
}
},
"Response463397119C53_KeywordsDataClickstreamDataLocationsAndLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataLocationsAndLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataLocationsAndLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataClickstreamDataLocationsAndLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataClickstreamDataLocationsAndLanguagesResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"string",
"null"
],
"description": "the code of the superordinate location
the value will be null as Country is the only supported location_type for this API"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
possible values:Country"
},
"available_languages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvailableLanguages"
}
]
},
"description": "supported languages
contains the languages which are supported for a specific location"
}
}
},
"Provider463397119C53_KeywordsDataDataforseoTrendsDemographyLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
the maximum number of keywords you can specify: 5
avoid symbols and special characters (e.g., UTF symbols, emojis);
specifying non-Latin characters, you’ll get data for the countries where they are usedkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:2840"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"time_range": {
"type": [
"string",
"null"
],
"description": "preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"rugby",
"cricket"
],
"date_from": "2023-01-01",
"date_to": "2024-01-01",
"type": "web",
"location_name": "United States"
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsDemographyLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsDemographyLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsDemographyLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsDemographyLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsDemographyLiveResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsDemographyElementItem"
}
]
},
"description": "contains keyword popularity and related data"
}
}
},
"Response463397119C53_DataforseoTrendsDemographyElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataDataforseoTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"demography": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Demography"
}
],
"description": "demographic breakdown of keyword popularity data per each specified term
conains keyword popularity data by age and gender"
},
"demography_comparison": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DemographyComparisonInfo"
}
],
"description": "comparison of demographic data on keyword popularity for the specified parameters
conains keyword popularity data by age and gender
if you specified a single keyword, the value will be null"
}
}
}
]
},
"Response463397119C53_BaseKeywordDataDataforseoTrendsItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"position": {
"type": [
"integer",
"null"
],
"description": "the alignment of the element
can take the following values: 1, 2, 3, 4, etc."
},
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"dataforseo_trends_graph": "#/components/schemas/Response463397119C53_DataforseoTrendsDataforseoTrendsGraphElementItem",
"subregion_interests": "#/components/schemas/Response463397119C53_DataforseoTrendsSubregionInterestsElementItem",
"demography": "#/components/schemas/Response463397119C53_DataforseoTrendsDemographyElementItem"
}
}
},
"Response463397119C53_DataforseoTrendsDataforseoTrendsGraphElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataDataforseoTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"data": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsGraphDataTrendsGraphDataInfo"
}
]
},
"description": "contains the same parameters that you specified in the POST request
"
},
"averages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
}
}
}
}
]
},
"Response463397119C53_DataforseoTrendsGraphDataTrendsGraphDataInfo": {
"type": "object",
"properties": {
"date_from": {
"type": [
"string",
"null"
],
"description": "start date of the corresponding time range
in the UTC format: \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "end date of the corresponding time range
in the UTC format: \"yyyy-mm-dd\""
},
"timestamp": {
"type": [
"integer",
"null"
],
"description": "a point in time in the Unix time format"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
},
"description": "relative keyword popularity rate at a specific timestamp
represents the keyword popularity rate over the given time range
if you specify more than one keyword, the values will be averaged to the highest value across all specified keywords
a value of 100 is the peak popularity for the term. A value of 50 means that the term is half as popular. A score of 0 means there was not enough data for this term"
}
}
},
"Response463397119C53_DataforseoTrendsSubregionInterestsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataDataforseoTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"interests": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsinterestsInfo"
}
]
},
"description": "subregional keyword popuarity data for each specified term"
},
"interests_comparison": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_InterestsComparison"
}
],
"description": "comparison of data on subregional keyword popularity for the specified parameters
if you specified a single keyword, the value will be null"
}
}
}
]
},
"Response463397119C53_DataforseoTrendsinterestsInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "relevant keyword
the data included in the values element is based on this keyword"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsinterestsValuesInfo"
}
]
},
"description": "contains data on relative keyword popularity by country or region"
}
}
},
"Response463397119C53_DataforseoTrendsinterestsValuesInfo": {
"type": "object",
"properties": {
"geo_id": {
"type": [
"string",
"null"
],
"description": "location identifier
you can use this field for matching obtained results with location parameters specified in the request
see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
example:US-NY"
},
"geo_name": {
"type": [
"string",
"null"
],
"description": "location name
you can use this field for matching obtained results with location parameters specified in the request
see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
example:Andorra"
},
"value": {
"type": [
"integer",
"null"
],
"description": "relative keyword popularity rate in a given location
represents location-specific keyword popularity rate over the specified time range;
using this value you can understand how popular a keyword is in one location compared to another location;
calculation: we determine the highest popularity value for the relevant keyword across all locations, and then express all other values as a percentage of that highest value (100);
a value of 100 is the highest popularity for the term
a value of 50 means that the term is half as popular
a value of 0 means there was not enough data for this term"
}
}
},
"Response463397119C53_InterestsComparison": {
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AbsoluteItems"
}
]
},
"description": "contains keyword popularity and related data"
},
"absolute_items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AbsoluteItems"
}
]
},
"description": "keyword popularity rates across all locations
values in this array represent percentages relative to the maximum value across all locations"
}
}
},
"Response463397119C53_AbsoluteItems": {
"type": "object",
"properties": {
"geo_id": {
"type": [
"string",
"null"
],
"description": "location identifier
you can use this field for matching obtained results with location parameters specified in the request
see the full list of available locations with their geo_id here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
example:US-NY"
},
"geo_name": {
"type": [
"string",
"null"
],
"description": "location name
you can use this field for matching obtained results with location parameters specified in the request
see the full list of available locations with their geo_name here or by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
example:Andorra"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains data on relative keyword popularity by country or region"
}
}
},
"Response463397119C53_Demography": {
"type": "object",
"properties": {
"age": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsDataInfo"
}
]
},
"description": "distribution of keyword popularity by age"
},
"gender": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsDataInfo"
}
]
},
"description": "distribution of keyword popularity by gender"
}
}
},
"Response463397119C53_DataforseoTrendsDataInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "relevant keyword for which demographic data is provided"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DemographyItemValueInfo"
}
]
},
"description": "contains age range and corresponding keyword popularity values"
}
}
},
"Response463397119C53_DemographyItemValueInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"value": {
"type": [
"integer",
"null"
],
"description": "keyword popularity rate within the specified age range
using this value you can understand how popular a keyword is within each age range;
calculation: we determine the highest popularity value for the relevant keyword across all age groups, and then express all other values as a percentage of that highest value (100);
a value of 100 is the highest popularity for the term
a value of 0 means there was not enough data for this term"
}
}
},
"Response463397119C53_DemographyComparisonInfo": {
"type": "object",
"properties": {
"age": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
}
},
"description": "type of element"
},
"gender": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": [
"integer",
"null"
]
}
},
"description": "type of element"
}
}
},
"Provider463397119C53_KeywordsDataDataforseoTrendsExploreLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
the maximum number of keywords you can specify: 5keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:2840"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"time_range": {
"type": [
"string",
"null"
],
"description": "preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"iphone 14",
"samsung s23"
],
"location_code": 2840
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsExploreLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsExploreLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsExploreLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsExploreLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsExploreLiveResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsDataforseoTrendsGraphElementItem"
}
]
},
"description": "contains keyword popularity and related data"
}
}
},
"Response463397119C53_KeywordsDataDataforseoTrendsLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:\"location_code\": 9041134,
\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",
\"location_code_parent\": 20044
where location_code_parent corresponds to:\"location_code\": 20044,"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
\"location_name\": \"Lower Austria,Austria\"
possible values according to Google’s target types"
},
"geo_id": {
"type": [
"string",
"null"
],
"description": "DataForSEO trends location identifier
you can use this field for matching obtained results with the location_code parameter specified in the request"
}
}
},
"Provider463397119C53_KeywordsDataDataforseoTrendsMergedDataLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
the maximum number of keywords you can specify: 5
avoid symbols and special characters (e.g., UTF symbols, emojis);
specifying non-Latin characters, you’ll get data for the countries where they are usedkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:2840"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"time_range": {
"type": [
"string",
"null"
],
"description": "preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"rugby",
"cricket"
],
"date_from": "2023-01-01",
"date_to": "2024-01-01",
"type": "web",
"location_name": "United States"
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsMergedDataLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsMergedDataLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsMergedDataLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsMergedDataLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsMergedDataLiveResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataDataforseoTrendsItem"
}
]
},
"description": "contains keyword popularity and related data"
}
}
},
"Provider463397119C53_KeywordsDataDataforseoTrendsSubregionInterestsLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
the maximum number of keywords you can specify: 5
avoid symbols and special characters (e.g., UTF symbols, emojis);
specifying non-Latin characters, you’ll get data for the countries where they are usedkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_name belongs to;
example:United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/locations
note that the data will be provided for the country the specified location_code belongs to;
example:2840"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"time_range": {
"type": [
"string",
"null"
],
"description": "preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keywords": [
"rugby",
"cricket"
],
"date_from": "2023-01-01",
"date_to": "2024-01-01",
"type": "web",
"location_name": "United States"
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsSubregionInterestsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsSubregionInterestsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsSubregionInterestsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataDataforseoTrendsSubregionInterestsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataDataforseoTrendsSubregionInterestsLiveResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DataforseoTrendsSubregionInterestsElementItem"
}
]
},
"description": "contains keyword popularity and related data"
}
}
},
"Provider463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the keywords you specify will be converted to a lowercase format
Note: Google Ads may return no data for certain groups of keywords
visit our Help Center to learn more
Also note that Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"bid": {
"type": "integer",
"description": "the maximum custom bid
required field
the collected data will be based on this value
it stands for the price you are willing to pay for an ad; the higher value you specify here, the higher values you will get in the returned metrics
learn more in this help center article",
"format": "int64"
},
"match": {
"type": "string",
"description": "keywords match-type
required field
can take the following values: exact, broad, phrase"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"date_from": {
"type": "string",
"description": "starting date of the forecasting time range
required field if you specify date_to
if you indicate date_from and date_to, you don't need to specify date_interval
minimum value is tomorrow's date
the value you specify in date_from shouldn't be further than date_to
date format: \"yyyy-mm-dd\"
example:\"2021-10-30\"if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": "string",
"description": "ending date of the forecasting time range
required field if you specify date_from
if you indicate date_from and date_to, you don't need to specify date_interval
minimum value is date_from +1 day
maximum value is current day and month of the next year
date format: \"yyyy-mm-dd\"
example:\"2022-10-30\""
},
"date_interval": {
"type": [
"string",
"null"
],
"description": "forecasting date interval
optional field
if you specify date_interval, you don't need to indicate date_from and date_to
possible values: next_week, next_month, next_quarter
default value: next_month"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by relevance, impressions, ctr, average_cpc, cost, or clicks in the descending order
default value: relevance"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"language_code": "en",
"bid": 999,
"match": "exact",
"keywords": [
"seo marketing"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"date_interval": {
"type": [
"string",
"null"
],
"description": "forecasting date interval in a POST array"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
the value you specified when setting the task
Note: parameter deprecated, the value is always false"
},
"bid": {
"type": [
"number",
"null"
],
"description": "the maximum custom bid
the bid you have specified when setting the task
represents the price you are willing to pay for an ad
the higher value you have specified, the higher metrics and cost you receive in response
learn more in this help center article",
"format": "int64"
},
"match": {
"type": [
"string",
"null"
],
"description": "keywords match-type
can take the following values: exact, broad, phrase"
},
"impressions": {
"type": [
"integer",
"null"
],
"description": "projected number of ad impressions
number of impressions an ad is projected to get within the specified time period
Note: parameter deprecated, the value is always null"
},
"ctr": {
"type": [
"number",
"null"
],
"description": "projected click through rate (CTR) of the advertisement
number of clicks an ad is projected to receive divided by the number of ad impressions; the CTR is projected for the specified time period
Note: parameter deprecated, the value is always null",
"format": "double"
},
"average_cpc": {
"type": [
"number",
"null"
],
"description": "the average cost-per-click value
represents the cost-per-click (USD) estimated for a keyword based on the specified time period and historical data;
if there is no data, then the value is_nulln",
"format": "double"
},
"cost": {
"type": [
"number",
"null"
],
"description": "total tasks cost, USD"
},
"clicks": {
"type": [
"number",
"null"
],
"description": "number of clicks on an ad
number of clicks an ad is projected to get within the specified time period
if there is no data, then the value is_nulln"
}
}
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array
metrics are provided for all the keywords specified in the POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"date_interval": {
"type": [
"string",
"null"
],
"description": "forecasting date interval in a POST array"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
the value is always false"
},
"bid": {
"type": [
"number",
"null"
],
"description": "the maximum custom bid
the bid you have specified when setting the task
represents the price you are willing to pay for an ad
the higher value you have specified, the higher metrics and cost you receive in response
learn more in this help center article"
},
"match": {
"type": [
"string",
"null"
],
"description": "keywords match-type
can take the following values: exact, broad, phrase"
},
"impressions": {
"type": [
"integer",
"null"
],
"description": "projected number of ad impressions
number of impressions an ad is projected to get within the specified time period
Note: parameter deprecated, the value is always_nulln"
},
"ctr": {
"type": [
"number",
"null"
],
"description": "projected clickthrough rate (CTR) of the advertisement
number of clicks an ad is projected to receive divided by the number of ad impressions;
Note: parameter deprecated, the value is always null",
"format": "double"
},
"average_cpc": {
"type": [
"number",
"null"
],
"description": "the average cost-per-click value
represents the cost-per-click (USD) estimated for a keyword based on the specified time period and historical data;
if there is no data, then the value is_nulln",
"format": "double"
},
"cost": {
"type": [
"number",
"null"
],
"description": "charge for an ad
amount that will be charged for running an ad within the specified time period
if there is no data, then the value is_nulln"
},
"clicks": {
"type": [
"number",
"null"
],
"description": "number of clicks on an ad
number of clicks an ad is projected to get within the specified time period
if there is no data, then the value is_nulln"
}
}
},
"Provider463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the keywords you specify will be converted to a lowercase format
Note #1: Google Ads may return no data for certain groups of keywords;
Note #2: Google Ads provides combined search volume values for groups of similar keywords
to obtain search volume for similar keywords, we recommend submitting such keywords in separate requests;
Note #3: Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"bid": {
"type": "number",
"description": "the maximum custom bid
required field
the collected data will be based on this value
it stands for the price you are willing to pay for an ad; the higher value you specify here, the higher values you will get in the returned metrics
learn more in this help center article"
},
"match": {
"type": "string",
"description": "keywords match-type
required field
can take the following values: exact, broad, phrase"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"date_from": {
"type": "string",
"description": "starting date of the forecasting time range
required field if you specify date_to
if you indicate date_from and date_to, you don't need to specify date_interval
minimum value is tomorrow's date
the value you specify in date_from shouldn't be further than date_to
date format: \"yyyy-mm-dd\"
example:\"2021-10-30\"if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": "string",
"description": "ending date of the forecasting time range
required field if you specify date_from
if you indicate date_from and date_to, you don't need to specify date_interval
minimum value is date_from +1 day
maximum value is current day and month of the next year
date format: \"yyyy-mm-dd\"
example:\"2022-10-30\""
},
"date_interval": {
"type": [
"string",
"null"
],
"description": "forecasting date interval
optional field
if you specify date_interval, you don't need to indicate date_from and date_to
possible values: next_week, next_month, next_quarter
default value: next_month"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by relevance, average_cpc, cost, or clicks in the descending order
default value: relevance"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"bid": 999,
"match": "exact",
"keywords": [
"seo marketing"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 20
The maximum number of characters for each keyword: 80
the keywords you specify will be converted to a lowercase format
Note: Google Ads may return no data for certain groups of keywords
visit our Help Center to learn more
Also note that Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
Note: the indicated date cannot be greater than yesterday's date;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2022-11-30\""
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order
default value: relevance"
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "include keywords associated with adult content
optional field
if set to true, adult keywords will be included in the response
default value: false
note that the API may return no data for such keywords due to Google Ads restrictions"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"keywords": [
"phone",
"cellphone"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"spell": {
"type": [
"string",
"null"
]
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
the value you specified when setting the task
if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;
if false, the results are returned for Google search sites only"
},
"competition": {
"type": [
"string",
"null"
],
"description": "competition
represents the relative level of competition associated with the given keyword in paid SERP only
possible values: LOW, MEDIUM, HIGH
if competition level is unknown, the value is null;
learn more about the metric in this help center article"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "competition index
the competition index for the query indicating how competitive ad placement is for the keyword
can take values from 0 to 100
the level of competition from 0 to 100 is determined by the number of ad slots filled divided by the total number of ad slots available
if not enough data is available, the value is null;
learn more about the metric in this help center article"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the given keyword idea either on google.com or google.com and partners, depending on the user’s targeting
if there is no data, the value is null",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost per click
indicates the amount paid (USD) for each click on the ad displayed for a given keyword"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations
if there is no data, the value is null"
}
}
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"spell": {
"type": [
"string",
"null"
]
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
the value you specified when setting the task
if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;
if false, the results are returned for Google search sites only"
},
"competition": {
"type": [
"string",
"null"
],
"description": "competition
represents the relative level of competition associated with the given keyword in paid SERP only
possible values: LOW, MEDIUM, HIGH
if competition level is unknown, the value is null;
learn more about the metric in this help center article"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "competition index
the competition index for the query indicating how competitive ad placement is for the keyword
can take values from 0 to 100
the level of competition from 0 to 100 is determined by the number of ad slots filled divided by the total number of ad slots available
if not enough data is available, the value is null;
learn more about the metric in this help center article"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the given keyword idea either on google.com or google.com and partners, depending on the user’s targeting
if there is no data, the value is null",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost per click
indicates the amount paid (USD) for each click on the ad displayed for a given keyword"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations
if there is no data, the value is null"
}
}
},
"Provider463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 20
The maximum number of characters for each keyword: 80
the keywords you specify will be converted to a lowercase format
Note: Google Ads may return no data for certain groups of keywords
visit our Help Center to learn more
Also note that Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"target": {
"type": [
"string",
"null"
],
"description": "target website
optional field
specify a website or URL to get a list of keywords relevant to it;
Note: if a website url is specified, you will still get keywords relevant for the entire website"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
Note: the indicated date cannot be greater than yesterday's date;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2022-11-30\""
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order
default value: relevance"
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "include keywords associated with adult content
optional field
if set to true, adult keywords will be included in the response
default value: false
note that the API may return no data for such keywords due to Google Ads restrictions"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"keywords": [
"phone",
"cellphone"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForKeywordsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataGoogleAdsKeywordsForSiteLiveRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain or page
required field
the domain name of the target website or the url of the target page;
note: to obtain keywords for the target website, use the target_type parameter"
},
"target_type": {
"type": [
"string",
"null"
],
"description": "search keywords for site or for url
optional field
possible values: site, page;
default value: page;
if set to site, keywords will be provided for the entire site;
if set to page, keywords will be provided for the specified webpage"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
Note: the indicated date cannot be greater than yesterday's date;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2022-11-30\""
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "include keywords associated with adult content
optional field
if set to true, adult keywords will be included in the response
default value: false
note that the API may return no data for such keywords due to Google Ads restrictions"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order
default value: relevance"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"target": "dataforseo.com"
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"spell": {
"type": [
"string",
"null"
]
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
the value you specified when setting the task
if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;
if false, the results are returned for Google search sites only"
},
"competition": {
"type": [
"string",
"null"
],
"description": "competition
represents the relative level of competition associated with the given keyword in paid SERP only
possible values: LOW, MEDIUM, HIGH
if competition level is unknown, the value is null;
learn more about the metric in this help center article"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "competition index
the competition index for the query indicating how competitive ad placement is for the keyword
can take values from 0 to 100
the level of competition from 0 to 100 is determined by the number of ad slots filled divided by the total number of ad slots available
if not enough data is available, the value is null;
learn more about the metric in this help center article"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the given keyword idea either on google.com or google.com and partners, depending on the user’s targeting
if there is no data, the value is null",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost per click
indicates the amount paid (USD) for each click on the ad displayed for a given keyword"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations
if there is no data, the value is null"
}
}
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword in a POST array"
},
"spell": {
"type": [
"string",
"null"
]
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
the value you specified when setting the task
if true, the results are returned for owned, operated, and syndicated networks across Google and partner sites that host Google search;
if false, the results are returned for Google search sites only"
},
"competition": {
"type": [
"string",
"null"
],
"description": "competition
represents the relative level of competition associated with the given keyword in paid SERP only
possible values: LOW, MEDIUM, HIGH
if competition level is unknown, the value is null;
learn more about the metric in this help center article"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "competition index
the competition index for the query indicating how competitive ad placement is for the keyword
can take values from 0 to 100
the level of competition from 0 to 100 is determined by the number of ad slots filled divided by the total number of ad slots available
if not enough data is available, the value is null;
learn more about the metric in this help center article"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate
represents the (approximate) number of searches for the given keyword idea either on google.com or google.com and partners, depending on the user’s targeting
if there is no data, the value is null",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers)
the value may differ depending on the location specified in a POST request"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost per click
indicates the amount paid (USD) for each click on the ad displayed for a given keyword"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months), targeted to the specified geographic locations
if there is no data, the value is null"
}
}
},
"Provider463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskPostRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "domain or page
required field
the domain name of the target website or the url of the target page;
note: to obtain keywords for the target website, use the target_type parameter"
},
"target_type": {
"type": [
"string",
"null"
],
"description": "search keywords for site or url
optional field
possible values: site, page;
default value: page
if set to site, keywords will be provided for the entire site;
if set to page, keywords will be provided for the specified webpage"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
Note: the indicated date cannot be greater than yesterday's date;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2022-11-30\""
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "include keywords associated with adult content
optional field
if set to true, adult keywords will be included in the response
default value: false
note that the API may return no data for such keywords due to Google Ads restrictions"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
Use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in descending order
default value: relevance"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_code": 2840,
"target": "dataforseo.com"
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsKeywordsForSiteTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_KeywordsDataGoogleAdsSearchVolumeLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the keywords you specify will be converted to a lowercase format
Note #1: Google Ads may return no data for certain groups of keywords;
Note #2: Google Ads provides combined search volume values for groups of similar keywords
to obtain search volume for similar keywords, we recommend submitting such keywords in separate requests;
Note #3: Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
Note: the indicated date cannot be greater than the past month, Google Ads does not return data on the current month;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2022-11-30\""
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "include keywords associated with adult content
optional field
if set to_true, adult keywords will be included in the response
default value:_false
note_that the API may return no data for such keywords due to_Google Ads restrictionsn"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in the descending order
default value: relevance"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data array of the response"
}
},
"example": [
{
"location_code": 2840,
"keywords": [
"buy laptop",
"cheap laptops for sale",
"purchase laptop"
],
"date_from": "2021-08-01",
"search_partners": true
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsSearchVolumeLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsSearchVolumeLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeLiveResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"spell": {
"type": [
"string",
"null"
],
"description": "correct spelling of the keyword
Note:if the keyword in the POST array appears to be misspelled, data will be returned for the correctly spelled keyword;
we use the functionality of Google Ads API to check and validate the spelling of keywords, learn more by this link"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"competition": {
"type": [
"string",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only;
this value is based on Google Ads data and can take the following values: HIGH, MEDIUM, LOW;
if there is no data the value is null;
learn more about the metric in this help center article"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only;
this value is based on Google Ads data and can be between 0 and 100 (inclusive);
if there is no data the value is null;
learn more about the metric in this help center article"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate;
represents either the (approximate) number of searches for the given keyword idea on google.com or google.com and partners, depending on the user’s targeting;
if there is no data then the value is_nulln",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers);
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers);
the value may differ depending on the location specified in a POST request"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost per click
indicates the amount paid (USD) for each click on the ad displayed for a given keyword"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months by default), targeted to the specified geographic locations;
if there is no data then the value is_nulln"
}
}
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskGetResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"spell": {
"type": [
"string",
"null"
],
"description": "correct spelling of the keyword
Note:if the keyword in the POST array appears to be misspelled, data will be returned for the correctly spelled keyword;
we use the functionality of Google Ads API to check and validate the spelling of keywords, learn more by this link"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "indicates whether data from partner networks included in the response"
},
"competition": {
"type": [
"string",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only;
this value is based on Google Ads data and can take the following values: HIGH, MEDIUM, LOW;
if there is no data the value is null;
learn more about the metric in this help center article"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "competition
represents the relative amount of competition associated with the given keyword in paid SERP only;
this value is based on Google Ads data and can be between 0 and 100 (inclusive);
if there is no data the value is null;
learn more about the metric in this help center article"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "monthly average search volume rate",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "minimum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 20% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers);
the value may differ depending on the location specified in a POST request"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "maximum bid for the ad to be displayed at the top of the first page
indicates the value greater than about 80% of the lowest bids for which ads were displayed (based on Google Ads statistics for advertisers);
the value may differ depending on the location specified in a POST request"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "cost per click
indicates the amount paid (USD) for each click on the ad displayed for a given keyword"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MonthlySearchesInfo"
}
]
},
"description": "monthly searches
represents the (approximate) number of searches on this keyword idea (as available for the past twelve months by default), targeted to the specified geographic locations;
if there is no data then the value is_nulln"
}
}
},
"Provider463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
The maximum number of keywords you can specify: 1000
The maximum number of characters for each keyword: 80
The maximum number of words for each keyword phrase: 10
the keywords you specify will be converted to a lowercase format
Note #1: Google Ads may return no data for certain groups of keywords;
Note #2: Google Ads provides combined search volume values for groups of similar keywords
to obtain search volume for similar keywords, we recommend submitting such keywords in separate requests;
Note #3: Google Ads doesn't allow using certain symbols and characters (e.g., UTF symbols, emojis), so you can't use them when setting a task;
to learn more about which symbols and characters can be used, please refer to this articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_coordinate;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations
example:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional field
if you do not indicate the location, you will receive worldwide results, i.e., for all available locations;
if you use this field, you don't need to specify location_name or location_code;location_coordinate parameter should be specified in the \"latitude,longitude\" format;
the data will be provided for the country the specified coordinates belong to;
example:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages
example:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "include Google search partners
optional field
if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search;
default value: false - results are returned for Google search sites"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
date format: \"yyyy-mm-dd\"
minimal value: 4 years from the current date
by default, data is returned for the past 12 months;
Note: the indicated date cannot be greater than that specified in date_to and/or yesterday's date;
if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior;
if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
Note: the indicated date cannot be greater than the past month, Google Ads does not return data on the current month;
if you don't specify this field, yesterday's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2022-11-30\""
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "include keywords associated with adult content
optional field
if set to_true, adult keywords will be included in the response
default value:_false
note_that the API may return no data for such keywords due to_Google Ads restrictionsn"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
use these parameters to sort the results by relevance, search_volume, competition_index, low_top_of_page_bid, or high_top_of_page_bid in the descending order
default value: relevance"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data array of the response"
}
},
"example": [
{
"location_name": "United States",
"keywords": [
"buy laptop",
"cheap laptops for sale",
"purchase laptop"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsSearchVolumeTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsStatusResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsStatusTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsStatusTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleAdsStatusResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleAdsStatusResultInfo": {
"type": "object",
"properties": {
"actual_data": {
"type": [
"boolean",
"null"
],
"description": "indicates whether Google updated keyword data for the previous month
generally, Google updates keyword data in the middle of the month
if the value is true, Google currently provides up-to-date data for the previous month
if the value is false, we are not able to provide data for the previous month"
},
"date_update": {
"type": [
"string",
"null"
],
"description": "date of the latest update of Google Ads data
indicates the latest date when Google updated search volume, CPC, and other keyword metrics
example:2020-05-15"
},
"last_year_in_monthly_searches": {
"type": [
"integer",
"null"
],
"description": "the latest year for which search volume data is available"
},
"last_month_in_monthly_searches": {
"type": [
"integer",
"null"
],
"description": "the latest month for which search volume data is available"
}
}
},
"Response463397119C53_KeywordsDataGoogleTrendsCategoriesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsCategoriesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsCategoriesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsCategoriesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsCategoriesResultInfo": {
"type": "object",
"properties": {
"category_code": {
"type": [
"integer",
"null"
],
"description": "unique google trends category identifier"
},
"category_name": {
"type": [
"string",
"null"
],
"description": "name of the google trends category"
},
"category_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate category
example:\"category_code\": 1100,\"category_name\": \"Superhero Films\",\"category_code_parent\": 1097
where category_code_parent corresponds to: \"category_code\": 1097,\"category_name\": \"Action & Adventure Films\""
}
}
},
"Provider463397119C53_KeywordsDataGoogleTrendsExploreLiveRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field if you don't specify `category_code`
the maximum number of keywords you can specify: 5
the maximum number of characters you can specify in a keyword: 100
the minimum number of characters must be greater than 1
comma characters (,) in the specified keywords will be unset and ignored< > | \" - + = ~ ! : * ( ) [ ] { }google_trends_topics_list and google_trends_queries_list items, specify no more than 1 keywordkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can use this field as an array to set several locations, each corresponding to a specific keyword - learn more;
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/locations
example:United Kingdom"
},
"location_code": {
"type": [
"string",
"null"
],
"description": "search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can use this field as an array to set several locations, each corresponding to a specific keyword - learn more;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
default value: English
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
default value: en
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/languages
example:en"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"category_code": {
"type": "integer",
"description": "google trends search category
required field if you don't specify `keywords`
if you don't specify `keywords`, the value of this field must be greater than `0`
if you specify `keywords` and don't specify this field, the 0 value will be applied by default and the search will be carried out across all available categories
you can receive the list of available categories with their category_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/google_trends/categories"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"time_range": {
"type": [
"string",
"null"
],
"description": "preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years
possible values for web only:2004_present
possible values for news, youtube, images, froogle:2008_present"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "types of items returned
optional field
to speed up the execution of the request, specify one item at a time;
possible values:\"google_trends_graph\", \"google_trends_map\", \"google_trends_topics_list\",\"google_trends_queries_list\"
default value:\"google_trends_graph\"google_trends_topics_list and google_trends_queries_list items, specify no more than 1 keyword in the keywords field"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"location_name": "United States",
"date_from": "2019-01-01",
"date_to": "2020-01-01",
"type": "youtube",
"category_code": 3,
"keywords": [
"rugby",
"cricket"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsExploreLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsExploreLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreLiveResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to the Google Trends results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataGoogleTrendsItem"
}
]
},
"description": "items on the Google Trends page"
}
}
},
"Response463397119C53_BaseKeywordDataGoogleTrendsItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"position": {
"type": [
"integer",
"null"
],
"description": "the alignment of the element in Google Trends
can take the following values: 1, 2, 3, 4, etc."
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in Google Trends"
},
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "relevant keywords
the data included in the google_trends_graph element is based on the keywords listed in this array"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"google_trends_graph": "#/components/schemas/Response463397119C53_GoogleTrendsGoogleTrendsGraphElementItem",
"google_trends_map": "#/components/schemas/Response463397119C53_GoogleTrendsGoogleTrendsMapElementItem",
"google_trends_queries_list": "#/components/schemas/Response463397119C53_GoogleTrendsGoogleTrendsQueriesListElementItem",
"google_trends_topics_list": "#/components/schemas/Response463397119C53_GoogleTrendsGoogleTrendsTopicsListElementItem"
}
}
},
"Response463397119C53_GoogleTrendsGoogleTrendsGraphElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataGoogleTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"data": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TrendsGraphDataInfo"
}
]
},
"description": "Google Trends data for the specified parameters"
},
"averages": {
"type": "array",
"items": {
"type": [
"number",
"null"
],
"format": "double"
}
}
}
}
]
},
"Response463397119C53_TrendsGraphDataInfo": {
"type": "object",
"properties": {
"date_from": {
"type": [
"string",
"null"
],
"description": "start date of the corresponding time range
in the UTC format: \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "end date of the corresponding time range
in the UTC format: \"yyyy-mm-dd\""
},
"timestamp": {
"type": [
"integer",
"null"
],
"description": "a point in time in the Unix time format"
},
"missing_data": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the data is unavailable
if true the data on the graph in the Google Trends interface is missing and thus labelled with a dotted line"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": [
"number",
"null"
]
},
"description": "relative keyword popularity rate at a specific timestamp
represents the keyword popularity rate over the given time range
if you specify more than one keyword, the values will be averaged to the highest value across all specified keywords
a value of 100 is the peak popularity for the term. A value of 50 means that the term is half as popular. A score of 0 means there was not enough data for this term"
}
}
},
"Response463397119C53_GoogleTrendsGoogleTrendsMapElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataGoogleTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"data": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TrendsMapDataInfo"
}
]
},
"description": "Google Trends data from the corresponding item"
}
}
}
]
},
"Response463397119C53_TrendsMapDataInfo": {
"type": "object",
"properties": {
"geo_id": {
"type": [
"string",
"null"
],
"description": "Google Trends location identifier
you can use this field for matching obtained results with location parameters specified in the request
example:US-NY"
},
"geo_name": {
"type": [
"string",
"null"
],
"description": "Google Trends location name
you can use this field for matching obtained results with location parameters specified in the request"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": [
"number",
"null"
]
},
"description": "relative keyword popularity rate in a given location
represents the location-specific keyword popularity rate over the given time range
if you specify more than one keyword, the values will be averaged to the highest value across all specified keywords
a value of 100 is the peak popularity for the term
a value of 50 means that the term is half as popular
a value of 0 means there was not enough data for this term"
},
"max_value_index": {
"type": [
"integer",
"null"
],
"description": "max value among comparable terms
represents the maximum value if you specified more than two keywords in a POST array
if you specified only one keyword, the value will be null"
}
}
},
"Response463397119C53_GoogleTrendsGoogleTrendsQueriesListElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataGoogleTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ListDataInfo"
}
],
"description": "Google Trends data from the corresponding item"
}
}
}
]
},
"Response463397119C53_ListDataInfo": {
"type": "object",
"properties": {
"top": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "the most popular related topics
represents the list of the most popular related topics"
},
"rising": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "emerging related topics
represents the list of related topics with the biggest increase in search frequency since the last time period"
}
}
},
"Response463397119C53_GoogleTrendsGoogleTrendsTopicsListElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataGoogleTrendsItem"
}
]
},
{
"type": "object",
"properties": {
"data": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ListDataInfo"
}
],
"description": "Google Trends data from the corresponding item"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreTaskGetResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsExploreTaskGetTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreTaskGetTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsExploreTaskGetResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreTaskGetResultInfo": {
"type": "object",
"properties": {
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array
if there is no data, then the value is_nulln"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array
if there is no data, then the value is_nulln"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to the Google Trends results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseKeywordDataGoogleTrendsItem"
}
]
},
"description": "items on the Google Trends page"
}
}
},
"Provider463397119C53_KeywordsDataGoogleTrendsExploreTaskPostRequestInfo": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field if you don't specify `category_code`
the maximum number of keywords you can specify: 5
the maximum number of characters you can specify in a keyword: 100
the minimum number of characters must be greater than 1
comma characters (,) in the specified keywords will be unset and ignored< > | \" - + = ~ ! : * ( ) [ ] { }google_trends_topics_list and google_trends_queries_list items, specify no more than 1 keywordkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_code
you can use this field as an array to set several locations, each corresponding to a specific keyword - learn more;
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/locations
example:United Kingdom"
},
"location_code": {
"type": [
"string",
"null"
],
"description": "search engine location code
optional field
if you don't use this field, you will recieve global results
if you use this field, you don't need to specify location_name
you can use this field as an array to set several locations, each corresponding to a specific keyword - learn more;
you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/locations
example:2840"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
default value: English
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
default value: en
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_trends/languages
example:en"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"category_code": {
"type": "integer",
"description": "google trends search category
required field if you don't specify `keywords`
if you don't specify `keywords`, the value of this field must be greater than `0`
if you specify `keywords` and don't specify this field, the 0 value will be applied by default and the search will be carried out across all available categories
you can receive the list of available categories with their category_code by making a separate request to the https://api.dataforseo.com/v3/keywords_data/google_trends/categories"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
if you don't specify this field, the current day and month of the preceding year will be used by default
minimal value for the web type: 2004-01-01
minimal value for other types: 2008-01-01
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"time_range": {
"type": [
"string",
"null"
],
"description": "preset time ranges
optional field
if you specify date_from or date_to parameters, this field will be ignored when setting a task
possible values for all type parameters:past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years
possible values for web only:2004_present
possible values for news, youtube, images, froogle:2008_present"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "types of items returned
optional field
to speed up the execution of the request, specify one item at a time;
possible values:\"google_trends_graph\", \"google_trends_map\", \"google_trends_topics_list\",\"google_trends_queries_list\"
default value:\"google_trends_graph\"google_trends_topics_list and google_trends_queries_list items, specify no more than 1 keyword in the keywords field"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"date_from": "2019-01-01",
"date_to": "2020-01-01",
"type": "youtube",
"category_code": 3,
"keywords": [
"seo api",
"rank api"
]
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KeywordsDataGoogleTrendsExploreTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_KeywordsDataGoogleTrendsExploreTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results
in this case, the value will be null"
}
}
}
]
},
"Provider463397119C53_MerchantAmazonAsinLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "product ID
required field
unique product identifier (ASIN) in Amazon
you can receive the asin parameter by making a separate request to the Amazon Products endpoint"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:HA1,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/locations
example:9045969"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United Kingdom)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_GB"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.com, amazon.co.uk, amazon.fr, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"asin": "B0756FCPPN"
}
]
},
"Response463397119C53_MerchantAmazonAsinLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN received in a POST array
the unique product identifier in Amazon (ASIN) received in a POST array
learn more about the identified in this help center guide"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "Amazon domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found on Amazon
contains types of all search results (items) found in the returned SERP
possible item types:amazon_product_info"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonProductInfo"
}
]
},
"description": "Amazon product info items"
}
}
},
"Response463397119C53_AmazonProductInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank
absolute position among all the elements in the response array"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Amazon SERP
possible values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"details": {
"type": [
"string",
"null"
],
"description": "product specs and other details"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "the URL of the product image"
},
"author": {
"type": [
"string",
"null"
],
"description": "product brand name"
},
"data_asin": {
"type": [
"string",
"null"
],
"description": "ASIN of the product received in a POST array"
},
"parent_asin": {
"type": [
"string",
"null"
],
"description": "parent ASIN of the product"
},
"product_asins": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "ASINs of all found product modifications"
},
"price_from": {
"type": [
"number",
"null"
],
"description": "the lower limit of the product price range
example:49.98"
},
"price_to": {
"type": [
"number",
"null"
],
"description": "the upper limit of the product price range
example:384.99"
},
"percentage_discount": {
"type": [
"string",
"null"
],
"description": "value of the percentage discount"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"is_amazon_choice": {
"type": [
"boolean",
"null"
],
"description": "\"Amazon's choice\" label
if the value is true, the product is marked with the \"Amazon's choice\" label"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating info"
},
"is_newer_model_available": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the newer model of the product is available"
},
"is_prime_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a product has an Amazon Prime Video label
if true, specified product is a part of Amazon Prime Video service"
},
"applicable_vouchers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonApplicableVouchersItem"
}
]
},
"description": "array of objects containing information about applicable vouchers"
},
"newer_model": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_NewerModel"
}
],
"description": "information about the newer model of the product"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Categories"
}
]
},
"description": "contains related product categories"
},
"product_information": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationElementItem"
}
]
},
"description": "contains related product information"
},
"product_images_list": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains URLs for all images of the product displayed on the left side of the main image"
},
"product_videos_list": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains URLs for all videos of the product displayed on the right side of the main video"
},
"description": {
"type": [
"string",
"null"
],
"description": "contains description of the product"
},
"is_available": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the product is available for ordering
if the value is true, the product can be ordered"
},
"top_local_reviews": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonReviewItem"
}
]
},
"description": "array of objects with top reviews from target location"
},
"top_global_reviews": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonReviewItem"
}
]
},
"description": "array of objects with top reviews from around the world"
}
}
},
"Response463397119C53_RatingElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Google Shopping SERP
possible values:left, right"
},
"rating_type": {
"type": [
"string",
"null"
],
"description": "the type of rating
here you can find the following elements: Max5, Percents, CustomMax"
},
"value": {
"type": [
"number",
"null"
],
"description": "value of the rating"
},
"votes_count": {
"type": [
"integer",
"null"
],
"description": "the amount of feedback",
"format": "int64"
},
"rating_max": {
"type": [
"integer",
"null"
],
"description": "the maximum value for a rating_type"
}
}
},
"Response463397119C53_AmazonApplicableVouchersItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"text": {
"type": [
"string",
"null"
],
"description": "text of the voucher"
},
"fixed_discount": {
"type": [
"number",
"null"
],
"description": "value of the fixed discount"
},
"fixed_discount_currency": {
"type": [
"string",
"null"
],
"description": "currency code of the fixed discount"
},
"percentage_discount": {
"type": [
"number",
"null"
],
"description": "value of the percentage discount
if the discount is fixed, the value will be null"
},
"important_details": {
"type": [
"string",
"null"
],
"description": "important details about the terms of discount vouchers"
}
}
},
"Response463397119C53_NewerModel": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"newer_model_asin": {
"type": [
"string",
"null"
],
"description": "ASIN of the newer product model"
}
}
},
"Response463397119C53_Categories": {
"type": "object",
"properties": {
"category": {
"type": [
"string",
"null"
],
"description": "product category name"
},
"url": {
"type": [
"string",
"null"
],
"description": "product category URL
indicates the browse path on Amazon with the unique browse node ID (product category ID on Amazon)"
}
}
},
"Response463397119C53_BaseMerchantAmazonProductInformationElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"section_name": {
"type": [
"string",
"null"
],
"description": "name of the section related to product information specified in the contents"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"product_information_details_item": "#/components/schemas/Response463397119C53_ProductInformationProductInformationDetailsItem",
"product_information_text_item": "#/components/schemas/Response463397119C53_ProductInformationProductInformationTextItem",
"product_information_extended_item": "#/components/schemas/Response463397119C53_ProductInformationProductInformationExtendedItem"
}
}
},
"Response463397119C53_ProductInformationProductInformationDetailsItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationElementItem"
}
]
},
{
"type": "object",
"properties": {
"body": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "contains information specified about the product within the section_name"
}
}
}
]
},
"Response463397119C53_ProductInformationProductInformationTextItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "text specified under the given title within the section_name"
}
}
}
]
},
"Response463397119C53_ProductInformationProductInformationExtendedItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationElementItem"
}
]
},
{
"type": "object",
"properties": {
"contents": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ProductInformationRows"
}
]
},
"description": "contains information specified about the product within the section_name"
}
}
}
]
},
"Response463397119C53_ProductInformationRows": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title under which related product information appears on the Amazon product page"
},
"rows": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationRowElementItem"
}
]
},
"description": "rows containing related product information"
}
}
},
"Response463397119C53_BaseMerchantAmazonProductInformationRowElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"product_information_image_row": "#/components/schemas/Response463397119C53_ProductInformationRowProductInformationImageRowElementItem",
"product_information_text_row": "#/components/schemas/Response463397119C53_ProductInformationRowProductInformationTextRowElementItem"
}
}
},
"Response463397119C53_ProductInformationRowProductInformationImageRowElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationRowElementItem"
}
]
},
{
"type": "object",
"properties": {
"alt": {
"type": [
"string",
"null"
],
"description": "alternative text of the related product image"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the image"
}
}
}
]
},
"Response463397119C53_ProductInformationRowProductInformationTextRowElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonProductInformationRowElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "text of the voucher"
}
}
}
]
},
"Response463397119C53_AmazonReviewItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank among all the listed reviews
absolute position among all reviews on the list"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the review in SERP
can take the following values: right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the review has the \"Verified Purchase\" mark"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the review"
},
"helpful_votes": {
"type": [
"string",
"null"
],
"description": "helpful votes count
number of users who clicked on the 'Helpful\" button under the review text"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the product submitted by the reviewer"
},
"videos": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_VideoElement"
}
]
},
"description": "videos of the product submitted by the reviewer"
},
"user_profile": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_UserProfileInfo"
}
],
"description": "user profile of the reviewer"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the review"
},
"url": {
"type": [
"string",
"null"
]
},
"review_text": {
"type": [
"string",
"null"
],
"description": "content of the review"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "date and time when the review was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example:2019-11-15 12:57:46 +00:00"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the rating score submitted by the reviewer"
}
}
},
"Response463397119C53_UserProfileInfo": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"avatar": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant url"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"locations": {
"type": [
"string",
"null"
]
}
}
},
"Provider463397119C53_MerchantAmazonAsinLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "product ID
required field
unique product identifier (ASIN) in Amazon
you can receive the asin parameter by making a separate request to the Amazon Products endpoint"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:HA1,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/locations
example:9045969"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United Kingdom)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_GB"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.com, amazon.co.uk, amazon.fr, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"asin": "B0756FCPPN"
}
]
},
"Response463397119C53_MerchantAmazonAsinLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinLiveHtmlResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Response463397119C53_MerchantAmazonAsinTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN received in a POST array
the unique product identifier in Amazon (ASIN) received in a POST array
learn more about the identified in this help center guide"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "Amazon domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found on Amazon
contains types of all search results (items) found in the returned SERP
possible item types:amazon_product_info"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonProductInfo"
}
]
},
"description": "Amazon product info items"
}
}
},
"Response463397119C53_MerchantAmazonAsinTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN received in a POST array"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Provider463397119C53_MerchantAmazonAsinTaskPostRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "product ID
required field
unique product identifier (ASIN) in Amazon
you can receive the asin parameter by making a separate request to the Amazon Products endpoint"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:HA1,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/locations
example:9045969n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United Kingdom)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_GB"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.com, amazon.co.uk, amazon.fr, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonAsinTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonAsinTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
can take the following values: shopping"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
]
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Amazon ASIN Advanced task"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Amazon ASIN HTML task"
}
}
},
"Response463397119C53_MerchantAmazonLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_MerchantAmazonLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_name_parent": {
"type": [
"string",
"null"
],
"description": "the name of the superordinate location
example:\"location_code\": 9041134,"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Provider463397119C53_MerchantAmazonProductsLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
\"location_name\": \"90290,California,United States\",
\"location_name_parent\": \"California,United States\"
required field
you can specify up to 700 characters in this field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://www.amazon.com/s/?field-keywords=shoes&language=en_US"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:HA1,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/locations
example:9045969"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United Kingdom)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_GB"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.com, amazon.co.uk, amazon.fr, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be retrieved from the Amazon results page
default value: 100
max value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
max value: 7
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"department": {
"type": [
"string",
"null"
],
"description": "amazon product department
optional field
specify one of the following amazon departments for extracting product listings:\"Arts & Crafts\", \"Automotive\", \"Baby\", \"Beauty & Personal Care\", \"Books\", \"Computers\", \"Digital Music\", \"Electronics\", \"Kindle Store\", \"Prime Video\", \"Women's Fashion\", \"Men's Fashion\", \"Girls' Fashion\", \"Boys' Fashion\", \"Deals\", \"Health & Household\", \"Home & Kitchen\", \"Industrial & Scientific\", \"Luggage\", \"Movies & TV\", \"Music, CDs & Vinyl\", \"Pet Supplies\", \"Software\", \"Sports & Outdoors\", \"Tools & Home Improvement\", \"Toys & Games\", \"Video Games\""
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
you can use the following Amazon search URL parameters for customizing the search
example:&low-price=52 - search for products that cost more than 52 USD;&high-price=45 - search for products that cost less than 45 USD;&sort=relevancerank - sort results by relevance;&sort=featured-rank - sort results by featured products;&sort=price-asc-rank - sort by ascending price;&sort=price-desc-rank - sort by descending price;&sort=review-rank - sort by the average customer reviews value;&sort=date-desc-rank - sort by the newest arrival
Note that search_param values will be ignored if any of the following parameters is used: price_min, price_max, sort_by"
},
"price_min": {
"type": [
"integer",
"null"
],
"description": "minimum product price
optional field
minimum price of the returned products listed on Amazon for the specified query
example:5
Note: if you specify price_min, the search_param parameter will be ignored"
},
"price_max": {
"type": [
"integer",
"null"
],
"description": "maximum product price
optional field
maximum price of the returned products listed on Amazon for the specified query
example:100
Note: if you specify price_max, the search_param parameter will be ignored"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting rules
optional field
the following sorting rules are supported:relevance, price_low_to_high, price_high_to_low, featured, avg_customer_review, newest_arrival
example:sort_by:\"relevance\"
Note: if you specify sort_by, the search_param parameter will be ignored"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"keyword": "shoes"
}
]
},
"Response463397119C53_MerchantAmazonProductsLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in Amazon SERP
contains types of all search results (items) found in the returned SERP
possible item types:amazon_serp, amazon_paid, editorial_recommendations, top_rated_from_our_brands, related_searches"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "search engine results count",
"format": "int64"
},
"categories": {
"type": [
"object",
"null"
],
"description": "amazon product departments and subcategories"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
"description": "Amazon product items"
}
}
},
"Response463397119C53_BaseMerchantAmazonElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements found in Amazon SERP"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"amazon_paid": "#/components/schemas/Response463397119C53_MerchantAmazonPaidSerpElementItem",
"amazon_serp": "#/components/schemas/Response463397119C53_MerchantAmazonSerpSerpElementItem",
"editorial_recommendations": "#/components/schemas/Response463397119C53_MerchantEditorialRecommendationsSerpElementItem",
"related_searches": "#/components/schemas/Response463397119C53_MerchantRelatedSearchesSerpElementItem",
"top_rated_from_our_brands": "#/components/schemas/Response463397119C53_MerchantTopRatedFromOurBrandsSerpElementItem"
}
}
},
"Response463397119C53_MerchantAmazonPaidSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "Amazon domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "the URL of the product page"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the product image featured in the results"
},
"bought_past_month": {
"type": [
"integer",
"null"
],
"description": "number of product purchases in the past month"
},
"price_from": {
"type": [
"number",
"null"
],
"description": "the regular price of a product
example:49.98"
},
"price_to": {
"type": [
"number",
"null"
],
"description": "the upper limit of the product price range
example:384.99"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"special_offers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "special offer details
contains special offer details, including coupon and Subscribe & Save discounts"
},
"data_asin": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Amazon
note that there is no full list of possible values as the data_asin is a dynamic value assigned by Amazon
example:B07G82D89J"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating info"
},
"is_amazon_choice": {
"type": [
"boolean",
"null"
],
"description": "\"Amazon's choice\" label
if the value is true, the product is marked with the \"Amazon's choice\" label"
},
"is_best_seller": {
"type": [
"boolean",
"null"
],
"description": "\"Best Seller\" label
if the value is true, the product is marked with the \"Best Seller\" label"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonDeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"labels": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "product labels
array containing an object with main Amazon labels’ information
if the product contains no labels, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSerpSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "Amazon domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "the URL of the product page"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the product image featured in the results"
},
"bought_past_month": {
"type": [
"integer",
"null"
],
"description": "number of product purchases in the past month"
},
"price_from": {
"type": [
"number",
"null"
],
"description": "the regular price of a product
example:49.98"
},
"price_to": {
"type": [
"number",
"null"
],
"description": "the upper limit of the product price range
example:384.99"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"special_offers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "special offer details
contains special offer details, including coupon and Subscribe & Save discounts"
},
"data_asin": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Amazon
note that there is no full list of possible values as the data_asin is a dynamic value assigned by Amazon
example:B07G82D89J"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating info"
},
"is_amazon_choice": {
"type": [
"boolean",
"null"
],
"description": "\"Amazon's choice\" label
if the value is true, the product is marked with the \"Amazon's choice\" label"
},
"is_best_seller": {
"type": [
"boolean",
"null"
],
"description": "\"Best Seller\" label
if the value is true, the product is marked with the \"Best Seller\" label"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonDeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"labels": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "product labels
array containing an object with main Amazon labels’ information
if the product contains no labels, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantEditorialRecommendationsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
{
"type": "object",
"properties": {
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Amazon SERP
possible values:left, right"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonSerpElement"
}
]
},
"description": "Amazon product items"
}
}
}
]
},
"Response463397119C53_AmazonSerpElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "Amazon domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "the URL of the product page"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the product image featured in the results"
},
"bought_past_month": {
"type": [
"integer",
"null"
],
"description": "number of product purchases in the past month"
},
"price_from": {
"type": [
"number",
"null"
],
"description": "the regular price of a product
example:49.98"
},
"price_to": {
"type": [
"number",
"null"
],
"description": "the upper limit of the product price range
example:384.99"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"special_offers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "special offer details
contains special offer details, including coupon and Subscribe & Save discounts"
},
"data_asin": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Amazon
note that there is no full list of possible values as the data_asin is a dynamic value assigned by Amazon
example:B07G82D89J"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating info"
},
"is_amazon_choice": {
"type": [
"boolean",
"null"
],
"description": "\"Amazon's choice\" label
if the value is true, the product is marked with the \"Amazon's choice\" label"
},
"is_best_seller": {
"type": [
"boolean",
"null"
],
"description": "\"Best Seller\" label
if the value is true, the product is marked with the \"Best Seller\" label"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonDeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"labels": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "product labels
array containing an object with main Amazon labels’ information
if the product contains no labels, the value will be null"
}
}
},
"Response463397119C53_MerchantRelatedSearchesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
{
"type": "object",
"properties": {
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Amazon SERP
possible values:left, right"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedSearchesElement"
}
]
},
"description": "Amazon product items"
}
}
}
]
},
"Response463397119C53_RelatedSearchesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "the URL of the product page"
},
"image_alt": {
"type": [
"string",
"null"
],
"description": "the alt tag of the product image featured in the results"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the product image featured in the results"
}
}
},
"Response463397119C53_MerchantTopRatedFromOurBrandsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
{
"type": "object",
"properties": {
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Amazon SERP
possible values:left, right"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonSerpElement"
}
]
},
"description": "Amazon product items"
}
}
}
]
},
"Provider463397119C53_MerchantAmazonProductsLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in this field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://www.amazon.com/s/?field-keywords=shoes&language=en_US"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:HA1,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/locations
example:9045969"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United Kingdom)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_GB"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.com, amazon.co.uk, amazon.fr, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be retrieved from the Amazon results page
default value: 100
max value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
max value: 7
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"department": {
"type": [
"string",
"null"
],
"description": "amazon product department
optional field
specify one of the following amazon departments for extracting product listings:\"Arts & Crafts\", \"Automotive\", \"Baby\", \"Beauty & Personal Care\", \"Books\", \"Computers\", \"Digital Music\", \"Electronics\", \"Kindle Store\", \"Prime Video\", \"Women's Fashion\", \"Men's Fashion\", \"Girls' Fashion\", \"Boys' Fashion\", \"Deals\", \"Health & Household\", \"Home & Kitchen\", \"Industrial & Scientific\", \"Luggage\", \"Movies & TV\", \"Music, CDs & Vinyl\", \"Pet Supplies\", \"Software\", \"Sports & Outdoors\", \"Tools & Home Improvement\", \"Toys & Games\", \"Video Games\""
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
you can use the following Amazon search URL parameters for customizing the search
example:&low-price=52 - search for products that cost more than 52 USD;&high-price=45 - search for products that cost less than 45 USD;&sort=relevancerank - sort results by relevance;&sort=featured-rank - sort results by featured products;&sort=price-asc-rank - sort by ascending price;&sort=price-desc-rank - sort by descending price;&sort=review-rank - sort by the average customer reviews value;&sort=date-desc-rank - sort by the newest arrival
Note that search_param values will be ignored if any of the following parameters is used: price_min, price_max, sort_by"
},
"price_min": {
"type": [
"integer",
"null"
],
"description": "minimum product price
optional field
minimum price of the returned products listed on Amazon for the specified query
example:5
Note: if you specify price_min, the search_param parameter will be ignored"
},
"price_max": {
"type": [
"integer",
"null"
],
"description": "maximum product price
optional field
maximum price of the returned products listed on Amazon for the specified query
example:100
Note: if you specify price_max, the search_param parameter will be ignored"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting rules
optional field
the following sorting rules are supported:relevance, price_low_to_high, price_high_to_low, featured, avg_customer_review, newest_arrival
example:sort_by:\"relevance\"
Note: if you specify sort_by, the search_param parameter will be ignored"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"keyword": "shoes"
}
]
},
"Response463397119C53_MerchantAmazonProductsLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Response463397119C53_MerchantAmazonProductsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in Amazon SERP
contains types of all search results (items) found in the returned SERP
possible item types:amazon_serp, amazon_paid, editorial_recommendations, top_rated_from_our_brands, related_searches"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "search engine results count",
"format": "int64"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "amazon product departments and subcategories"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonElementItem"
}
]
},
"description": "Amazon product items within the editorial_recommendations element"
}
}
},
"Response463397119C53_MerchantAmazonProductsTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "HTML pages and related data"
}
}
},
"Provider463397119C53_MerchantAmazonProductsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in this field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://www.amazon.com/s/?field-keywords=shoes&language=en_US"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with their location_name parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:HA1,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with their location_code parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/locations
example:9045969"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name parameters by making a separate request to thehttps://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United Kingdom)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_parameters by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_GB"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.com, amazon.co.uk, amazon.fr, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be retrieved from the Amazon results page
default value: 100
max value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
max value: 7
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"department": {
"type": [
"string",
"null"
],
"description": "amazon product department
optional field
specify one of the following amazon departments for extracting product listings:\"Arts & Crafts\", \"Automotive\", \"Baby\", \"Beauty & Personal Care\", \"Books\", \"Computers\", \"Digital Music\", \"Electronics\", \"Kindle Store\", \"Prime Video\", \"Women's Fashion\", \"Men's Fashion\", \"Girls' Fashion\", \"Boys' Fashion\", \"Deals\", \"Health & Household\", \"Home & Kitchen\", \"Industrial & Scientific\", \"Luggage\", \"Movies & TV\", \"Music, CDs & Vinyl\", \"Pet Supplies\", \"Software\", \"Sports & Outdoors\", \"Tools & Home Improvement\", \"Toys & Games\", \"Video Games\""
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
you can use the following Amazon search URL parameters for customizing the search
example:&low-price=52 - search for products that cost more than 52 USD;&high-price=45 - search for products that cost less than 45 USD;&sort=relevancerank - sort results by relevance;&sort=featured-rank - sort results by featured products;&sort=price-asc-rank - sort by ascending price;&sort=price-desc-rank - sort by descending price;&sort=review-rank - sort by the average customer reviews value;&sort=date-desc-rank - sort by the newest arrival
Note that search_param values will be ignored if any of the following parameters is used: price_min, price_max, sort_by"
},
"price_min": {
"type": [
"integer",
"null"
],
"description": "minimum product price
optional field
minimum price of the returned products listed on Amazon for the specified query
example:5
Note: if you specify price_min, the search_param parameter will be ignored"
},
"price_max": {
"type": [
"integer",
"null"
],
"description": "maximum product price
optional field
maximum price of the returned products listed on Amazon for the specified query
example:100
Note: if you specify price_max, the search_param parameter will be ignored"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting rules
optional field
the following sorting rules are supported:relevance, price_low_to_high, price_high_to_low, featured, avg_customer_review, newest_arrival
example:sort_by:\"relevance\"
Note: if you specify sort_by, the search_param parameter will be ignored"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonProductsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonProductsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
can take the following values: organic"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Amazon Products Advanced task"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Amazon Products HTML task"
}
}
},
"Provider463397119C53_MerchantAmazonSellersLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "unique product identifier on Amazon
required field
you can get this value making a separate request to the Amazon Products endpoint
note that there is no full list of possible values as the asin values is a dynamic value assigned by Amazon
example:B085RFFC9Q
learn more about the identifier in this help center guide"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Amazon locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Amazon locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Amazon languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United States)"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Amazon languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_US"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.co.uk, amazon.com.au, amazon.de, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"asin": "B07D528W98"
}
]
},
"Response463397119C53_MerchantAmazonSellersLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "asin received in a POST array
learn more about ASINs in this help center guide"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain received in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code received in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code received in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure the provided results are accurate"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title
title of the product relevant to the asin received in a POST array"
},
"image": {
"type": [
"string",
"null"
],
"description": "product image url
image URL of the product relevant to the asin received in a POST array"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in Amazon Sellers SERP
contains types of all search results (items) found in the returned SERP
possible item types:amazon_seller_main_item, amazon_seller_item"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonSellersElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Response463397119C53_BaseMerchantAmazonSellersElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements found in Amazon Sellers SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "alignment of the element in SERP
possible values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "XPath of the element"
},
"seller_name": {
"type": [
"string",
"null"
],
"description": "business name of the seller"
},
"seller_url": {
"type": [
"string",
"null"
],
"description": "url forwarding to the seller's page on Amazon"
},
"ships_from": {
"type": [
"string",
"null"
],
"description": "sender company name"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "product pricing details
if there are no details, the value will be null"
},
"percentage_discount": {
"type": [
"number",
"null"
],
"description": "value of the percentage discount"
},
"applicable_vouchers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonApplicableVouchersItem"
}
]
},
"description": "array of objects containing information about applicable vouchers"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "seller rating details
seller popularity rate based on customer reviews"
},
"condition": {
"type": [
"string",
"null"
],
"description": "product condition
condition of the product offered by the seller"
},
"condition_description": {
"type": [
"string",
"null"
],
"description": "product condition details
expanded details on the condition of the product offered by the seller"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonDeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"amazon_seller_main_item": "#/components/schemas/Response463397119C53_MerchantAmazonSellerMainItemSerpElementItem",
"amazon_seller_item": "#/components/schemas/Response463397119C53_MerchantAmazonSellerItemSerpElementItem"
}
}
},
"Response463397119C53_MerchantAmazonSellerMainItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonSellersElementItem"
}
]
},
{
"type": "object"
}
]
},
"Response463397119C53_MerchantAmazonSellerItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonSellersElementItem"
}
]
},
{
"type": "object"
}
]
},
"Provider463397119C53_MerchantAmazonSellersLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "unique product identifier on Amazon
required field
you can get this value making a separate request to the Amazon Products endpoint
note that there is no full list of possible values as the asin values is a dynamic value assigned by Amazon
example:B085RFFC9Q
learn more about the identifier in this help center guide"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Amazon locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Amazon locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Amazon languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United States)"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Amazon languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_US"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.co.uk, amazon.com.au, amazon.de, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en_US",
"location_code": 2840,
"asin": "B085RFFC9Q"
}
]
},
"Response463397119C53_MerchantAmazonSellersLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersLiveHtmlResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN received in a POST array "
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found on Amazon"
}
}
},
"Response463397119C53_MerchantAmazonSellersTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "asin received in a POST array
learn more about ASINs in this help center guide"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain received in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code received in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code received in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Amazon results
you can use it to make sure the provided results are accurate"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title
title of the product relevant to the asin received in a POST array"
},
"image": {
"type": [
"string",
"null"
],
"description": "product image url
image URL of the product relevant to the asin received in a POST array"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in Amazon Sellers SERP
contains types of all search results (items) found in the returned SERP
possible item types:amazon_seller_main_item, amazon_seller_item"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantAmazonSellersElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Response463397119C53_MerchantAmazonSellersTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"asin": {
"type": [
"string",
"null"
],
"description": "ASIN received in a POST array "
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found on Amazon"
}
}
},
"Provider463397119C53_MerchantAmazonSellersTaskPostRequestInfo": {
"type": "object",
"properties": {
"asin": {
"type": "string",
"description": "unique product identifier on Amazon
required field
you can get this value making a separate request to the Amazon Products endpoint
note that there is no full list of possible values as the asin values is a dynamic value assigned by Amazon
example:B085RFFC9Q
learn more about the identifier in this help center guide"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Amazon locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Amazon locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Amazon languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:English (United States)"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Amazon languages with their language_code by making a separate request to the https://api.dataforseo.com/v3/merchant/amazon/languages
example:en_US"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:amazon.co.uk, amazon.com.au, amazon.de, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantAmazonSellersTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantAmazonSellersTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of Amazon Sellers Advanced task"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of Amazon Sellers HTML task"
}
}
},
"Response463397119C53_MerchantGoogleLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_MerchantGoogleLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_name_parent": {
"type": [
"string",
"null"
],
"description": "the name of the superordinate location
example:
`\"location_name\": \"Arkansas,United States\"`,
`\"location_name_parent\": \"United States\"`"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Response463397119C53_MerchantGoogleProductInfoTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductInfoTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductInfoTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"product_id": {
"type": [
"string",
"null"
],
"description": "product ID in a POST array
learn more about the parameter in this help center guide"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the format: “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes”
example:2019-11-15 12:57:46 +00:00"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of items found on the product specification page
possible item types:product_info_element"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ProductInfoElement"
}
]
},
"description": "items on the product page
contains all product attributes and related data listed on the product page"
}
}
},
"Response463397119C53_ProductInfoElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank on the product specification page
absolute position among all the elements found on the product specification page"
},
"position": {
"type": [
"string",
"null"
],
"description": "alignment of the element on the product specification page
can take the following values:right, left"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "product_id received in a POST array
ilearn more about the parameter in this help center guide"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the product"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the product"
},
"url": {
"type": [
"string",
"null"
],
"description": "product url
url of the product on Google Shopping"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product images
contains urls to product images"
},
"features": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "product features
contains snippets with the description of product features"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating
the popularity rate based on reviews"
},
"seller_reviews_count": {
"type": [
"integer",
"null"
],
"description": "number of seller reviews
number of reviews on the product seller's account",
"format": "int64"
},
"data_docid": {
"type": [
"string",
"null"
],
"description": "unique identifier of the SERP data element
note that there is no full list of possible values as the data_docid is a dynamic value assigned by Google
example:17363035694596624076"
},
"gid": {
"type": [
"string",
"null"
],
"description": "global product identifier on Google Shopping
note that there is no full list of possible values as the gid is a dynamic value assigned by Google
if there are no values, you will get null
example:4702526954592161872
learn more about gid in this help center guide"
},
"specifications": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ShoppingSpecification"
}
]
},
"description": "product specifications
contains all product attributes and related data listed on the product specification page"
},
"sellers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ProductSeller"
}
]
},
"description": "sellers of the product
number of reviews on the product seller's account"
},
"variations": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ProductVariation"
}
]
},
"description": "variations of the product
contains brief information about different product variations"
}
}
},
"Response463397119C53_ShoppingSpecification": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"block_name": {
"type": [
"string",
"null"
],
"description": "name of the block of product attributes
indicates the name of the product specification section in which the related element is listed"
},
"specification_name": {
"type": [
"string",
"null"
],
"description": "product attribute
attribute name of the product data specification"
},
"specification_value": {
"type": [
"string",
"null"
],
"description": "content of the specification"
}
}
},
"Response463397119C53_ProductSeller": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "seller url
url of the page where the product is sold"
},
"seller_rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "rating of the seller"
},
"seller_review_count": {
"type": [
"integer",
"null"
],
"description": "number of seller reviews\nnumber of reviews on the product seller’s account"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "product price
product price details on the seller's website"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DeliveryInfo"
}
],
"description": "delivery information
product delivery information"
},
"product_availability": {
"type": [
"string",
"null"
],
"description": "product availability information
can take the following values: in_stock, limited_stock, out_of_stock, backordered, pre_order_available, on_display_to_order"
}
}
},
"Response463397119C53_DeliveryInfo": {
"type": "object",
"properties": {
"delivery_date_from": {
"type": [
"string",
"null"
],
"description": "earliest delivery date
the earliest date when the product can be shipped, in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00"
},
"delivery_date_to": {
"type": [
"string",
"null"
],
"description": "latest delivery date
the latest date when the product can be delivered, in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00"
},
"fastest_delivery_date_from": {
"type": [
"string",
"null"
],
"description": "earliest free delivery date
the earliest date when the product can be delivered with a fast delivery option, in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00"
},
"fastest_delivery_date_to": {
"type": [
"string",
"null"
],
"description": "latest free delivery date
the latest date when the product can be delivered with a fast delivery option, in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00"
},
"delivery_message": {
"type": [
"string",
"null"
],
"description": "delivery information
message accompanying the delivery information as posted by the seller"
},
"delivery_price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price for the delivery
price of the delivery based on the location you specified in the POST request;
if free delivery is available, the value is null"
}
}
},
"Response463397119C53_ProductVariation": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "product ID in a POST array
learn more about the parameter in this help center guide"
},
"gid": {
"type": [
"string",
"null"
],
"description": "GID ID in a POST array
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": [
"string",
"null"
],
"description": "unique identifier of the SERP data element in the POST array"
},
"pvf": {
"type": [
"string",
"null"
],
"description": "product variation filter
used in the product variation URL as the identifier of the specific product variation"
},
"title": {
"type": [
"string",
"null"
],
"description": "name of the product seller"
},
"url": {
"type": [
"string",
"null"
],
"description": "product variation URL on Google Shopping"
},
"variation_category": {
"type": [
"string",
"null"
],
"description": "category of the product variation
example: \"Storage Capacity\""
}
}
},
"Provider463397119C53_MerchantGoogleProductInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "unique product identifier on Google Shopping
required field if data_docid or gid is not specified
we recommend specifying product_id together with data_docid and gid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:4485466949985702538
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": "string",
"description": "unique identifier of the SERP data element
required field if product_id or gid is not specified
we recommend specifying data_docid together with product_id and gid for optimal results;
you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint
example:13071766526042404278"
},
"gid": {
"type": "string",
"description": "global product identifier on Google Shopping
required field if product_id or data_docid is not specified
we recommend specifying gid together with product_id and data_docid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:4702526954592161872
learn more about the parameter in this help center guide"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Google Shopping languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:en"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:google.co.uk, google.com.au, google.de, etc."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductInfoTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductInfoTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductInfoTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
can take the following values: shopping_specifications"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
]
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Google Shopping Product Specifications Advanced task"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the Google Shopping Product Specifications HTML task
note: HTML is not available for this endpoint, the value will be null"
}
}
},
"Response463397119C53_MerchantGoogleProductsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Google Shopping results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in Google Shopping SERP
contains types of all search results (items) found in the returned SERP
possible item types:google_shopping_sponsored_carousel, google_shopping_paid, google_shopping_serp, google_shopping_carousel, related_searches"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem"
}
]
},
"description": "additional items present in the element
contains a list of related keywords;
if there are none, equals null"
}
}
},
"Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements found in Google Shopping SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "alignment of the element in SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "XPath of the element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"google_shopping_serp": "#/components/schemas/Response463397119C53_GoogleShoppingSerpElementItem",
"google_shopping_paid": "#/components/schemas/Response463397119C53_GoogleShoppingPaidElementItem",
"google_shopping_sponsored_carousel": "#/components/schemas/Response463397119C53_GoogleShoppingSponsoredCarouselElementItem",
"google_shopping_carousel": "#/components/schemas/Response463397119C53_GoogleShoppingCarouselElementItem",
"related_searches": "#/components/schemas/Response463397119C53_RelatedSearchesElementItem"
}
}
},
"Response463397119C53_GoogleShoppingSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the URL
domain of the URL where a special offer is posted
Note: this field is deprecated and will return null"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the product in Google Shopping SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL pointing at special offer page
URL where a special offer is posted
Note: this field is deprecated and will return null"
},
"shopping_url": {
"type": [
"string",
"null"
],
"description": "URL to the product page on Google Shopping"
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "tags assigned to the product"
},
"price": {
"type": [
"number",
"null"
],
"description": "product price
example:384.99"
},
"price_multiplier": {
"type": [
"integer",
"null"
],
"description": "price multiplier for instalment plan
indicates the number of months covered by the monthly payment for the product"
},
"old_price": {
"type": [
"number",
"null"
],
"description": "product old price
displayed if the product price has been changed
example:499"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Google Shopping
note that there is no full list of possible values as the product_id is a dynamic value assigned by Google
if there are no values, you will get null
example:4485466949985702538
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": [
"string",
"null"
],
"description": "unique identifier of the SERP data element
note that there is no full list of possible values as the data_docid is a dynamic value assigned by Google
example:17363035694596624076"
},
"seller": {
"type": [
"string",
"null"
],
"description": "name of the seller
the name of the company that placed a corresponding product on Google Shopping"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information about the result"
},
"additional_specifications": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "object containing additional url parameters
you can get more details about the product by using this object in the POST request to the Google Shopping Product Specification and Google Shopping Sellers endpoint"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "number of product reviews
indicates the number of reviews left by users on Google Shopping
if there are no values, you will get null",
"format": "int64"
},
"is_best_match": {
"type": [
"boolean",
"null"
],
"description": "\"best match\" label
if the value is true, the product is marked with the \"best match\" label
if there are no values, you will get null"
},
"product_rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating
the product popularity rate based on product reviews"
},
"shop_rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "shop rating
the popularity rate of the seller based on user reviews"
},
"product_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "URLs to the images of the product
the first URL in the array is the featured image of the product"
},
"shop_ad_aclk": {
"type": [
"string",
"null"
],
"description": "unique ad click referral parameter
using this parameter you can get a URL of the advertisement in Google Shopping Sellers Ad URL"
},
"gid": {
"type": [
"string",
"null"
],
"description": "global product identifier on Google Shopping
note that there is no full list of possible values as the gid is a dynamic value assigned by Google
if there are no values, you will get null
example:4702526954592161872
learn more about gid parameter in this help center guide"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"stores_count_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_StoresCountInfo"
}
],
"description": "stores count information
contains information about the number of stores that offer the same product"
}
}
}
]
},
"Response463397119C53_StoresCountInfo": {
"type": "object",
"properties": {
"count": {
"type": [
"integer",
"null"
],
"description": "number of stores that offer the product"
},
"displayed_text": {
"type": [
"string",
"null"
],
"description": "text displayed on the Google Shopping page"
},
"count_from_text": {
"type": [
"boolean",
"null"
],
"description": "whether the number of stores is taken from text
indicates whether the number of stores is taken from displayed_text;
if the API finds the exact number of stores in the HTML code of the Google Shopping page, this parameter is false;
if the API cannot find the number of stores in the HTML code of the page, it takes the number from the displayed_text;
in this case, the parameter is true"
}
}
},
"Response463397119C53_GoogleShoppingPaidElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the URL
domain of the URL where a special offer is posted
Note: this field is deprecated and will return null"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the product in Google Shopping SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL pointing at special offer page
URL where a special offer is posted
Note: this field is deprecated and will return null"
},
"shop_ad_aclk": {
"type": [
"string",
"null"
],
"description": "unique ad click referral parameter
using this parameter you can get a URL of the advertisement in Google Shopping Sellers Ad URL"
}
}
}
]
},
"Response463397119C53_GoogleShoppingSponsoredCarouselElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the special offer"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleShoppingSponsoredCarouselElement"
}
]
},
"description": "items in SERP"
}
}
}
]
},
"Response463397119C53_GoogleShoppingSponsoredCarouselElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "XPath of the element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "tags assigned to the product"
},
"seller": {
"type": [
"string",
"null"
],
"description": "name of the seller
the name of the company that placed a corresponding product on Google Shopping"
},
"price": {
"type": [
"number",
"null"
],
"description": "product price
example:384.99"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"product_rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating
the product popularity rate based on product reviews"
},
"product_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "URLs to the images of the product
the first URL in the array is the featured image of the product"
},
"shop_ad_aclk": {
"type": [
"string",
"null"
],
"description": "unique ad click referral parameter
using this parameter you can get a URL of the advertisement in Google Shopping Sellers Ad URL"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"special_offer_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpecialOfferInfo"
}
],
"description": "special offer from the seller
information on the special offer from the seller, including discount and coupon info"
}
}
},
"Response463397119C53_SpecialOfferInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "subtitle of the special offer"
},
"fixed_discount": {
"type": [
"number",
"null"
],
"description": "amount of the fixed discount",
"format": "int64"
},
"fixed_discount_currency": {
"type": [
"string",
"null"
],
"description": "currency of the fixed discount"
},
"percentage_discount": {
"type": [
"number",
"null"
],
"description": "percentage of the discount",
"format": "int64"
},
"coupon_code": {
"type": [
"string",
"null"
],
"description": "code of coupon discount"
},
"coupon_info": {
"type": [
"string",
"null"
],
"description": "information on coupon discount"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the product page on the seller's website
Note: this field is deprecated and will return null"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
}
}
},
"Response463397119C53_GoogleShoppingCarouselElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the special offer"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleShoppingCarouselElement"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_GoogleShoppingCarouselElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "XPath of the element"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "tags assigned to the product"
},
"seller": {
"type": [
"string",
"null"
],
"description": "name of the seller
the name of the company that placed a corresponding product on Google Shopping"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information about the result"
},
"price": {
"type": [
"number",
"null"
],
"description": "product price
example:384.99"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"product_rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "product rating
the product popularity rate based on product reviews"
},
"product_images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "URLs to the images of the product
the first URL in the array is the featured image of the product"
},
"shopping_url": {
"type": [
"string",
"null"
],
"description": "URL to the product page on Google Shopping"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Google Shopping
note that there is no full list of possible values as the product_id is a dynamic value assigned by Google
if there are no values, you will get null
example:4485466949985702538
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": [
"string",
"null"
],
"description": "unique identifier of the SERP data element
note that there is no full list of possible values as the data_docid is a dynamic value assigned by Google
example:17363035694596624076"
},
"gid": {
"type": [
"string",
"null"
],
"description": "global product identifier on Google Shopping
note that there is no full list of possible values as the gid is a dynamic value assigned by Google
if there are no values, you will get null
example:4702526954592161872
learn more about gid parameter in this help center guide"
},
"delivery_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DeliveryInfo"
}
],
"description": "delivery information
delivery information including free and fast delivery date ranges"
},
"special_offer_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpecialOfferInfo"
}
],
"description": "special offer from the seller
information on the special offer from the seller, including discount and coupon info"
}
}
},
"Response463397119C53_RelatedSearchesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingProductsElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found on Google Shopping"
}
}
},
"Provider463397119C53_MerchantGoogleProductsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://www.google.com/search?q=fish&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Google Shopping languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:en"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:google.co.uk, google.com.au, google.de, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be retrieved from Google Shopping SERP
default value: 40
max value: 120
Your account will be billed per each SERP containing up to 40 results;
Setting depth above 40 may result in additional charges if the search engine returns more than 40 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
max value: 7
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
you can use the following search URL parameters for customizing the search;
example:&tbs=ppr_min:45 – search for products that cost more than 45 USD;&tbs=ppr_max:50 – search for products that cost less than 50 USD;&tbs=p_ord:p – sort by ascending price;&tbs=p_ord:pd – sort by descending price;&tbs=p_ord:rv – sort by review score;&&udm=28 – use new Google Shopping markup with 40 SERP results returned by default (the cost for one SERP is deducted accordingly); the maximum depth is 200; this parameter must be specified without tbm=shop in the url;&shoprs=$value – specify advanced filtering and sorting in the new Shopping markup; replace $value with a string in protobuf Base64 format; learn more on our help center.
Note that search_param values will be ignored if any of the following parameters are used: price_min, price_max, sort_by\n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"price_min": {
"type": [
"integer",
"null"
],
"description": "minimum product price
optional field
minimum price of the returned products listed on Google Shopping for the specified query
example:5
Note: if you specify price_min, the search_param parameter will be ignored"
},
"price_max": {
"type": [
"integer",
"null"
],
"description": "maximum product price
optional field
maximum price of the returned products listed on Google Shopping for the specified query
example:100
Note: if you specify price_max, the search_param parameter will be ignored"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting rules
optional field
the following sorting rules are supported:review_score, price_low_to_high, price_high_to_low
example:sort_by:\"review_score\"
Note: if you specify sort_by, the search_param parameter will be ignored"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleProductsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleProductsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: products"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of Google Shopping Products Advanced task"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of Google Shopping Products HTML task"
}
}
},
"Response463397119C53_MerchantGoogleSellersTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleSellersTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleSellersTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleSellersTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleSellersTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"product_id": {
"type": [
"string",
"null"
],
"description": "product_id received in a POST array
learn more about the parameter in this help center guide"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to Google Shopping results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the product"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the product page"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL to the product image"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "product rating
the product popularity rate based on product reviews"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in Google Shopping SERP
contains types of all search results (items) found in the returned SERP
possible item types:shops_list, buy_on_google"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingSellersElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Response463397119C53_BaseMerchantGoogleShoppingSellersElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements found in Google Shopping SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in Google Shopping SERP
possible values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "XPath of the element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "product title"
},
"url": {
"type": [
"string",
"null"
],
"description": "Google Shopping URL forwarding to the product page on the seller’s website
if you want to obtain a URL of the advertisement forwarding to the product page on the seller's website, please refer to the Google Shopping Sellers Ad URL endpoint"
},
"details": {
"type": [
"string",
"null"
],
"description": "details and special offers
if there are no details, the value will be null"
},
"base_price": {
"type": [
"number",
"null"
],
"description": "product price without tax and shipping"
},
"tax": {
"type": [
"number",
"null"
],
"description": "the amount of tax
tax is specified as the actual amount of money, not as the percentage"
},
"shipping_price": {
"type": [
"number",
"null"
],
"description": "product shipping price"
},
"total_price": {
"type": [
"number",
"null"
],
"description": "product price including tax and shipping",
"format": "int64"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency in the ISO format
example:USD"
},
"seller_name": {
"type": [
"string",
"null"
],
"description": "name of the seller
the name of the company that placed a corresponding product on Google Shopping"
},
"shop_ad_aclk": {
"type": [
"string",
"null"
],
"description": "unique ad click referral parameter
using this parameter you can get a URL of the advertisement in Google Shopping Sellers Ad URL"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"shops_list": "#/components/schemas/Response463397119C53_GoogleShoppingSellersShopsListElementItem",
"buy_on_google": "#/components/schemas/Response463397119C53_GoogleShoppingSellersBuyOnGoogleElementItem"
}
}
},
"Response463397119C53_GoogleShoppingSellersShopsListElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingSellersElementItem"
}
]
},
{
"type": "object",
"properties": {
"price_multiplier": {
"type": [
"integer",
"null"
],
"description": "monthly price multiplier
indicates the number of months covered by the monthly payment for the product"
},
"displayed_payment_breakdown": {
"type": [
"string",
"null"
],
"description": "installment details as displayed in the results
shows how the product price can be broken down into monthly payments, if applicable"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingElement"
}
],
"description": "shop rating
the shop popularity rate based on product reviews"
},
"product_condition": {
"type": [
"string",
"null"
],
"description": "indicated condition of the product
possible values: Used, Refurbished, New, Pre-owned, null"
},
"product_annotation": {
"type": [
"string",
"null"
],
"description": "data from annotations and badges with special offers
if there is no annotation for this product, the value will be null
examples: LOW PRICE, SPECIAL OFFER, SALE, PRICE DROP"
},
"product_availability": {
"type": [
"string",
"null"
],
"description": "product availability information
product availability information
can take the following values: in_stock, limited_stock, out_of_stock, backordered, pre_order_available, on_display_to_order"
}
}
}
]
},
"Response463397119C53_GoogleShoppingSellersBuyOnGoogleElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseMerchantGoogleShoppingSellersElementItem"
}
]
},
{
"type": "object",
"properties": {
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "shop rating
the shop popularity rate based on product reviews"
}
}
}
]
},
"Provider463397119C53_MerchantGoogleSellersTaskPostRequestInfo": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "unique product identifier on Google Shopping
required field if data_docid or gid is not specified
we recommend specifying product_id together with data_docid and gid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:4485466949985702538
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": "string",
"description": "unique identifier of the SERP data element
required field if product_id or gid is not specified
we recommend specifying data_docid together with product_id and gid for optimal results;
you can get this value for a certain element by making a separate request to the Google Shopping Products endpoint
example:13071766526042404278"
},
"gid": {
"type": "string",
"description": "global product identifier on Google Shopping
required field if product_id or data_docid is not specified
we recommend specifying gid together with product_id and data_docid for optimal results;
you can get this value for a certain product by making a separate request to the Google Shopping Products endpoint
example:4702526954592161872
learn more about the parameter in this help center guide"
},
"pvf": {
"type": [
"string",
"null"
],
"description": "product variant filter on Google Shopping
optional field
parameter in Google Shopping URL, setting optional product variant filtration;
example:Eg4iBWNvbG9yKgV3aGl0ZRISIgxwYWNrYWdlIHNpemUqAjE0EgoiBHNpemUqAnhs"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available Google Shopping locations with their location_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available Google Shopping locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/merchant/google/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available Google Shopping languages with their language_name by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available Google Shopping languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/merchant/google/languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be retrieved from Google Shopping SERP
default value: 10
max value: 200
your account will be billed per each SERP containing up to 10 results;
setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
the cost can be calculated on the Pricing page"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:google.co.uk, google.com.au, google.de, etc."
},
"get_shops_on_google": {
"type": [
"boolean",
"null"
],
"description": "include \"buy on Google\" shops
optional field
if set to true, the response will contain the list of sellers that allow to purchase a given product directly on Google
Note: if set to true, the cost of a task will be doubled"
},
"additional_specifications": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "object containing additional url parameters
you can get additional information about the product by using the \"additional_specifications object, which you can get by making a separate request to the Google Shopping Products endpoint
example:\"additional_specifications\": {"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
\"eto\": \"16157121050167572763_0\"
}
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_MerchantGoogleSellersTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleSellersTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_MerchantGoogleSellersTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MerchantGoogleSellersTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_MerchantGoogleSellersTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
can take the following values: shopping"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of Google Shopping Sellers Advanced task"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of Google Shopping Sellers HTML task"
}
}
},
"Response463397119C53_OnPageAvailableFiltersResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageAvailableFiltersTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageAvailableFiltersTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageAvailableFiltersResultInfo"
}
]
},
"description": "array of results
contains the full list of available parameters that can be used for data filtration
the parameters are grouped by the endpoint they can be used with"
}
}
}
]
},
"Response463397119C53_OnPageAvailableFiltersResultInfo": {
"type": "object",
"properties": {
"resources": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"pages": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"non_indexable": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"links": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"pages_by_resource": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"redirect_chains": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"keyword_density": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"uncrawlable_resources": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
}
},
"Provider463397119C53_OnPageContentParsingRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL of the content to parse
required field
URL of the page to parse
example:
`https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api`"
},
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
note: the enable_content_parsing parameter in the POST request must be set to true
example:\"07131248-1535-0216-1000-17384017ad04\""
},
"markdown_view": {
"type": [
"boolean",
"null"
],
"description": "return page content as markdown
optional field
if set to true, the markdown-formatted content of the page will be returned in the page_as_markdown field of the response;
default value: false"
}
},
"example": [
{
"url": "https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api",
"id": "11161551-1535-0216-0000-500b3f307f92"
}
]
},
"Response463397119C53_OnPageContentParsingResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageContentParsingTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageContentParsingTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageContentParsingResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageContentParsingResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array
",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentParsingElement"
}
]
},
"description": "items array
"
}
}
},
"Response463397119C53_CrawlStatusInfo": {
"type": "object",
"properties": {
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "maximum number of pages to crawl\n indicates the max_crawl_pages limit you specified when setting a task",
"format": "int64"
},
"pages_in_queue": {
"type": [
"integer",
"null"
],
"description": "number of pages that are currently in the crawling queue",
"format": "int64"
},
"pages_crawled": {
"type": [
"integer",
"null"
],
"description": "number of crawled pages",
"format": "int64"
}
}
},
"Response463397119C53_ContentParsingElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"fetch_time": {
"type": [
"string",
"null"
],
"description": "date and time when the content was fethced
example:
\"2022-11-01 10:02:52 +00:00\""
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status code
you can find the full list of the response codes here
Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions"
},
"page_content": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageContentInfo"
}
],
"description": "parsed content of the page
"
},
"page_as_markdown": {
"type": [
"string",
"null"
],
"description": "page content in the markdown format
page content in the text-to-HTML markdown format
specify markdown_view as true in the request to return the value"
}
}
},
"Response463397119C53_PageContentInfo": {
"type": "object",
"properties": {
"header": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageSectionContentInfo"
}
],
"description": "parsed content of the header
"
},
"footer": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageSectionContentInfo"
}
],
"description": "content of the footer of the table
"
},
"main_topic": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopicInfo"
}
]
},
"description": "main topic on the page
you can find more information about topic priority calculation in this help center article
"
},
"secondary_topic": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopicInfo"
}
]
},
"description": "secondary topic on the page
you can find more information about topic priority calculation in this help center article
"
},
"ratings": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContententRatingInfo"
}
]
},
"description": "contains objects with rating information for the products displayed on the page
"
},
"offers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentOfferInfo"
}
]
},
"description": "array of products displayed on the page
contains objects with information on products displayed on the page"
},
"comments": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentCommentInfo"
}
]
},
"description": "array of comments displayed on the page
contains objects with information on comments related to displayed products"
},
"contacts": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Contacts"
}
],
"description": "contact information
contains contact information displayed on the page"
}
}
},
"Response463397119C53_PageSectionContentInfo": {
"type": "object",
"properties": {
"primary_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SectionContentItemInfo"
}
]
},
"description": "primary content on the page
you can find more information about content priority calculation in this help center article
"
},
"secondary_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SectionContentItemInfo"
}
]
},
"description": "secondary content on the page
you can find more information about content priority calculation in this help center article
"
},
"table_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TableContentInfo"
}
]
},
"description": "content of the table on the page
"
}
}
},
"Response463397119C53_SectionContentItemInfo": {
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "secondary content on the page\nyou can find more information about content priority calculation in this help center article"
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL.\ndisplayed in case the text is a link anchor"
},
"urls": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentUrlInfo"
}
]
},
"description": "contains other URLs and anchors found in the content element"
}
}
},
"Response463397119C53_ContentUrlInfo": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "contains other URLs and anchors found in the content element"
},
"anchor_text": {
"type": [
"string",
"null"
],
"description": "text of the URL’s anchor"
}
}
},
"Response463397119C53_TableContentInfo": {
"type": "object",
"properties": {
"header": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TableContentItemInfo"
}
]
},
"description": "parsed content of the header"
},
"body": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TableContentItemInfo"
}
]
},
"description": "content of the body of the table"
},
"footer": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TableContentItemInfo"
}
]
},
"description": "content of the footer of the table"
}
}
},
"Response463397119C53_TableContentItemInfo": {
"type": "object",
"properties": {
"row_cells": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RowCellInfo"
}
]
},
"description": "content of the row cells of the header"
}
}
},
"Response463397119C53_RowCellInfo": {
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "content of the row cells of the header"
},
"urls": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentUrlInfo"
}
]
},
"description": "contains other URLs and anchors found in the content element"
},
"is_header": {
"type": [
"boolean",
"null"
],
"description": "content of the row cells of the header"
}
}
},
"Response463397119C53_TopicInfo": {
"type": "object",
"properties": {
"h_title": {
"type": [
"string",
"null"
],
"description": "meta title
"
},
"main_title": {
"type": [
"string",
"null"
],
"description": " main title of the block
"
},
"author": {
"type": [
"string",
"null"
],
"description": "content author name
"
},
"language": {
"type": [
"string",
"null"
],
"description": "content language
"
},
"level": {
"type": [
"integer",
"null"
],
"description": "HTML level
"
},
"primary_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SectionContentItemInfo"
}
]
},
"description": "primary content on the page
you can find more information about content priority calculation in this help center article
"
},
"secondary_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SectionContentItemInfo"
}
]
},
"description": "secondary content on the page
you can find more information about content priority calculation in this help center article
"
},
"table_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TableContentInfo"
}
]
},
"description": "content of the table on the page
"
}
}
},
"Response463397119C53_ContentOfferInfo": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "name of the product"
},
"price": {
"type": [
"number",
"null"
],
"description": "price of the product",
"format": "double"
},
"price_currency": {
"type": [
"string",
"null"
],
"description": "price currency"
},
"price_valid_until": {
"type": [
"string",
"null"
],
"description": "displays the date and time until which the price is valid\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nexample: \"2022-11-01 10:02:52 +00:00\""
}
}
},
"Response463397119C53_ContentCommentInfo": {
"type": "object",
"properties": {
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContententRatingInfo"
}
],
"description": "product’s rating\ncontains information about the rating a customer has given to the product"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the customer’s comment"
},
"publish_date": {
"type": [
"string",
"null"
],
"description": "date when the comment was published"
},
"author": {
"type": [
"string",
"null"
],
"description": "author of the comment"
},
"have_form": {
"type": [
"boolean",
"null"
],
"description": ""
},
"primary_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SectionContentItemInfo"
}
]
},
"description": "primary content on the page\nyou can find more information about content priority calculation in this help center article"
}
}
},
"Response463397119C53_Contacts": {
"type": "object",
"properties": {
"telephones": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of telephone numbers
"
},
"emails": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of emails
"
}
}
},
"Provider463397119C53_OnPageContentParsingLiveRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL of the content to parse
required field
URL of the page to parse
example:
`https://www.fujielectric.com/`"
},
"custom_user_agent": {
"type": [
"string",
"null"
],
"description": "custom user agent
optional field
custom user agent for crawling a website
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36
default value: Mozilla/5.0 (compatible; RSiteAuditor)"
},
"browser_preset": {
"type": [
"string",
"null"
],
"description": "preset for browser screen parameters
optional field
if you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factordesktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920browser_screen_height: 1080browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390browser_screen_height: 844browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024browser_screen_height: 1366browser_screen_scale_factor: 2enable_javascript or enable_browser_rendering to true"
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen width
optional field
you can set a custom browser screen width to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;enable_javascript or enable_browser_rendering to true240
maximum value, in pixels: 9999",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen height
optional field
you can set a custom browser screen height to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;enable_javascript or enable_browser_rendering to true240
maximum value, in pixels: 9999"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser screen scale factor
optional field
you can set a custom browser screen resolution ratio to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;enable_javascript or enable_browser_rendering to true0.5
maximum value: 3"
},
"store_raw_html": {
"type": [
"boolean",
"null"
],
"description": "store HTML of a crawled page
optional field
set to true if you want to get the HTML of the page using the OnPage Raw HTML endpoint
default value: false"
},
"disable_cookie_popup": {
"type": [
"boolean",
"null"
],
"description": "disable the cookie popup
optional field
set to true if you want to disable the popup requesting cookie consent from the user;
default value:false"
},
"accept_language": {
"type": [
"string",
"null"
],
"description": "language header for accessing the website
optional field
all locale formats are supported (xx, xx-XX, xxx-XX, etc.)
Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the \"type\":\"broken in the response array"
},
"enable_javascript": {
"type": [
"boolean",
"null"
],
"description": "load javascript on a page
optional field
set to true if you want to load the scripts available on a page
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"enable_browser_rendering": {
"type": [
"boolean",
"null"
],
"description": "emulate browser rendering to measure Core Web Vitals
optional field
by using this parameter you will be able to emulate a browser when loading a web page;enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page;
default value: false
set to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response;
if you use this field, enable_javascript, and load_resources parameters must be set to true
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"enable_xhr": {
"type": [
"boolean",
"null"
],
"description": "enable XMLHttpRequest on a page
optional field
set to true if you want our crawler to request data from a web server using the XMLHttpRequest object
default value:falseenable_javascript must be set to true;"
},
"switch_pool": {
"type": [
"boolean",
"null"
],
"description": "switch proxy pool
optional field
if true, additional proxy pools will be used to obtain the requested data;
the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors"
},
"ip_pool_for_scan": {
"type": [
"string",
"null"
],
"description": "proxy pool
optional field
you can choose a location of the proxy pool that will be used to obtain the requested data;
the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errors
possible values: us, de"
},
"markdown_view": {
"type": [
"boolean",
"null"
],
"description": "return page content as markdown
optional field
if set to true, the markdown-formatted content of the page will be returned in the page_as_markdown field of the response;
default value: false"
}
},
"example": [
{
"url": "https://dataforseo.com/blog/a-versatile-alternative-to-google-trends-exploring-the-power-of-dataforseo-trends-api"
}
]
},
"Response463397119C53_OnPageContentParsingLiveResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageContentParsingLiveTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageContentParsingLiveTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageContentParsingLiveResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageContentParsingLiveResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ContentParsingElement"
}
]
},
"description": "items array"
}
}
},
"Provider463397119C53_OnPageDuplicateContentRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": "string",
"description": "page URL
required field
specify the initial page you want to receive duplicate content for"
},
"similarity": {
"type": [
"integer",
"null"
],
"description": "content similarity score
by default, the content is considered duplicate if the value is greater than or equals 6
you can specify any similarity score in the 0-to-10 range"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"url": "https://www.etsy.com/"
}
]
},
"Response463397119C53_OnPageDuplicateContentResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageDuplicateContentTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageDuplicateContentTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageDuplicateContentResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageDuplicateContentResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageDuplicateContentItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageDuplicateContentItem": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "URL of the specified page"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total count of duplicate pages",
"format": "int64"
},
"pages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DuplicatePageInfo"
}
]
},
"description": "pages with duplicate content"
}
}
},
"Response463397119C53_DuplicatePageInfo": {
"type": "object",
"properties": {
"similarity": {
"type": [
"integer",
"null"
]
},
"page": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageHtmlResourceItem"
}
]
},
"description": "information about the page with duplicate content"
}
}
},
"Response463397119C53_OnPageHtmlResourceItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
{
"type": "object",
"properties": {
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageMetaInfo"
}
],
"properties": {
"social_media_tags": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"broken_html": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourceIssueInfo"
}
],
"description": "resource errors and warnings"
}
},
"description": "page propertiesthe value depends on the resource_type"
},
"page_timing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageTiming"
}
],
"description": "object of page load metrics"
},
"onpage_score": {
"type": [
"number",
"null"
],
"description": "shows how page is optimized on a 100-point scalethis field shows how page is optimized considering critical on-page issues and warnings detected;100 is the highest possible score that means the page does not have any critical on-page issues and important warnings;learn more about how the metric is calculated in this help center article"
},
"total_dom_size": {
"type": [
"integer",
"null"
],
"description": "total DOM size of a page",
"format": "int64"
},
"custom_js_response": {
"type": [
"object",
"null"
],
"description": "the result of executing a specified JS scriptnote that you should specify a custom_js field when setting a task to receive this data and the field type and its value will totally depend on the script you specified;you can also filter the results by this value specifying filters in the following way:[\"custom_js_response.url\", \"like\", \"pixel\"]"
},
"custom_js_client_exception": {
"type": [
"string",
"null"
],
"description": "error when executing a custom jsif the error occurred when executing the script you specified in the custom_js field, the error message would be displayed here"
},
"broken_resources": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page contains broken resources"
},
"broken_links": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page contains broken links"
},
"duplicate_title": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page has duplicate title tags"
},
"duplicate_description": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page has a duplicate description"
},
"duplicate_content": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page has duplicate content"
},
"click_depth": {
"type": [
"integer",
"null"
],
"description": "number of clicks it takes to get to the pageindicates the number of clicks from the homepage needed before landing at the target page"
},
"is_resource": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page is a single resource"
},
"url_length": {
"type": [
"integer",
"null"
],
"description": "page URL length in characters"
},
"relative_url_length": {
"type": [
"integer",
"null"
],
"description": "relative URL length in characters"
}
}
}
]
},
"Response463397119C53_BaseOnPageResourceItem": {
"type": "object",
"properties": {
"resource_type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status codeyou can find the full list of the response codes hereNote: we strongly recommend designing a necessary system for handling related exceptional or error conditions"
},
"location": {
"type": [
"string",
"null"
],
"description": "location headerindicates the URL to redirect a page to"
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL"
},
"resource_errors": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourceIssueInfo"
}
],
"description": "resource errors and warnings"
},
"size": {
"type": [
"integer",
"null"
],
"description": "resource sizeindicates the size of a given page measured in bytes"
},
"encoded_size": {
"type": [
"integer",
"null"
],
"description": "page size after encodingindicates the size of the encoded page measured in bytes"
},
"total_transfer_size": {
"type": [
"integer",
"null"
],
"description": "compressed page sizeindicates the compressed size of a given page",
"format": "int64"
},
"fetch_time": {
"type": [
"string",
"null"
],
"description": "date and time when a resource was fetchedin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”example:2019-11-15 12:57:46 +00:00"
},
"cache_control": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CacheControl"
}
],
"description": "instructions for caching"
},
"checks": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"boolean",
"null"
]
},
"description": "website checkson-page check-ups related to the page"
},
"content_encoding": {
"type": [
"string",
"null"
],
"description": "type of encoding"
},
"media_type": {
"type": [
"string",
"null"
],
"description": "types of media used to display a page"
},
"server": {
"type": [
"string",
"null"
],
"description": "server version"
},
"last_modified": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LastModified"
}
],
"description": "contains data on changes related to the resourceif there is no data, the value will be null"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "resource_type",
"mapping": {
"html": "#/components/schemas/Response463397119C53_OnPageHtmlResourceItem",
"broken": "#/components/schemas/Response463397119C53_OnPageBrokenResourceItem",
"redirect": "#/components/schemas/Response463397119C53_OnPageRedirectResourceItem",
"script": "#/components/schemas/Response463397119C53_OnPageScriptResourceItem",
"image": "#/components/schemas/Response463397119C53_OnPageImageResourceItem",
"stylesheet": "#/components/schemas/Response463397119C53_OnPageStylesheetResourceItem"
}
}
},
"Response463397119C53_OnPageBrokenResourceItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
{
"type": "object",
"properties": {
"fetch_timing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FetchTiming"
}
],
"description": "time range within which a result was fetched"
},
"is_resource": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page is a single resource"
},
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageMetaInfo"
}
],
"description": "resource properties
the value depends on the resource_type
note that if you do not indicate a url when setting a task, resource's meta is returned based on the data from the page where our crawler first saw the resource;
to obtain resource's meta from a particular url, specify that URL when setting a task"
},
"accept_type": {
"type": [
"string",
"null"
],
"description": "indicates the expected type of resource
for example, if \"resource_type\": \"broken\", accept_type will indicate the type of the broken resource
possible values: any, none, image, sitemap, robots, script, stylesheet, redirect, html, text, other, font"
}
}
}
]
},
"Response463397119C53_FetchTiming": {
"type": "object",
"properties": {
"duration_time": {
"type": [
"integer",
"null"
],
"description": "total time it takes until a browser receives a complete response from a server (in milliseconds)"
},
"fetch_start": {
"type": [
"integer",
"null"
],
"description": "time to start downloading the HTML resourcethe amount of time the browser needs to start downloading a page"
},
"fetch_end": {
"type": [
"integer",
"null"
],
"description": "time to complete downloading the HTML resourcethe amount of time the browser needs to complete downloading a page"
}
}
},
"Response463397119C53_PageMetaInfo": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "page title"
},
"charset": {
"type": [
"integer",
"null"
],
"description": "code pageexample: 65001"
},
"follow": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page's 'meta robots' allows crawlers to follow the links on the pageif false, the page's 'meta robots' tag contains \"nofollow\" parameter instructing crawlers not to follow the links on the page"
},
"generator": {
"type": [
"string",
"null"
],
"description": "meta tag generator"
},
"htags": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"description": "HTML header tags"
},
"description": {
"type": [
"string",
"null"
],
"description": "content of the meta description tag"
},
"favicon": {
"type": [
"string",
"null"
],
"description": "favicon of the page"
},
"meta_keywords": {
"type": [
"string",
"null"
],
"description": "content of the keywords meta tag"
},
"canonical": {
"type": [
"string",
"null"
],
"description": "canonical page"
},
"internal_links_count": {
"type": [
"integer",
"null"
],
"description": "number of internal links on the page",
"format": "int64"
},
"external_links_count": {
"type": [
"integer",
"null"
],
"description": "number of external links on the page",
"format": "int64"
},
"inbound_links_count": {
"type": [
"integer",
"null"
],
"description": "number of internal links pointing at the page",
"format": "int64"
},
"images_count": {
"type": [
"integer",
"null"
],
"description": "number of images on the page",
"format": "int64"
},
"images_size": {
"type": [
"integer",
"null"
],
"description": "total size of images on the page measured in bytes"
},
"scripts_count": {
"type": [
"integer",
"null"
],
"description": "number of scripts on the page",
"format": "int64"
},
"scripts_size": {
"type": [
"integer",
"null"
],
"description": "total size of scripts on the page measured in bytes"
},
"stylesheets_count": {
"type": [
"integer",
"null"
],
"description": "number of stylesheets on the page",
"format": "int64"
},
"stylesheets_size": {
"type": [
"integer",
"null"
],
"description": "total size of stylesheets on the page measured in bytes"
},
"title_length": {
"type": [
"integer",
"null"
],
"description": "length of the title tag in characters"
},
"description_length": {
"type": [
"integer",
"null"
],
"description": "length of the description tag in characters"
},
"render_blocking_scripts_count": {
"type": [
"integer",
"null"
],
"description": "number of scripts on the page that block page rendering",
"format": "int64"
},
"render_blocking_stylesheets_count": {
"type": [
"integer",
"null"
],
"description": "number of CSS styles on the page that block page rendering",
"format": "int64"
},
"cumulative_layout_shift": {
"type": [
"number",
"null"
],
"description": "Core Web Vitals metric measuring the layout stability of the pagemeasures the sum total of all individual layout shift scores for every unexpected layout shift that occurs during the entire lifespan of the page. Learn more."
},
"meta_title": {
"type": [
"string",
"null"
],
"description": "meta title of the pagemeta tag in the head section of an HTML document that defines the title of a page"
},
"content": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlContentInfo"
}
],
"description": "overall information about content of the page"
},
"deprecated_tags": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "deprecated tags on the page"
},
"duplicate_meta_tags": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "duplicate meta tags on the page"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HunspellInfo"
}
],
"description": "spellcheckhunspell spellcheck errors"
},
"social_media_tags": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "object of social media tags found on the pagecontains social media tags and their contentsupported tags include but are not limited to Open Graph and Twitter card"
},
"broken_html": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourceIssueInfo"
}
],
"description": "resource errors and warnings"
}
}
},
"Response463397119C53_HtmlContentInfo": {
"type": "object",
"properties": {
"plain_text_size": {
"type": [
"integer",
"null"
],
"description": "total size of the text on the page measured in bytes"
},
"plain_text_rate": {
"type": [
"number",
"null"
],
"description": "plaintext rate value\nplain_text_size to size ratio",
"format": "double"
},
"plain_text_word_count": {
"type": [
"integer",
"null"
],
"description": "number of words on the page"
},
"automated_readability_index": {
"type": [
"number",
"null"
],
"description": "Automated Readability Index"
},
"coleman_liau_readability_index": {
"type": [
"number",
"null"
],
"description": "Coleman–Liau Index"
},
"dale_chall_readability_index": {
"type": [
"number",
"null"
],
"description": "Dale–Chall Readability Index"
},
"flesch_kincaid_readability_index": {
"type": [
"number",
"null"
],
"description": "Flesch–Kincaid Readability Index"
},
"smog_readability_index": {
"type": [
"number",
"null"
],
"description": "SMOG Readability Index"
},
"description_to_content_consistency": {
"type": [
"number",
"null"
],
"description": "consistency of the meta description tag with the page contentmeasured from 0 to 1"
},
"title_to_content_consistency": {
"type": [
"number",
"null"
],
"description": "consistency of the meta title tag with the page contentmeasured from 0 to 1"
},
"meta_keywords_to_content_consistency": {
"type": [
"number",
"null"
],
"description": "consistency of meta keywordstag with the page contentmeasured from 0 to 1"
}
}
},
"Response463397119C53_HunspellInfo": {
"type": "object",
"properties": {
"hunspell_language_code": {
"type": [
"string",
"null"
],
"description": "spellcheck language code"
},
"misspelled": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HunspellMisspelledInfo"
}
]
},
"description": "array of misspelled words"
}
}
},
"Response463397119C53_HunspellMisspelledInfo": {
"type": "object",
"properties": {
"word": {
"type": [
"string",
"null"
],
"description": "misspelled word"
}
}
},
"Response463397119C53_OnPageResourceIssueInfo": {
"type": "object",
"properties": {
"errors": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourceIssueItemInfo"
}
]
},
"description": "resource errors"
},
"warnings": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourceIssueItemInfo"
}
]
},
"description": "resource warnings"
}
},
"description": "resource errors and warnings"
},
"Response463397119C53_OnPageResourceIssueItemInfo": {
"type": "object",
"properties": {
"line": {
"type": [
"integer",
"null"
],
"description": "line where the error was found"
},
"column": {
"type": [
"integer",
"null"
],
"description": "column where the error was found"
},
"message": {
"type": [
"string",
"null"
],
"description": "text message of the errorthe full list of possible HTML errors can be found here"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status codeyou can find the full list of the response codes hereNote: we strongly recommend designing a necessary system for handling related exceptional or error conditions"
}
}
},
"Response463397119C53_OnPageRedirectResourceItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
{
"type": "object",
"properties": {
"fetch_timing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FetchTiming"
}
],
"description": "time range within which a result was fetched"
},
"is_resource": {
"type": [
"boolean",
"null"
],
"description": "indicates whether a page is a single resource"
}
}
}
]
},
"Response463397119C53_OnPageScriptResourceItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
{
"type": "object",
"properties": {
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ResourceMetaInfo"
}
]
},
"fetch_timing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FetchTiming"
}
],
"description": "time range within which a result was fetched"
},
"accept_type": {
"type": [
"string",
"null"
],
"description": "indicates the expected type of resourcefor example, if \"resource_type\": \"broken\", accept_type will indicate the type of the broken resourcepossible values:any, none, image, sitemap, robots, script, stylesheet, redirect, html, text, other, font"
}
}
}
]
},
"Response463397119C53_ResourceMetaInfo": {
"type": "object",
"properties": {
"alternative_text": {
"type": [
"string",
"null"
],
"description": "content of the image alt attribute"
},
"title": {
"type": [
"string",
"null"
],
"description": "title"
},
"original_width": {
"type": [
"number",
"null"
],
"description": "original image width in px",
"format": "double"
},
"original_height": {
"type": [
"number",
"null"
],
"description": "original image height in px",
"format": "double"
},
"width": {
"type": [
"number",
"null"
],
"description": "image width in px",
"format": "double"
},
"height": {
"type": [
"number",
"null"
],
"description": "image height in px",
"format": "double"
}
}
},
"Response463397119C53_OnPageImageResourceItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
{
"type": "object",
"properties": {
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ResourceMetaInfo"
}
],
"description": "page propertiesthe value depends on the resource_type"
},
"fetch_timing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FetchTiming"
}
],
"description": "time range within which a result was fetched"
},
"accept_type": {
"type": [
"string",
"null"
],
"description": "indicates the expected type of resourcefor example, if \"resource_type\": \"broken\", accept_type will indicate the type of the broken resourcepossible values:any, none, image, sitemap, robots, script, stylesheet, redirect, html, text, other, font"
}
}
}
]
},
"Response463397119C53_OnPageStylesheetResourceItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
{
"type": "object",
"properties": {
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ResourceMetaInfo"
}
],
"description": "page propertiesthe value depends on the resource_type"
},
"fetch_timing": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FetchTiming"
}
],
"description": "time range within which a result was fetched"
},
"accept_type": {
"type": [
"string",
"null"
],
"description": "indicates the expected type of resourcefor example, if \"resource_type\": \"broken\", accept_type will indicate the type of the broken resourcepossible values:any, none, image, sitemap, robots, script, stylesheet, redirect, html, text, other, font"
}
}
}
]
},
"Response463397119C53_CacheControl": {
"type": "object",
"properties": {
"cachable": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the page is cacheable"
},
"ttl": {
"type": [
"integer",
"null"
],
"description": "time to livethe amount of time the browser caches a resource"
}
}
},
"Response463397119C53_LastModified": {
"type": "object",
"properties": {
"header": {
"type": [
"string",
"null"
],
"description": "date and time when the header was last modifiedin the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"example:2019-11-15 12:57:46 +00:00if there is no data, the value will be null"
},
"sitemap": {
"type": [
"string",
"null"
],
"description": "date and time when the sitemap was last modifiedin the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"example:2019-11-15 12:57:46 +00:00if there is no data, the value will be null"
},
"meta_tag": {
"type": [
"string",
"null"
],
"description": "date and time when the meta tag was last modifiedin the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"example:2019-11-15 12:57:46 +00:00if there is no data, the value will be null"
}
}
},
"Response463397119C53_PageTiming": {
"type": "object",
"properties": {
"time_to_interactive": {
"type": [
"integer",
"null"
],
"description": "Time To Interactive (TTI) metricthe time it takes until the user can interact with a page (in milliseconds)"
},
"dom_complete": {
"type": [
"integer",
"null"
],
"description": "time to load resourcesthe time it takes until the page and all of its subresources are downloaded (in milliseconds)"
},
"largest_contentful_paint": {
"type": [
"number",
"null"
],
"description": "Core Web Vitals metric measuring how fast the largest above-the-fold content element is displayedThe amount of time (in milliseconds) to render the largest content element visible in the viewport, from when the user requests the URL. Learn more."
},
"first_input_delay": {
"type": [
"number",
"null"
],
"description": "Core Web Vitals metric indicating the responsiveness of a pageThe time (in milliseconds) from when a user first interacts with your page to the time when the browser responds to that interaction. Learn more."
},
"connection_time": {
"type": [
"integer",
"null"
],
"description": "time to connect to a serverthe time it takes until the connection with a server is established (in milliseconds)"
},
"time_to_secure_connection": {
"type": [
"integer",
"null"
],
"description": "time to establish a secure connectionthe time it takes until the secure connection with a server is established (in milliseconds)"
},
"request_sent_time": {
"type": [
"integer",
"null"
],
"description": "time to send a request to a serverthe time it takes until the request to a server is sent (in milliseconds)"
},
"waiting_time": {
"type": [
"integer",
"null"
],
"description": "time to first byte (TTFB) in milliseconds"
},
"download_time": {
"type": [
"integer",
"null"
],
"description": "time it takes for a browser to receive a response (in milliseconds)"
},
"duration_time": {
"type": [
"integer",
"null"
],
"description": "total time it takes until a browser receives a complete response from a server (in milliseconds)"
},
"fetch_start": {
"type": [
"integer",
"null"
],
"description": "time to start downloading the HTML resourcethe amount of time the browser needs to start downloading a page"
},
"fetch_end": {
"type": [
"integer",
"null"
],
"description": "time to complete downloading the HTML resourcethe amount of time the browser needs to complete downloading a page"
}
}
},
"Provider463397119C53_OnPageDuplicateTagsRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"type": {
"type": "string",
"description": "type of element"
},
"accumulator": {
"type": [
"string",
"null"
],
"description": "tag value
optional field
specify a title or description here if you want to receive a list of duplicate pages that contains this tag"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"type": "duplicate_description",
"limit": 10
}
]
},
"Response463397119C53_OnPageDuplicateTagsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageDuplicateTagsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageDuplicateTagsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageDuplicateTagsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageDuplicateTagsResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"total_pages_count": {
"type": [
"integer",
"null"
],
"description": "total number of pages with duplicate tags
displays the total number of pages with duplicate tags of the target website",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "number of pages with duplicate tags in the response
displays the number of pages with duplicate tags returned in the response",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageDuplicateTagsItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageDuplicateTagsItem": {
"type": "object",
"properties": {
"accumulator": {
"type": [
"string",
"null"
],
"description": "contains the value of duplicated tag"
},
"total_count": {
"type": [
"integer",
"null"
],
"description": "total count of duplicate pages",
"format": "int64"
},
"pages": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageHtmlResourceItem"
}
]
},
"description": "pages with duplicate tags"
}
}
},
"Provider463397119C53_OnPageForceStopRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\"id values as separate objects in the POST array"
}
},
"example": [
{
"id": "08121600-1535-0216-0000-37b4c7a34453"
},
{
"id": "08121600-1535-0216-0000-d6a5000b6897"
}
]
},
"Response463397119C53_OnPageForceStopResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageForceStopTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageForceStopTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of results"
}
}
}
]
},
"Provider463397119C53_OnPageInstantPagesRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "target page urlrequired fieldabsolute URL of the target page;Note #1: results will be returned for the specified URL only;Note #2: to prevent denial-of-service events, tasks that contain a duplicate crawl host will be returned with a 40501 error;to prevent this error from occurring, avoid setting tasks with the same domain if at least one of your previous tasks with this domain (including a page URL on the domain) is still in a crawling queue"
},
"custom_user_agent": {
"type": [
"string",
"null"
],
"description": "custom user agentoptional fieldcustom user agent for crawling a websiteexample: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36default value: Mozilla/5.0 (compatible; RSiteAuditor)"
},
"browser_preset": {
"type": [
"string",
"null"
],
"description": "preset for browser screen parametersoptional fieldif you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factorpossible values:desktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920browser_screen_height: 1080browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390browser_screen_height: 844browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024browser_screen_height: 1366browser_screen_scale_factor: 2Note: to use this parameter, set enable_javascript or enable_browser_rendering to true"
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen widthoptional fieldyou can set a custom browser screen width to perform audit for a particular device;if you use this field, you don't need to indicate browser_preset as it will be ignored;Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240maximum value, in pixels: 9999",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen heightoptional fieldyou can set a custom browser screen height to perform audit for a particular device;if you use this field, you don't need to indicate browser_preset as it will be ignored;Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240maximum value, in pixels: 9999"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser screen scale factoroptional fieldyou can set a custom browser screen resolution ratio to perform audit for a particular device;if you use this field, you don't need to indicate browser_preset as it will be ignored;Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value: 0.5maximum value: 3"
},
"store_raw_html": {
"type": [
"boolean",
"null"
],
"description": "store HTML of a crawled pageoptional fieldset to true if you want get the HTML of the page using the OnPage Raw HTML endpointdefault value: false"
},
"accept_language": {
"type": [
"string",
"null"
],
"description": "language header for accessing the websiteoptional fieldall locale formats are supported (xx, xx-XX, xxx-XX, etc.)Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the \"type\":\"broken in the response array"
},
"load_resources": {
"type": [
"boolean",
"null"
],
"description": "load resourcesoptional fieldset to true if you want to load image, stylesheets, scripts, and broken resourcesdefault value: falseNote: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"enable_browser_rendering": {
"type": [
"boolean",
"null"
],
"description": "emulate browser rendering to measure Core Web Vitalsoptional fieldby using this parameter you will be able to emulate a browser when loading a web page;enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page;default value: falseset to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response;if you use this field, parameters enable_javascript, and load_resources are enabled automatically;Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"disable_cookie_popup": {
"type": [
"boolean",
"null"
],
"description": "disable the cookie popup optional fieldset to true if you want to disable the popup requesting cookie consent from the user;default value:false"
},
"return_despite_timeout": {
"type": [
"boolean",
"null"
],
"description": "return data on pages despite the timeout erroroptional fieldif true, the data will be provided on pages that failed to load within 120 seconds and responded with a timeout error;default value: false"
},
"enable_javascript": {
"type": [
"boolean",
"null"
],
"description": "load javascript on a pageoptional fieldset to true if you want to load the scripts available on a pagedefault value: falseNote: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"enable_xhr": {
"type": [
"boolean",
"null"
],
"description": "enable XMLHttpRequest on a pageoptional fieldset to true if you want our crawler to request data from a web server using the XMLHttpRequest objectdefault value:falseif you use this field, enable_javascript must be set to true;"
},
"custom_js": {
"type": [
"string",
"null"
],
"description": "custom javascriptoptional fieldNote that the execution time for the script you enter here should be 700 ms maximum;for example, you can use the following JS snippet to check if the website contains Google Tag Manager as a scr attribute:let meta = { haveGoogleAnalytics: false, haveTagManager: false };rnfor (var i = 0; i < document.scripts.length; i++) {rn let src = document.scripts[i].getAttribute(\"src\");rn if (src != undefined) {rn if (src.indexOf(\"analytics.js\") >= 0)rn meta.haveGoogleAnalytics = true;rntif (src.indexOf(\"gtm.js\") >= 0)rn meta.haveTagManager = true;rn }rn}rnmeta;the returned value depends on what you specified in this field. For instance, if you specify the following script:meta = {}; meta.url = document.URL; meta.test = 'test'; meta;as a response you will receive the following data:\"custom_js_response\": {\"url\": \"https://dataforseo.com/\",\"test\": \"test\"}"
},
"validate_micromarkup": {
"type": [
"boolean",
"null"
],
"description": "enable microdata validationoptional fieldif set to true, you can use the OnPage API Microdata endpoint with the id of the task;default value: false"
},
"check_spell": {
"type": [
"boolean",
"null"
],
"description": "check spellingoptional fieldset to true to check spelling on a website using Hunspell librarydefault value: false"
},
"checks_threshold": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "custom threshold values for checksoptional fieldyou can specify custom threshold values for the parameters included in the checks array of OnPage API responses;Note: only integer threshold values can be modified;"
},
"switch_pool": {
"type": [
"boolean",
"null"
],
"description": "switch proxy pooloptional fieldif true, additional proxy pools will be used to obtain the requested data;the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors"
},
"ip_pool_for_scan": {
"type": [
"string",
"null"
],
"description": "proxy pooloptional fieldyou can choose a location of the proxy pool that will be used to obtain the requested data;the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errorspossible values: us, de"
}
},
"example": [
{
"url": "https://dataforseo.com/blog",
"enable_javascript": true,
"custom_js": "meta = {}; meta.url = document.URL; meta;"
}
]
},
"Response463397119C53_OnPageInstantPagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageInstantPagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageInstantPagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageInstantPagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageInstantPagesResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling sessionpossible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"description": "details of the crawling sessionin this case the value will be null"
},
"crawl_gateway_address": {
"type": [
"string",
"null"
],
"description": "crawler ip addressdisplays the IP address used by the crawler to initiate the current crawling sessionyou can find the full list of IPs used by our crawler in the Overview section"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageHtmlResourceItem"
}
]
},
"description": "items array"
}
}
},
"Provider463397119C53_OnPageKeywordDensityRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"keyword_length": {
"type": "integer",
"description": "number of words for a keyword
required field
possible values:1, 2, 3, 4, 5"
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL
optional field
if you do not specify a page here, the results will be provided for the whole website
if you use this field, the API response will contain only keywords from the specified page
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned keywords
optional field
default value: 100
maximum value: 1000"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"keyword\",\"=\",\"%seo%\"][[\"keyword\",\"=\",\"%seo%\"],
\"and\",
[\"frequency\",\"<\",\"6\"]][[\"keyword\",\"not_like\",\"%seo%\"],
\"and\",
[[\"frequency\",\">\",\"6\"],\"or\",[\"density\",\">\",\"0.02\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"frequency,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"keyword,asc\",\"frequency,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "09101923-1535-0216-0000-2389a8854b70",
"url": "https://dataforseo.com/",
"keyword_length": 2,
"filters": [
"frequency",
">",
5
]
}
]
},
"Response463397119C53_OnPageKeywordDensityResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageKeywordDensityTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageKeywordDensityTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageKeywordDensityResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageKeywordDensityResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items
total number of keywords on the specified website or web page matching the set keyword_length and filters",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageKeywordDensityItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageKeywordDensityItem": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "returned keyword"
},
"frequency": {
"type": [
"integer",
"null"
],
"description": "keyword frequency
number of times the keyword appears on the website (or webpage if you specified a url)"
},
"density": {
"type": [
"number",
"null"
],
"description": "keyword density
calculated as a ratio of frequency to the total count of keywords with the set keyword_length on the web page or website"
}
}
},
"Response463397119C53_OnPageLighthouseAuditsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseAuditsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseAuditsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseAuditsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseAuditsResultInfo": {
"type": "object",
"properties": {
"audits": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "the list of available lighthouse audits
an array containing the titles of available audits;
Note: the titles can change depending on if the audit passed or failed and may contain markdown code;
Note #2: if you're using the audit that contains a slash (/) in its name, search by the last word after the slash"
}
}
},
"Response463397119C53_OnPageLighthouseLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Provider463397119C53_OnPageLighthouseLiveJsonRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "target URL
required field
target page should be specified with its absolute URL (including http:// or https://)
example:https://dataforseo.com/"
},
"for_mobile": {
"type": [
"boolean",
"null"
],
"description": "applies mobile emulation
optional field
if set to true, Lighthouse will use mobile device and screen emulation to test the page against mobile environment
if set to false, the results will be provided for desktop
default value: false"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "categories of Lighthouse audits
optional field
each category is a collection of audits and audit groups that applies weighting and scoring to the section (see official definition)audits
use this field to get data for specific categories you indicate hereseo, performance, best_practices, accessibility"
},
"audits": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Lighthouse audits
optional field
audits are individual tests Lighthouse runs for each specific feature/optimization/metric to produce a numeric score (see official definition);
use this field to get data for specific audits you indicate here;categories, you can use this field to get data for the specified audits only
for example, if you ignore \"categories\" and specify \"audits\": [\"metrics/cumulative-layout-shift\",\"metrics/largest-contentful-paint\",\"metrics/total-blocking-time\"], you will get data only for these audits
for example, if you specify \"categories\": [\"seo\"] and \"audits\": [\"metrics/cumulative-layout-shift\",\"metrics/largest-contentful-paint\",\"metrics/total-blocking-time\"], you will get only these audits under \"performance\" and all audits under \"seo\"
optional field
you can obtain the results specific to a certain Lighthouse version by specifying its number
the list of available versions is available through the Lighthouse Versions endpoint"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "lighthouse language name
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages
default value:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "lighthouse language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages
default value:en"
},
"custom_user_agent": {
"type": [
"string",
"null"
],
"description": "custom user agent
optional field
specify the custom user agent used by the browser when running the Lighthouse audit;
can be specified with up to 254 characters;"
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen width
optional field
set the screen width of the browser used for the Lighthouse audit to emulate a specific device;
can be specified within the following range: 240–9999;",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen height
optional field
set the screen height of the browser used for the Lighthouse audit to emulate a specific device;
can be specified within the following range: 240–9999;"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser screen scale factor
optional field
set the device pixel ratio of the browser used for the Lighthouse audit;
can be specified within the following range: 0.5–3;"
},
"browser_network_throttling_method": {
"type": [
"string",
"null"
],
"description": "browser network throttling method
optional field
defines the method used to apply throttling during the Lighthouse audit;
possible vaules:simulate - calculates estimated performance metrics without applying explicit throttling;devtools - applies the throttling settings specified in browser_network_throttling and browser_cpu_throttling_multiplier;provided - uses the network conditions of the crawling environment;"
},
"browser_cpu_throttling_multiplier": {
"type": [
"number",
"null"
],
"description": "browser CPU throttling multiplier
required if browser_network_throttling_method is set to devtools;
set the CPU throttling multiplier to simulate device performance conditions during the Lighthouse audit;
can be specified within the following range: 1–4;
Note: this parameter is applied only when browser_network_throttling_method is set to devtools;"
},
"browser_network_throttling": {
"type": [
"string",
"null"
],
"description": "browser network throttling
required if browser_network_throttling_method is set to devtools;
set the network throttling profile to simulate connection speed conditions during the Lighthouse audit;
possible values: no_throttling, fast_4g, slow_4g, regular_3g, pc;
Note: this parameter is applied only when browser_network_throttling_method is set to devtools;"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"url": "https://dataforseo.com",
"for_mobile": true,
"tag": "some_string_123"
}
]
},
"Response463397119C53_OnPageLighthouseLiveJsonResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseLiveJsonTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseLiveJsonTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
}
},
"description": "results of Lighthouse audit
this array will include data according to the parameters you specified when setting a task;
required field
target page should be specified with its absolute URL (including http:// or https://)
example:https://dataforseo.com/"
},
"for_mobile": {
"type": [
"boolean",
"null"
],
"description": "applies mobile emulation
optional field
if set to true, Lighthouse will use mobile device and screen emulation to test the page against mobile environment
if set to false, the results will be provided for desktop
default value: false"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "categories of Lighthouse audits
optional field
each category is a collection of audits and audit groups that applies weighting and scoring to the section (see official definition)if you ignore this field, we will return data for all categories unless you specify audits
use this field to get data for specific categories you indicate hereseo, performance, best_practices, accessibility"
},
"audits": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Lighthouse audits
optional field
audits are individual tests Lighthouse runs for each specific feature/optimization/metric to produce a numeric score (see official definition)if you ignore this field, we will return data for all audits
use this field to get data for specific audits you indicate herecategories, you can use this field to get data for the specified audits only
for example, if you ignore \"categories\" and specify \"audits\": [\"metrics/cumulative-layout-shift\",\"metrics/largest-contentful-paint\",\"metrics/total-blocking-time\"], you will get data only for these audits
for example, if you specify \"categories\": [\"seo\"] and \"audits\": [\"metrics/cumulative-layout-shift\",\"metrics/largest-contentful-paint\",\"metrics/total-blocking-time\"], you will get only these audits under \"performance\" and all audits under \"seo\"
optional field
you can obtain the results specific to a certain Lighthouse version by specifying its number
the list of available versions is available through the Lighthouse Versions endpoint"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "lighthouse language name
optional field
you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages
default value:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "lighthouse language code
optional field
you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/on_page/lighthouse/languages
default value:en"
},
"custom_user_agent": {
"type": [
"string",
"null"
],
"description": "custom user agent
optional field
specify the custom user agent used by the browser when running the Lighthouse audit;
can be specified with up to 254 characters;"
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen width
optional field
set the screen width of the browser used for the Lighthouse audit to emulate a specific device;
can be specified within the following range: 240–9999;",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen height
optional field
set the screen height of the browser used for the Lighthouse audit to emulate a specific device;
can be specified within the following range: 240–9999;"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser screen scale factor
optional field
set the device pixel ratio of the browser used for the Lighthouse audit;
can be specified within the following range: 0.5–3;"
},
"browser_network_throttling_method": {
"type": [
"string",
"null"
],
"description": "browser network throttling method
optional field
defines the method used to apply throttling during the Lighthouse audit;
possible vaules:simulate - calculates estimated performance metrics without applying explicit throttling;devtools - applies the throttling settings specified in browser_network_throttling and browser_cpu_throttling_multiplier;provided - uses the network conditions of the crawling environment;"
},
"browser_cpu_throttling_multiplier": {
"type": [
"number",
"null"
],
"description": "browser CPU throttling multiplier
required if browser_network_throttling_method is set to devtools;
set the CPU throttling multiplier to simulate device performance conditions during the Lighthouse audit;
can be specified within the following range: 1–4;
Note: this parameter is applied only when browser_network_throttling_method is set to devtools;"
},
"browser_network_throttling": {
"type": [
"string",
"null"
],
"description": "browser network throttling
required if browser_network_throttling_method is set to devtools;
set the network throttling profile to simulate connection speed conditions during the Lighthouse audit;
possible values: no_throttling, fast_4g, slow_4g, regular_3g, pc;
Note: this parameter is applied only when browser_network_throttling_method is set to devtools;"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23learn more on our Help Center"
}
},
"example": [
{
"url": "https://dataforseo.com",
"for_mobile": true,
"tag": "some_string_123",
"pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
}
]
},
"Response463397119C53_OnPageLighthouseTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
}
}
}
}
}
]
},
"Response463397119C53_OnPageLighthouseTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_json": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the OnPage Lighthouse JSON task"
}
}
},
"Response463397119C53_OnPageLighthouseVersionsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseVersionsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseVersionsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLighthouseVersionsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageLighthouseVersionsResultInfo": {
"type": "object",
"properties": {
"availible_versions": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AvailibleVersions"
}
]
}
}
}
},
"Response463397119C53_AvailibleVersions": {
"type": "object",
"properties": {
"version": {
"type": [
"string",
"null"
],
"description": "lighthouse version"
},
"default": {
"type": [
"boolean",
"null"
],
"description": "the version is used by default
if false, the version is not used by default and should be specified in the corresponding field of the POST request if necessary"
}
}
},
"Provider463397119C53_OnPageLinksRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"page_from": {
"type": [
"string",
"null"
],
"description": "relative page URL
optional field
if you use this field, the API response will contain only links from the specified page
note that in this field you can specify relative URLs only"
},
"page_to": {
"type": [
"string",
"null"
],
"description": "relative page URL
optional field
if you use this field, the API response will contain only internal links pointing to the specified page
note that in this field you can specify relative URLs only"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned links
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned links
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten links in the results array will be omitted and the data will be provided for the successive links"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"direction\",\"=\",\"external\"][[\"domain_to\",\"<>\",\"example.com\"],
\"and\",
[\"link_from\",\"not_like\",\"%example.com/blog%\"]][[\"direction\",\"=\",\"external\"],
\"and\",
[[\"link_from\",\"like\",\"%example.com/blog%\"],\"or\",[\"link_from\",\"like\",\"%example.com/help%\"]]]
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"page_from": "/apis/google-trends-api",
"filters": [
[
"dofollow",
"=",
true
],
"and",
[
"direction",
"=",
"external"
]
],
"limit": 10
}
]
},
"Response463397119C53_OnPageLinksResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLinksTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageLinksTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageLinksResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageLinksResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"search_after_token": {
"type": [
"string",
"null"
]
},
"current_offset": {
"type": [
"integer",
"null"
]
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_BaseOnPageLinkItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"domain_from": {
"type": [
"string",
"null"
],
"description": "referring domain
the link was found on this domain"
},
"domain_to": {
"type": [
"string",
"null"
],
"description": "referenced domain
the link is pointing to this domain"
},
"page_from": {
"type": [
"string",
"null"
],
"description": "referring page
relative URL of the page on which the link was found"
},
"page_to": {
"type": [
"string",
"null"
],
"description": "referenced page
relative URL of the page to which the link is pointing"
},
"link_from": {
"type": [
"string",
"null"
],
"description": "referring page
absolute URL of the page on which the link was found"
},
"link_to": {
"type": [
"string",
"null"
],
"description": "referenced page
absolute URL of the page to which the link is pointing"
},
"dofollow": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the link is dofollow
if the value is true, the link doesn't have a rel=\"nofollow\" attribute"
},
"page_from_scheme": {
"type": [
"string",
"null"
],
"description": "url scheme of the referring page"
},
"page_to_scheme": {
"type": [
"string",
"null"
],
"description": "url scheme of the referenced page"
},
"direction": {
"type": [
"string",
"null"
],
"description": "direction of the link
possible values: internal, external"
},
"is_broken": {
"type": [
"boolean",
"null"
],
"description": "link is broken
indicates whether a link is directing to a broken page or resource"
},
"is_link_relation_conflict": {
"type": [
"boolean",
"null"
],
"description": "indicates that the link may have a conflict with another link
if true, at least one link pointing to link_to has a rel=\"nofollow\" attribute and at least one is dofollow"
},
"page_to_status_code": {
"type": [
"integer",
"null"
],
"description": "status code of the referenced page
status code of the page to which the link is pointing"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"anchor": "#/components/schemas/Response463397119C53_OnPageAnchorLinkItem",
"image": "#/components/schemas/Response463397119C53_OnPageImageLinkItem",
"canonical": "#/components/schemas/Response463397119C53_OnPageCanonicalLinkItem",
"alternate": "#/components/schemas/Response463397119C53_OnPageAlternateLinkItem",
"link": "#/components/schemas/Response463397119C53_OnPageLinkLinkItem",
"redirect": "#/components/schemas/Response463397119C53_OnPageRedirectLinkItem",
"meta": "#/components/schemas/Response463397119C53_OnPageMetaLinkItem"
}
}
},
"Response463397119C53_OnPageAnchorLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object",
"properties": {
"link_attribute": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "link attribute added to external link
indicates link attributes added to the link_to on the page_from
example:[\"ugc\",\"noopener\"]"
},
"text": {
"type": [
"string",
"null"
],
"description": "anchor text"
}
}
}
]
},
"Response463397119C53_OnPageImageLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object",
"properties": {
"link_attribute": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "link attribute added to external link
indicates link attributes added to the link_to on the page_from
example:[\"ugc\",\"noopener\"]"
},
"text": {
"type": [
"string",
"null"
],
"description": "anchor text"
},
"image_alt": {
"type": [
"string",
"null"
],
"description": "alternative text for the image"
},
"image_src": {
"type": [
"string",
"null"
],
"description": "url of the image"
}
}
}
]
},
"Response463397119C53_OnPageCanonicalLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object"
}
]
},
"Response463397119C53_OnPageAlternateLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object",
"properties": {
"is_valid_hreflang": {
"type": [
"boolean",
"null"
],
"description": "hreflang validity status
indicates whether the hreflang attribute is correctly implemented"
},
"hreflang": {
"type": [
"string",
"null"
],
"description": "hreflang attribute value
language and optional country code specified in the hreflang attribute
example: \"en-US\", \"fr\""
}
}
}
]
},
"Response463397119C53_OnPageLinkLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object"
}
]
},
"Response463397119C53_OnPageRedirectLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object"
}
]
},
"Response463397119C53_OnPageMetaLinkItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageLinkItem"
}
]
},
{
"type": "object"
}
]
},
"Provider463397119C53_OnPageMicrodataRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": "string",
"description": "resource URL
required field
you can get this URL in the response of the Pages endpoint
example:https://dataforseo.com/apis"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "02241700-1535-0216-0000-034137259bc1",
"url": "https://dataforseo.com/apis"
}
]
},
"Response463397119C53_OnPageMicrodataResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageMicrodataTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageMicrodataTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageMicrodataResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageMicrodataResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"test_summary": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TestSummary"
}
],
"description": "microdata validation test results"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageMicrodataInfoItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_TestSummary": {
"type": "object",
"properties": {
"fatal": {
"type": [
"integer",
"null"
],
"description": "number of fatal microdata errors"
},
"error": {
"type": [
"integer",
"null"
],
"description": "number of serious microdata errors"
},
"warning": {
"type": [
"integer",
"null"
],
"description": "number of microdata warnings"
},
"info": {
"type": [
"integer",
"null"
],
"description": "number of microdata information flags"
}
}
},
"Response463397119C53_OnPageMicrodataInfoItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"inspection_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MicrodataInspectionInfo"
}
],
"description": "information related to microdata validation"
}
}
},
"Response463397119C53_MicrodataInspectionInfo": {
"type": "object",
"properties": {
"types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "parent microdata types
for a full list of available types, please visit schema.org"
},
"fields": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MicrodataFieldsInfo"
}
]
},
"description": "microdata fields
an array of objects containing data fields related to the certain microdata type"
}
}
},
"Response463397119C53_MicrodataFieldsInfo": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "field name
name of the data field"
},
"types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "list of microdata types"
},
"value": {
"type": [
"string",
"null"
],
"description": "microdata value\nmicrodata value specified on a target web page"
},
"test_results": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MessageInfo"
}
],
"description": "microdata validation test results
sub-type microdata test results that contain detected errors and related messages"
},
"fields": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MicrodataFieldsInfo"
}
]
},
"description": "microdata fields
an array of objects containing data fields related to the certain microdata type"
}
}
},
"Response463397119C53_MessageInfo": {
"type": "object",
"properties": {
"level": {
"type": [
"string",
"null"
],
"description": "level of error\ncan take the following values: fatal, error, warning, info"
},
"message": {
"type": [
"string",
"null"
],
"description": "message associated with an error\nmessage providing the details of the detected error"
}
}
},
"Provider463397119C53_OnPageNonIndexableRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[[\"reason\",\"<>\",\"robots_txt\"],
\"and\",
[\"url\",\"not_like\",\"%/wp-admin/%\"]][[\"url\",\"not_like\",\"%/wp-admin/%\"],
\"and\",
[[\"reason\",\"<>\",\"meta_tag\"],\"or\",[\"reason\",\"<>\",\"http_header\"]]]
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageNonIndexableItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageNonIndexableItem": {
"type": "object",
"properties": {
"reason": {
"type": [
"string",
"null"
],
"description": "the reason why the page is non-indexable
can take the following values: robots_txt, meta_tag, http_header, attribute, too_many_redirects"
},
"url": {
"type": [
"string",
"null"
],
"description": "url of the non-indexable page"
}
}
},
"Provider463397119C53_OnPagePageScreenshotRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "page url
required field
absolute URL of the page to snap
note: if the URL you indicate here returns a 404 status code or the indicated value is not a valid URL, you will obtain \"error_message\":\"Screenshot is empty\" in the response array"
},
"accept_language": {
"type": [
"string",
"null"
],
"description": "language header for accessing the website
optional field
all locale formats are supported (xx, xx-XX, xxx-XX, etc.)
note: if you do not specify this parameter, some websites may deny access; in this case, you will obtain \"error_message\":\"Screenshot is empty\" in the response array"
},
"custom_user_agent": {
"type": [
"string",
"null"
],
"description": "custom user agent
optional field
custom user agent for crawling a website
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36
default value: Mozilla/5.0 (compatible; RSiteAuditor)"
},
"browser_preset": {
"type": [
"string",
"null"
],
"description": "preset for browser screen parameters
optional field
if you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factordesktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920browser_screen_height: 1080browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390browser_screen_height: 844browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024browser_screen_height: 1366browser_screen_scale_factor: 2enable_browser_rendering, enable_javascript, load_resources, and enable_xhr parameters are always enabled."
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen width
optional field
you can set a custom browser screen width to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;240
maximum value, in pixels: 9999",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen height
optional field
you can set a custom browser screen height to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;240
maximum value, in pixels: 9999"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser screen scale factor
optional field
you can set a custom browser screen resolution ratio to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;0.5
maximum value: 3"
},
"full_page_screenshot": {
"type": [
"boolean",
"null"
],
"description": "take a screenshot of the full page
optional field
set to false if you want to capture only the part of the page displayed before scrolling
default value: true"
},
"disable_cookie_popup": {
"type": [
"boolean",
"null"
],
"description": "disable the cookie popup
optional field
set to true if you want to disable the popup requesting cookie consent from the user;
default value: false"
},
"switch_pool": {
"type": [
"boolean",
"null"
],
"description": "switch proxy pool
optional field
if true, additional proxy pools will be used to obtain the requested data;
the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors"
},
"ip_pool_for_scan": {
"type": [
"string",
"null"
],
"description": "proxy pool
optional field
you can choose a location of the proxy pool that will be used to obtain the requested data;
the parameter can be used if page content is inaccessible in one of the locations, resulting in occasional site_unreachable errors
possible values: us, de"
}
},
"example": [
{
"url": "https://dataforseo.com/apis"
}
]
},
"Response463397119C53_OnPagePageScreenshotResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPagePageScreenshotTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPagePageScreenshotTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPagePageScreenshotResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPagePageScreenshotResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"error_message": {
"type": [
"string",
"null"
],
"description": "error message
if the url you indicated returns a 404 status code or is not a valid URL, you will obtain \"error_message\":\"Screenshot is empty\"
if no error is encountered, the value will be null"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ScreenshotItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_ScreenshotItem": {
"type": "object",
"properties": {
"image": {
"type": [
"string",
"null"
],
"description": "screenshot of the requested page
URL of the page screenshot on the DataForSEO storage
note: the page screenshot saved on the DataForSEO storage only remains accessible for one day after making the request"
}
}
},
"Provider463397119C53_OnPagePagesRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the taskrequired fieldyou can get this ID in the response of the Task POST endpointexample:\"07131248-1535-0216-1000-17384017ad04\""
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pagesoptional fielddefault value: 100maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pagesoptional fielddefault value: 0maximum value: 2000000if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parametersoptional fieldyou can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_likeyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"meta.external_links_count\",\"<=\",50][\"url\",\"like\",\"https://dataforseo.com/apis/dataforseo-labs-api\"][[\"checks.high_waiting_time\",\"=\",false],\"and\",[\"resource_type\",\"=\",\"html\"]][[\"page_timing.duration_time\",\"<\",100],\"and\",[[\"checks.large_page_size\",\"=\",false],\"or\",[\"checks.high_waiting_time\",\"=\",false]]]The full list of possible filters is available by this link."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rulesoptional fieldyou can use the same values as in the filters array to sort the resultspossible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending orderyou should use a comma to set up a sorting typeexample:[\"meta.external_links_count,desc\"]note that you can set no more than three sorting rules in a single requestyou should use a comma to separate several sorting rulesexample:[\"page_timing.dom_complete,asc\",\"size,desc\"]"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requestsoptional fieldprovided in the identical filed of the response to each request;use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"filters": [
[
"resource_type",
"=",
"html"
],
"and",
[
"meta.scripts_count",
">",
40
]
],
"order_by": [
"meta.content.plain_text_word_count,desc"
],
"limit": 10
}
]
},
"Response463397119C53_OnPagePagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPagePagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPagePagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPagePagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPagePagesResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling sessionpossible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"search_after_token": {
"type": [
"string",
"null"
]
},
"current_offset": {
"type": [
"integer",
"null"
]
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
"description": "items array"
}
}
},
"Provider463397119C53_OnPagePagesByResourceRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": "string",
"description": "resource URL
required field
you can get this URL in the response of the Resources endpoint
example:https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"meta.external_links_count\",\"<=\",50][\"url\",\"like\",\"https://dataforseo.com/apis/dataforseo-labs-api\"][[\"checks.high_waiting_time\",\"=\",false],
\"and\",[\"resource_type\",\"=\",\"html\"]][[\"page_timing.duration_time\",\"<\",100],\"and\",[[\"checks.large_page_size\",\"=\",false],\"or\",[\"checks.high_waiting_time\",\"=\",false]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"meta.external_links_count,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"page_timing.dom_complete,asc\",\"size,desc\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "02241700-1535-0216-0000-034137259bc1",
"url": "https://www.etsy.com/about/jobs.workco2018.js?"
}
]
},
"Response463397119C53_OnPagePagesByResourceResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPagePagesByResourceTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPagePagesByResourceTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPagePagesByResourceResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPagePagesByResourceResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageHtmlResourceItem"
}
]
},
"description": "items array"
}
}
},
"Provider463397119C53_OnPageRawHtmlRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": "string",
"description": "page url
required field
the absolute URL of a page to request HTML
Note: this field is optional if the task was set using the Instant Pages endpoint"
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"url": "https://dataforseo.com/apis"
}
]
},
"Response463397119C53_OnPageRawHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRawHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageRawHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRawHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageRawHtmlResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRawHtmlItem"
}
],
"description": "items object"
}
}
},
"Response463397119C53_OnPageRawHtmlItem": {
"type": "object",
"properties": {
"html": {
"type": [
"string",
"null"
],
"description": "HTML_pagen"
}
}
},
"Provider463397119C53_OnPageRedirectChainsRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL
optional field
absolute URL of the target page
if you use this field, the API response will return only redirect chains which contain the specified URL"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned redirect chains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned redirect chains
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten redirect chains in the results array will be omitted and the data will be provided for the successive redirect chains"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can use only one filtering parameter with this endpointis_redirect_loop
the following operators are supported:regex, not_regex, =, <>[\"is_redirect_loop\",\"=\",\"true\"][\"is_redirect_loop\",\"<>\",\"false\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "03051327-4536-0216-1000-3b458a2cfcca",
"url": "https://test_rdr.dataforseo.com/a/"
}
]
},
"Response463397119C53_OnPageRedirectChainsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRedirectChainsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageRedirectChainsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRedirectChainsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageRedirectChainsResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items in the database",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRedirectChainsItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageRedirectChainsItem": {
"type": "object",
"properties": {
"is_redirect_loop": {
"type": [
"boolean",
"null"
],
"description": "indicates if redirects in chain start and end at the same URL
if true, the last URL from the chain redirects back to the original URL"
},
"chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageRedirectLinkItem"
}
]
},
"description": "contains links that form a chain"
}
}
},
"Provider463397119C53_OnPageResourcesRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": [
"string",
"null"
],
"description": "page URL
optional field
specify this field if you want to get the resources for a specific page
note that to obtain resource's meta from a particular URL, you should specify the URL in this field;
if you do not indicate a url when setting a task, resource's meta in the results will be returned based on the data from the page where our crawler first saw the resource"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned resources
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned resources
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten resources in the results array will be omitted and the data will be provided for the successive resources"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"resource_type\",\"=\",\"stylesheet\"][[\"resource_type\",\"=\",\"image\"],
\"and\",[\"checks.is_https\",\"=\",false]][[\"fetch_timing.duration_time\",\">\",1],\"and\",[[\"total_transfer_size\",\">\",100],\"or\",[\"checks.high_loading_time\",\"=\",true]]]
optional field
you can use this field to obtain resources from pages matching to the defined parameters
you can apply the same filters here as available for the pages endpoint
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"checks.no_image_title\",\"=\",true]"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"size,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"size,desc\",\"fetch_timing.fetch_end,desc\"]"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "07281559-0695-0216-0000-c269be8b7592",
"filters": [
[
"resource_type",
"=",
"image"
],
"and",
[
"size",
">",
100000
]
],
"order_by": [
"size,desc"
],
"limit": 10
}
]
},
"Response463397119C53_OnPageResourcesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourcesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageResourcesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourcesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageResourcesResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"search_after_token": {
"type": [
"string",
"null"
]
},
"current_offset": {
"type": [
"integer",
"null"
]
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of relevant items crawled",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseOnPageResourceItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageSummaryResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageSummaryTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageSummaryTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageSummaryResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageSummaryResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"crawl_gateway_address": {
"type": [
"string",
"null"
],
"description": "crawler ip address
displays the IP address used by the crawler to initiate the current crawling session
you can find the full list of IPs used by our crawler in the Overview section"
},
"crawl_stop_reason": {
"type": [
"string",
"null"
],
"description": "reason why the crawling stopped
information about the reason why the crawling process stopped;
possible values:limit_exceeded - the limit set in the max_crawl_pages was exceeded;empty_queue - all URLs in the queue were crawled;force_stopped - the crawling process was halted using the On Page API Force Stop function;unexpected_exception - an internal error was encountered while crawling the target, contact support for more info"
},
"domain_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DomainInfo"
}
],
"description": "domain-wide info
on-page information about the target domain and crawling process"
},
"page_metrics": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PageMetrics"
}
],
"description": "page-specific info
metrics information on the target website pages"
}
}
},
"Response463397119C53_DomainInfo": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "domain name"
},
"cms": {
"type": [
"string",
"null"
],
"description": "content management system
content management system identified on a website
the content of_the generator_meta tag
the data is taken from the first random page that returns the 200 response code
if our crawler was unable to identify the cms, the value would be nulln"
},
"ip": {
"type": [
"string",
"null"
],
"description": "domain ip address"
},
"server": {
"type": [
"string",
"null"
],
"description": "website server
the version of the server detected on a website
the content of the server header
the information is taken from the first page which response code is 200"
},
"crawl_start": {
"type": [
"string",
"null"
],
"description": "time when the crawling start
date and time when the website was sent for crawling
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"crawl_end": {
"type": [
"string",
"null"
],
"description": "time when the crawling ended
date and time when the crawling was finished
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00
Note: informative only if \"crawl_progress\" is \"finished\"
if \"crawl_progress\" is in_progress, the value will be null"
},
"extended_crawl_status": {
"type": [
"string",
"null"
],
"description": "crawl status and errors
indicates the reason why a website was not crawled;
can take the following values:no_errors - no crawling errors were detected;site_unreachable - our crawler could not reach a website and thus was not able to obtain a status code;invalid_page_status_code - status code of the first crawled page >= 400;forbidden_meta_tag - the first crawled page contains the <meta robots=\"noindex\"> tag;forbidden_robots - robots.txt forbids crawling the page;forbidden_http_header - HTTP header of the page contains \"X-Robots-Tag: noindex\" ;too_many_redirects - the first crawled page has more than 10 redirects;unknown - the reason is unknown"
},
"ssl_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SslInfo"
}
],
"description": "ssl certificate info
information about the Secure Sockets Layer protocol detected on a website"
},
"checks": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"boolean",
"null"
]
},
"description": "website checks
other on-page check-ups related to the website"
},
"total_pages": {
"type": [
"integer",
"null"
],
"description": "total crawled pages
the total number of crawled pages",
"format": "int64"
},
"total_uncrawlable_resources": {
"type": [
"integer",
"null"
],
"description": "total uncrawlable resources
the total number of resources that could not be crawled;
the resource is considered uncrawlable when the actual content type of the resource doesn't match the content type expected by the crawler",
"format": "int64"
},
"page_not_found_status_code": {
"type": [
"integer",
"null"
],
"description": "status code returned by a non-existent page
in most cases, it is recommended a server returns a 404 response code"
},
"canonicalization_status_code": {
"type": [
"integer",
"null"
],
"description": "status code returned by a canonicalized page
the checkup of the server behavior when our crawler tries to access the website via IP;
in most cases, it is recommended that canonicalized pages respond with a 301 or 302 status code"
},
"directory_browsing_status_code": {
"type": [
"integer",
"null"
],
"description": "status code returned by a directory
the status code returned by a directory page on a target website
in most cases, it is recommended that directories respond with a 403 or 401 status code"
},
"www_redirect_status_code": {
"type": [
"integer",
"null"
],
"description": "redirect status code
the status code of the www to non-www redirect
in most cases, it is recommended that redirect returns a 301 status code"
},
"main_domain": {
"type": [
"string",
"null"
],
"description": "root domain name"
}
}
},
"Response463397119C53_SslInfo": {
"type": "object",
"properties": {
"valid_certificate": {
"type": [
"boolean",
"null"
],
"description": "ssl certificate validity
indicates whether the ssl certificate detected on a website is not expired, suspended, revoked or invalid"
},
"certificate_issuer": {
"type": [
"string",
"null"
],
"description": "ssl certificate authority
the entity that issued the detected ssl certificate"
},
"certificate_subject": {
"type": [
"string",
"null"
],
"description": "ssl certificate subject
the entity associated with the public key"
},
"certificate_version": {
"type": [
"integer",
"null"
],
"description": "ssl certificate version
indicates the version of X.509 used by an ssl certificate"
},
"certificate_hash": {
"type": [
"string",
"null"
],
"description": "ssl certificate hash
the version of the ssl certificate's hash function"
},
"certificate_expiration_date": {
"type": [
"string",
"null"
],
"description": "ssl certificate expiration date
the date and time when the ssl certificate expires
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_PageMetrics": {
"type": "object",
"properties": {
"links_external": {
"type": [
"integer",
"null"
],
"description": "number of external links
the number of links pointing to other websites"
},
"links_internal": {
"type": [
"integer",
"null"
],
"description": "number of internal links
the number of links pointing to other pages within the target website"
},
"duplicate_title": {
"type": [
"integer",
"null"
],
"description": "number of pages with duplicate titles"
},
"duplicate_description": {
"type": [
"integer",
"null"
],
"description": "number of pages with duplicate descriptions"
},
"duplicate_content": {
"type": [
"integer",
"null"
],
"description": "number of pages with duplicate content"
},
"broken_links": {
"type": [
"integer",
"null"
],
"description": "number of broken links
number of broken links across all crawled pages on a target website"
},
"broken_resources": {
"type": [
"integer",
"null"
],
"description": "number of broken resources
the number of images and other resources with broken links"
},
"links_relation_conflict": {
"type": [
"integer",
"null"
],
"description": "number of links present on the target website that may have a conflict
for example, if \"links_relation_conflict\": 2, the target website is referring to the same source by at least one internal link with the rel=\"nofollow\" attribute and by at least one dofollow link"
},
"redirect_loop": {
"type": [
"integer",
"null"
],
"description": "number of redirect chains that start and end at the same URL
number of redirect chains where the destination URL redirects back to the original URL"
},
"onpage_score": {
"type": [
"number",
"null"
],
"description": "shows how website is optimized on a 100-point scale
this field shows how website is optimized considering critical on-page issues and warnings detected;100 is the highest possible score that means website does not have any critical on-page issues and important warnings;
note that this value depends on the number of crawled pages;
learn more about how the metric is calculated in this help center article"
},
"non_indexable": {
"type": [
"integer",
"null"
],
"description": "number of non-indexable pages
number of pages that are blocked from being indexed by Google and other search engines by robots.txt, HTTP headers, or meta tags settings;
you can receive a list of non-indexable URLs using this endpoint"
},
"checks": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "page-specific on-page check-ups"
}
}
},
"Provider463397119C53_OnPageTaskPostRequestInfo": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "target domain
required field
domain name should be specified without https:// and www.
if you specify the page URL, the results will be returned for the domain included in the URL"
},
"max_crawl_pages": {
"type": "integer",
"description": "crawled pages limit
required field
the number of pages to crawl on the specified domain
Note:
if you set max_crawl_pages to 1 and do not specify start_url or set a homepage in it, the following sitewide checks will be disabled:test_canonicalization, enable_www_redirect_check, test_hidden_server_signature, test_page_not_found, test_directory_browsing, test_https_redirect
to enable them anyway, set force_sitewide_checks to trueif you set max_crawl_pages to 1 and specify start_url other than a homepage, all sitewide checks will be disabled;
to enable them anyway, set force_sitewide_checks to true"
},
"start_url": {
"type": [
"string",
"null"
],
"description": "the first url to crawl
optional field
Note: you should specify an absolute URL
if you want to crawl a single page, specify its URL in this field and additionally set the max_crawl_pages parameter to 1
you can also use the live Instant Pages endpoint to get page-specific data"
},
"force_sitewide_checks": {
"type": [
"boolean",
"null"
],
"description": "enable sitewide checks when crawling a single page
optional field
set to true to get data on sitewide checks when crawling a single page;
default value: false"
},
"priority_urls": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "urls to be crawled bypassing the queue
optional field
URLs specified in this array will be crawled in the first instance, bypassing the crawling queue;
Note: you should specify the absolute URL;
you can specify up to 20 URLs;
all URLs in the array must belong to the target domain;
subdomains will be ignored unless the allow_subdomains parameter is set to trueexample:
`\"priority_urls\": [
\"https://dataforseo.com/apis/serp-api\",
\"https://dataforseo.com/contact\"
]`"
},
"max_crawl_depth": {
"type": [
"integer",
"null"
],
"description": "crawl depth
optional field
the linking depth of the pages to crawl;
for example, starting page of the crawl is level 0, pages that have links from that page are level 1, etc."
},
"crawl_delay": {
"type": [
"integer",
"null"
],
"description": "delay between hits, ms
optional field
the custom delay between crawler hits to the server
default value: 2000"
},
"store_raw_html": {
"type": [
"boolean",
"null"
],
"description": "store HTML of crawled pages
optional field
set to true if you want to get the HTML of the page using the OnPage Raw HTML endpoint
default value: false"
},
"enable_content_parsing": {
"type": [
"boolean",
"null"
],
"description": "parse content on crawled pages
optional field
set to true to use the OnPage Content Parsing endpoint
default value: false"
},
"support_cookies": {
"type": [
"boolean",
"null"
],
"description": "support cookies on crawled pages
optional field
set to true to support cookies when crawling the pages
default value: false"
},
"accept_language": {
"type": [
"string",
"null"
],
"description": "language header for accessing the website
optional field
all locale formats are supported (xx, xx-XX, xxx-XX, etc.)
Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the \"type\":\"broken in the response array"
},
"custom_robots_txt": {
"type": [
"string",
"null"
],
"description": "custom robots.txt settings
optional field
example: Disallow: /directory1/"
},
"robots_txt_merge_mode": {
"type": [
"string",
"null"
],
"description": "merge with or override robots.txt settings
optional field
possible values: merge, override;
set to override if you want to ignore website crawling restrictions and other robots.txt settings
default value: merge;
Note: if set to override, specify the custom_robots_txt parameter"
},
"custom_user_agent": {
"type": [
"string",
"null"
],
"description": "custom user agent
optional field
custom user agent for crawling a website
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36
default value: Mozilla/5.0 (compatible; RSiteAuditor)"
},
"browser_preset": {
"type": [
"string",
"null"
],
"description": "preset for browser screen parameters
optional field
if you use this field, you don't need to indicate browser_screen_width, browser_screen_height, browser_screen_scale_factorpossible values:desktop, mobile, tabletdesktop preset will apply the following values:browser_screen_width: 1920browser_screen_height: 1080browser_screen_scale_factor: 1mobile preset will apply the following values:browser_screen_width: 390browser_screen_height: 844browser_screen_scale_factor: 3tablet preset will apply the following values:browser_screen_width: 1024browser_screen_height: 1366browser_screen_scale_factor: 2
Note: to use this parameter, set enable_javascript or enable_browser_rendering to true"
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen width
optional field
you can set a custom browser screen width to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240
maximum value, in pixels: 9999",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen height
optional field
you can set a custom browser screen height to perform an audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value, in pixels: 240
maximum value, in pixels: 9999"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser screen scale factor
optional field
you can set a custom browser screen resolution ratio to perform audit for a particular device;
if you use this field, you don't need to indicate browser_preset as it will be ignored;
Note: to use this parameter, set enable_javascript or enable_browser_rendering to trueminimum value: 0.5
maximum value: 3"
},
"respect_sitemap": {
"type": [
"boolean",
"null"
],
"description": "respect sitemap when crawling
optional field
set to true if you want to follow the order of pages indicated in the primary sitemap when crawling;
default value: false
Note: if set to true, the click_depth value in the API response will equal 0;
the max_crawl_depth field of the request will be ignored, you can specify the number of pages to crawl using the max_crawl_pages parameter"
},
"custom_sitemap": {
"type": [
"string",
"null"
],
"description": "custom sitemap url
optional field
the URL of the page where the alternative sitemap is located
Note: if you want to use this parameter, respect_sitemap should be true"
},
"crawl_sitemap_only": {
"type": [
"boolean",
"null"
],
"description": "crawl only pages indicated in the sitemap
optional field
set to true if you want to crawl only the pages indicated in the sitemap
if you set this parameter to true and do not specify custom_sitemap, we will crawl the default sitemap
default value: false
Note: if you want to use this parameter, respect_sitemap should be true"
},
"load_resources": {
"type": [
"boolean",
"null"
],
"description": "load resources
optional field
set to true if you want to load image, stylesheets, scripts, and broken resources
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"enable_www_redirect_check": {
"type": [
"boolean",
"null"
],
"description": "check if the domain implemented the www redirection
optional field
set to true if you want to check if the requested domain implemented the www to non-www or non-www to www redirect;
default value: false"
},
"enable_javascript": {
"type": [
"boolean",
"null"
],
"description": "load javascript on a page
optional field
set to true if you want to load the scripts available on a page
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"enable_xhr": {
"type": [
"boolean",
"null"
],
"description": "enable XMLHttpRequest on a page
optional field
set to true if you want our crawler to request data from a web server using the XMLHttpRequest object
default value: false;if you use this field, enable_javascript must be set to true;"
},
"enable_browser_rendering": {
"type": [
"boolean",
"null"
],
"description": "emulate browser rendering to measure Core Web Vitals
optional field
by using this parameter you will be able to emulate a browser when loading a web page;enable_browser_rendering loads styles, images, fonts, animations, videos, and other resources on a page;
default value: false
set to true to obtain Core Web Vitals (FID, CLS, LCP) metrics in the response;
if you use this field, enable_javascript, and load_resources parameters must be set to true
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article; the cost can be calculated on the Pricing Page"
},
"disable_cookie_popup": {
"type": [
"boolean",
"null"
],
"description": "disable the cookie popup
optional field
set to true if you want to disable the popup requesting cookie consent from the user;
default value:false"
},
"custom_js": {
"type": [
"string",
"null"
],
"description": "custom javascript
optional field
Note that the execution time for the script you enter here should be 700 ms maximum, for example, you can use the following JS snippet to check if the website contains Google Tag Manager as a scr attribute:let meta = { haveGoogleAnalytics: false, haveTagManager: false };rnfor (var i = 0; i < document.scripts.length; i++) {rn let src = document.scripts[i].getAttribute(\"src\");rn if (src != undefined) {rn if (src.indexOf(\"analytics.js\") >= 0)rn meta.haveGoogleAnalytics = true;rntif (src.indexOf(\"gtm.js\") >= 0)rn meta.haveTagManager = true;rn }rn}rnmeta;the returned value depends on what you specified in this field. For instance, if you specify the following script:
`meta = {}; meta.url = document.URL; meta.test = 'test'; meta;`
as a response you will receive the following data:
`\"custom_js_response\": {
\"url\": \"https://dataforseo.com/\",
\"test\": \"test\"
}`
Note: the length of the script you enter must be no more than 2000 characters"
},
"validate_micromarkup": {
"type": [
"boolean",
"null"
],
"description": "enable microdata validation
optional field
set to true if you want to use the OnPage API Microdata endpoint
default value: false"
},
"allow_subdomains": {
"type": [
"boolean",
"null"
],
"description": "include pages on subdomains
optional field
set to true if you want to crawl all subdomains of a target website
default value: false"
},
"allowed_subdomains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "subdomains to crawl
optional field
specify subdomains that you want to crawl
example: [\"blog.site.com\", \"my.site.com\", \"shop.site.com\"]
Note: to use this parameter, the allow_subdomains parameter should be set to false;
otherwise, the content of allowed_subdomains field will be ignored and the results will be returned for all subdomains"
},
"disallowed_subdomains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "subdomains not to crawl
optional field
specify subdomains that you don't want to crawl
example: [\"status.site.com\", \"docs.site.com\"]
Note: to use this parameter, the allow_subdomains parameter should be set to true"
},
"check_spell": {
"type": [
"boolean",
"null"
],
"description": "check spelling
optional field
set to true to check spelling on a website using Hunspell library
default value: false"
},
"check_spell_language": {
"type": [
"string",
"null"
],
"description": "language of the spell check
optional field
supported languages: 'hy', 'eu', 'bg', 'ca', 'hr', 'cs', 'da', 'nl', 'en', 'eo', 'et', 'fo', 'fa', 'fr', 'fy', 'gl', 'ka', 'de', 'el', 'he', 'hu', 'is', 'ia', 'ga', 'it', 'rw', 'la', 'lv', 'lt', 'mk', 'mn', 'ne', 'nb', 'nn', 'pl', 'pt', 'ro', 'gd', 'sr', 'sk', 'sl', 'es', 'sv', 'tr', 'tk', 'uk', 'vi'
Note: if no language is specified, it will be set automatically based on page content"
},
"check_spell_exceptions": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "words excluded from spell check
optional field
specify the words that you want to exclude from spell check
maximum word length: 100 characters
maximum amount of words: 1000
example: \"SERP\", \"minifiers\", \"JavaScript\""
},
"calculate_keyword_density": {
"type": [
"boolean",
"null"
],
"description": "calculate keyword density for the target domain
optional field
set to true if you want to calculate keyword density for website pages
default value: false
Note: if you use this parameter, additional charges will apply; learn more about the cost of tasks with this parameter in our help article
once the crawl is completed, you can obtain keyword density values with the Keyword Density endpoint"
},
"checks_threshold": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"description": "custom threshold values for checks
optional field
you can specify custom threshold values for the parameters included in the checks object of OnPage API responses;
Note: only integer threshold values can be modified;
for example, the high_loading_time and large_page_size parameters are set to 3 seconds and 1 megabyte respectively by default;
if you want to change these thresholds to 1 second and 1000 kbytes, use the following snippet:
`\"checks_threshold\": {
\"high_loading_time\": 1,
\"large_page_size\": 1000
}`
available customizable parameters with default values:
`\"title_too_short\", default value: 30, type: \"int\"
\"title_too_long\", default value: 65, type: \"int\"
\"small_page_size\", default value: 1024, type: \"int\"
\"large_page_size\", default value: 1048576 (1024 * 1024), type: \"int\"
\"low_character_count\", default value: 1024, type: \"int\"
\"high_character_count\", default value: 256000 (250 * 1024), type: \"int\"
\"low_content_rate\", default value: 0.1, type: \"float\"
\"high_content_rate\", default value: 0.9, type: \"float\"
\"high_loading_time\", default value: 3000, type: \"int\"
\"high_waiting_time\", default value: 1500, type: \"int\"
\"low_readability_rate\", default value: 15.0, type: \"float\"
\"irrelevant_description\", default value: 0.2, type: \"float\"
\"irrelevant_title\", default value: 0.3, type: \"float\"
\"irrelevant_meta_keywords\", default value: 0.6, type: \"float\"`"
},
"disable_sitewide_checks": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "prevent certain sitewide checks from running
optional field
specify the following checks to prevent them from running on the target website:\"test_page_not_found\"\"test_canonicalization\"\"test_https_redirect\"\"test_directory_browsing\"example:\"disable_sitewide_checks\": [\"test_directory_browsing\", \"test_page_not_found\"]learn more on our help center"
},
"disable_page_checks": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "prevent certain page checks from running
optional field
specify certain checks to prevent them from running and impacting the onpage_scoreexample:\"disable_page_checks\": [\"is_5xx_code\", \"is_4xx_code\"]"
},
"switch_pool": {
"type": [
"boolean",
"null"
],
"description": "switch proxy pool
optional field
if true, additional proxy pools will be used to obtain the requested data;
the parameter can be used if a multitude of tasks is set simultaneously, resulting in occasional rate-limit and/or site_unreachable errors"
},
"return_despite_timeout": {
"type": [
"boolean",
"null"
],
"description": "return data on pages despite the timeout error
optional field
if true, the data will be provided on pages that failed to load within 120 seconds and responded with a timeout error;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_OnPageTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"target": {
"type": [
"string",
"null"
],
"description": "target website specified when setting a task"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
}
}
},
"Provider463397119C53_OnPageUncrawlableResourcesRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned uncrawlable resources
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned uncrawlable resources
optional field
default value: 0
maximum value: 2000000
if you specify the 10 value, the first ten invalid resources in the results array will be omitted and the data will be provided for the successive invalid resources"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"meta.content_type,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"meta.content_type,asc\",\"fetch_time,desc\"]"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example: [[\"meta.content_type\",\"=\",\"image/jpeg\"],
\"and\",
[\"url\",\"not_like\",\"%/help-center/%\"]]
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"current_offset": {
"type": [
"integer",
"null"
]
},
"total_items_count": {
"type": [
"integer",
"null"
],
"description": "total number of uncrawlable resources found
total number of uncrawlable resources found during the crawl of the target domain",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of uncrawlable resources in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageUncrawlableResourcesItem"
}
]
},
"description": "array of uncrawlable resources"
}
}
},
"Response463397119C53_OnPageUncrawlableResourcesItem": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "URL of the uncrawlable resource"
},
"reason": {
"type": [
"string",
"null"
],
"description": "reason the resource is uncrawlable
can take the following values: content_type_inconsistency"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "general status code
you can find the full list of the response codes here
Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions"
},
"fetch_time": {
"type": [
"string",
"null"
],
"description": "date and time when the resource was fetched
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2026-03-09 18:20:32 +00:00"
},
"meta": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_UncrawlableResourcesMeta"
}
],
"description": "metadata of the uncrawlable resource"
}
}
},
"Response463397119C53_UncrawlableResourcesMeta": {
"type": "object",
"properties": {
"content_type": {
"type": [
"string",
"null"
],
"description": "actual content type of the resource"
},
"expected_content_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "expected content types for the resource
list of content types that were expected by the crawler based on how the resource is referenced on the page"
}
}
},
"Provider463397119C53_OnPageWaterfallRequestInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the task
required field
you can get this ID in the response of the Task POST endpoint
example:
\"07131248-1535-0216-1000-17384017ad04\""
},
"url": {
"type": "string",
"description": "page URL
required field
specify the pages you want to receive timing for"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"id": "08101204-0696-0216-0000-644a7b21a48a",
"url": "https://dataforseo.com/tag/broken-links"
}
]
},
"Response463397119C53_OnPageWaterfallResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageWaterfallTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_OnPageWaterfallTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageWaterfallResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_OnPageWaterfallResultInfo": {
"type": "object",
"properties": {
"crawl_progress": {
"type": [
"string",
"null"
],
"description": "status of the crawling session
possible values: in_progress, finished"
},
"crawl_status": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CrawlStatusInfo"
}
],
"description": "details of the crawling session"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageWaterfallItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_OnPageWaterfallItem": {
"type": "object",
"properties": {
"page_url": {
"type": [
"string",
"null"
],
"description": "URL of the page"
},
"time_to_interactive": {
"type": [
"integer",
"null"
],
"description": "Time To Interactive (TTI) metric
the time it takes until the user can interact with a page (in milliseconds)"
},
"dom_complete": {
"type": [
"integer",
"null"
],
"description": "time to load resources
the time it takes until the page and all of its subresources are downloaded (in milliseconds)"
},
"connection_time": {
"type": [
"integer",
"null"
],
"description": "time to connect to a server
the time it takes until the connection with a server is established (in milliseconds)"
},
"time_to_secure_connection": {
"type": [
"integer",
"null"
],
"description": "time to establish a secure connection
the time it takes until the secure connection with a server is established (in milliseconds)"
},
"request_sent_time": {
"type": [
"integer",
"null"
],
"description": "time to send a request to a server
the time it takes until the request to a server is sent (in milliseconds)"
},
"waiting_time": {
"type": [
"integer",
"null"
],
"description": "time to first byte (TTFB) in milliseconds"
},
"download_time": {
"type": [
"integer",
"null"
],
"description": "time it takes for a browser to receive a response (in milliseconds)"
},
"duration_time": {
"type": [
"integer",
"null"
],
"description": "total time it takes until a browser receives a complete response from a server (in milliseconds)"
},
"fetch_start": {
"type": [
"integer",
"null"
],
"description": "time to start downloading the HTML resource
the amount of time the browser needs to start downloading a page"
},
"fetch_end": {
"type": [
"integer",
"null"
],
"description": "time to complete downloading the HTML resource
the amount of time the browser needs to complete downloading a page"
},
"resources": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_WaterfallResourceInfo"
}
]
},
"description": "resource-specific timing
contains separate arrays with timing for each resource found on the page"
}
}
},
"Response463397119C53_WaterfallResourceInfo": {
"type": "object",
"properties": {
"resource_type": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"description": "resource URL"
},
"initiator": {
"type": [
"string",
"null"
],
"description": "resource initiator"
},
"duration_time": {
"type": [
"integer",
"null"
],
"description": "total time it takes until a browser receives a complete response from a server (in milliseconds)"
},
"fetch_start": {
"type": [
"integer",
"null"
],
"description": "time to start downloading the HTML resource
the amount of time the browser needs to start downloading a page"
},
"fetch_end": {
"type": [
"integer",
"null"
],
"description": "time to complete downloading the HTML resource
the amount of time the browser needs to complete downloading a page"
},
"location": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_OnPageResourceLocationInfo"
}
],
"description": "location of the resource in the document
parameters defining the location of the specific resource within the document's HTML"
},
"is_render_blocking": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the resource blocks rendering"
}
}
},
"Response463397119C53_OnPageResourceLocationInfo": {
"type": "object",
"properties": {
"line": {
"type": [
"integer",
"null"
],
"description": "line number
the number of the line on which the resource is located"
},
"offset_left": {
"type": [
"integer",
"null"
],
"description": "position in line
the number of line characters before the resource;
sometimes referred to as column
Note: counts from 1, i.e. if the resource doesn't have any characters to the left, the value will be 1"
},
"offset_top": {
"type": [
"integer",
"null"
],
"description": "position in the document
the total number of characters between the resource and the top of HTML"
}
}
},
"Provider463397119C53_SerpAiSummaryRequestInfo": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "task identifier
required field
unique identifier of the associated task in the UUID format
you will be able to use it within 30 days to request the results of the task at any time"
},
"prompt": {
"type": [
"string",
"null"
],
"description": "AI prompt
optional field
additional task for AI summariser;
any form of text, question or information that communicates to AI what response you're looking for;
max number of symbols or characters you can specify: 2000;
note: your prompt has to be relevant to the keyword specified in the POST request to SERP API"
},
"support_extra": {
"type": [
"boolean",
"null"
],
"description": "support extra SERP features
optional field
if set to true, the AI model will consider the following extra SERP features, in addition to organic results: answer_box, knowledge_graph, featured_snippet;
default value: true"
},
"fetch_content": {
"type": [
"boolean",
"null"
],
"description": "fetch content from pages in SERPs
optional field
if set to true, the API will fetch the content from pages featured in SERP results, and the AI model will consider this content when generating the summary in the result;
default value: false"
},
"include_links": {
"type": [
"boolean",
"null"
],
"description": "include source links in the summary
optional field
if set to true, the summary field in the API response will contain links to sources of the generated summary;
default value: false"
}
},
"example": [
{
"task_id": "07031739-1535-0139-0000-9d1e639a5b7d",
"prompt": "explain what DataForSEO is",
"include_links": true,
"fetch_content": true
}
]
},
"Response463397119C53_SerpAiSummaryResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpAiSummaryTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpAiSummaryTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpAiSummaryResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpAiSummaryResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpAiSummaryItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_SerpAiSummaryItem": {
"type": "object",
"properties": {
"summary": {
"type": [
"string",
"null"
],
"description": "generated summary
summary generated by the AI model according to the parameters specified in the request"
}
}
},
"Response463397119C53_SerpBaiduLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBaiduLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_SerpBaiduLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBaiduLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
only City location_type is supported for all countries except China (where Country is also supported);
don't match locations by location_code_parent because the results for Region and Country-level results for most countries are not supported by Baidu SERP API"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
only City is supported for all countries except China (where Country is also supported)"
}
}
},
"Response463397119C53_SerpBaiduOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:
images, local_pack, map, organic, paid, related_searches, video, stocks_box, dictionary, shopping"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
},
"Response463397119C53_RefinementChipsInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsElement"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_RefinementChipsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"options": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "further search refinement options"
}
}
},
"Response463397119C53_BaseSerpApiElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"page": {
"type": [
"integer",
"null"
],
"description": "search results page number
indicates the number of the SERP page on which the element is located"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP
equals null if calculate_rectangles in the POST request is not set to true"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"paid": "#/components/schemas/Response463397119C53_PaidSerpElementItem",
"organic": "#/components/schemas/Response463397119C53_OrganicSerpElementItem",
"featured_snippet": "#/components/schemas/Response463397119C53_FeaturedSnippetSerpElementItem",
"knowledge_graph": "#/components/schemas/Response463397119C53_KnowledgeGraphSerpElementItem",
"top_stories": "#/components/schemas/Response463397119C53_TopStoriesSerpElementItem",
"people_also_ask": "#/components/schemas/Response463397119C53_PeopleAlsoAskSerpElementItem",
"people_also_search": "#/components/schemas/Response463397119C53_PeopleAlsoSearchSerpElementItem",
"images": "#/components/schemas/Response463397119C53_ImagesSerpElementItem",
"twitter": "#/components/schemas/Response463397119C53_TwitterSerpElementItem",
"google_reviews": "#/components/schemas/Response463397119C53_GoogleReviewsSerpElementItem",
"jobs": "#/components/schemas/Response463397119C53_JobsSerpElementItem",
"map": "#/components/schemas/Response463397119C53_MapSerpElementItem",
"app": "#/components/schemas/Response463397119C53_AppSerpElementItem",
"local_pack": "#/components/schemas/Response463397119C53_LocalPackSerpElementItem",
"carousel": "#/components/schemas/Response463397119C53_CarouselSerpElementItem",
"video": "#/components/schemas/Response463397119C53_VideoSerpElementItem",
"answer_box": "#/components/schemas/Response463397119C53_AnswerBoxSerpElementItem",
"shopping": "#/components/schemas/Response463397119C53_ShoppingSerpElementItem",
"google_flights": "#/components/schemas/Response463397119C53_GoogleFlightsSerpElementItem",
"events": "#/components/schemas/Response463397119C53_EventsSerpElementItem",
"related_searches": "#/components/schemas/Response463397119C53_RelatedSearchesSerpElementItem",
"multi_carousel": "#/components/schemas/Response463397119C53_MultiCarouselSerpElementItem",
"recipes": "#/components/schemas/Response463397119C53_RecipesSerpElementItem",
"top_sights": "#/components/schemas/Response463397119C53_TopSightsSerpElementItem",
"scholarly_articles": "#/components/schemas/Response463397119C53_ScholarlyArticlesSerpElementItem",
"popular_products": "#/components/schemas/Response463397119C53_PopularProductsSerpElementItem",
"stocks_box": "#/components/schemas/Response463397119C53_StocksBoxSerpElementItem",
"find_results_on": "#/components/schemas/Response463397119C53_FindResultsOnSerpElementItem",
"questions_and_answers": "#/components/schemas/Response463397119C53_QuestionsAndAnswersSerpElementItem",
"hotels_pack": "#/components/schemas/Response463397119C53_HotelsPackSerpElementItem",
"commercial_units": "#/components/schemas/Response463397119C53_CommercialUnitsSerpElementItem",
"local_services": "#/components/schemas/Response463397119C53_LocalServicesSerpElementItem",
"google_hotels": "#/components/schemas/Response463397119C53_GoogleHotelsSerpElementItem",
"math_solver": "#/components/schemas/Response463397119C53_MathSolverSerpElementItem",
"currency_box": "#/components/schemas/Response463397119C53_CurrencyBoxSerpElementItem",
"product_considerations": "#/components/schemas/Response463397119C53_ProductConsiderationsSerpElementItem",
"short_videos": "#/components/schemas/Response463397119C53_ShortVideosSerpElementItem",
"refine_products": "#/components/schemas/Response463397119C53_RefineProductsSerpElementItem",
"perspectives": "#/components/schemas/Response463397119C53_PerspectivesSerpElementItem",
"discussions_and_forums": "#/components/schemas/Response463397119C53_DiscussionsAndForumsSerpElementItem",
"compare_sites": "#/components/schemas/Response463397119C53_CompareSitesSerpElementItem",
"knowledge_graph_carousel_item": "#/components/schemas/Response463397119C53_KnowledgeGraphCarouselItemSerpElementItem",
"knowledge_graph_description_item": "#/components/schemas/Response463397119C53_KnowledgeGraphDescriptionItemSerpElementItem",
"knowledge_graph_images_item": "#/components/schemas/Response463397119C53_KnowledgeGraphImagesItemSerpElementItem",
"knowledge_graph_list_item": "#/components/schemas/Response463397119C53_KnowledgeGraphListItemSerpElementItem",
"knowledge_graph_row_item": "#/components/schemas/Response463397119C53_KnowledgeGraphRowItemSerpElementItem",
"knowledge_graph_hotels_booking_item": "#/components/schemas/Response463397119C53_KnowledgeGraphHotelsBookingItemSerpElementItem",
"knowledge_graph_expanded_item": "#/components/schemas/Response463397119C53_KnowledgeGraphExpandedItemSerpElementItem",
"knowledge_graph_part_item": "#/components/schemas/Response463397119C53_KnowledgeGraphPartItemSerpElementItem",
"knowledge_graph_shopping_item": "#/components/schemas/Response463397119C53_KnowledgeGraphShoppingItemSerpElementItem",
"knowledge_graph_ai_overview_item": "#/components/schemas/Response463397119C53_KnowledgeGraphAiOverviewItemSerpElementItem",
"ai_overview": "#/components/schemas/Response463397119C53_AiOverviewSerpElementItem",
"third_party_reviews": "#/components/schemas/Response463397119C53_ThirdPartyReviewsSerpElementItem",
"dictionary": "#/components/schemas/Response463397119C53_DictionarySerpElementItem",
"google_posts": "#/components/schemas/Response463397119C53_GooglePostsSerpElementItem",
"mention_carousel": "#/components/schemas/Response463397119C53_MentionCarouselSerpElementItem",
"podcasts": "#/components/schemas/Response463397119C53_PodcastsSerpElementItem",
"visual_stories": "#/components/schemas/Response463397119C53_VisualStoriesSerpElementItem",
"found_on_web": "#/components/schemas/Response463397119C53_FoundOnWebSerpElementItem",
"explore_brands": "#/components/schemas/Response463397119C53_ExploreBrandsSerpElementItem",
"courses": "#/components/schemas/Response463397119C53_CoursesSerpElementItem"
}
}
},
"Response463397119C53_PaidSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements found in SERPnote values are returned in the ascending order, with values corresponding to advanced SERP features omitted from the results;
to get all items (including SERP features and rich snippets) with their positions, please refer to the Google Organiс Advanced SERP endpoint"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the results element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "name of the website in SERP"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an_image
Note: this check no longer appears in SERP"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video
Note: this check no longer appears in SERP"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
],
"description": "indicates whether the element contains an_image
Note: this check no longer appears in SERP"
},
"description": "array of properties detected for the SERP element
lists the properties that are true for this element
each value in the array represents a detected property
example:
if is_image is present in the array, the element contains an image
possible values in the array:is_image, is_video, is_featured_snippet, amp_version, is_malicious, is_web_story, is_highly_cited
equals null if none of the properties are detected for the element
learn more about the checks array in this Help Center article"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"extra": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "additional information about the result"
},
"description_rows": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extended description
if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AdLinkElement"
}
]
},
"description": "link of the element"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing details
contains the pricing details of the product or service featured in the result;
if there is none, equals null"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP
if there is none, equals null"
}
}
}
]
},
"Response463397119C53_OrganicSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements found in SERPnote values are returned in the ascending order, with values corresponding to advanced SERP features omitted from the results;
to get all items (including SERP features and rich snippets) with their positions, please refer to the Google Organiс Advanced SERP endpoint"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the results element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"cache_url": {
"type": [
"string",
"null"
],
"description": "cached version of the page"
},
"related_search_url": {
"type": [
"string",
"null"
],
"description": "URL to a similar search
URL to a new search for the same keyword(s) on related sites"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "name of the website in SERP"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an_image
Note: this check no longer appears in SERP"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video
Note: this check no longer appears in SERP"
},
"is_featured_snippet": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is a featured_snippet
Note: this check no longer appears in SERP"
},
"is_malicious": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as malicious
Note: this check no longer appears in SERP"
},
"is_web_story": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as Google web story
Note: this check no longer appears in SERP"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
],
"description": "indicates whether the element contains an_image
Note: this check no longer appears in SERP"
},
"description": "array of properties detected for the SERP element
lists the properties that are true for this element
each value in the array represents a detected property
example:
if is_image is present in the array, the element contains an image
possible values in the array:is_image, is_video, is_featured_snippet, amp_version, is_malicious, is_web_story, is_highly_cited
equals null if none of the properties are detected for the element
learn more about the checks array in this Help Center article"
},
"pre_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended before the result description in SERP"
},
"extended_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended after the result description in SERP"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"amp_version": {
"type": [
"boolean",
"null"
],
"description": "Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version
Note: this check no longer appears in SERP"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP
if there is none, equals null"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing details
contains the pricing details of the product or service featured in the result;
if there is none, equals null"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "link of the element"
},
"faq": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FaqBox"
}
],
"description": "frequently asked questions
questions and answers extension shown below some of Google's search results
Note: this object is deprecated and always returns null",
"deprecated": true
},
"extended_people_also_search": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extension of the organic element
extension of the organic result containing related search queries
Note: extension appears in SERP upon clicking on the result and then bouncing back to search results"
},
"about_this_result": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AboutThisResultElement"
}
],
"description": "contains information from the 'About this result' panel
Note: this object is deprecated and always returns null",
"deprecated": true
},
"related_result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedResult"
}
]
},
"description": "related result from the same domain
related result from the same domain appears as a part of the main result snippet;
you can derive the related_result snippets as \"type\": \"organic\" results by setting the group_organic_results parameter to false in the POST request"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_FaqBox": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FaqBoxElement"
}
]
},
"description": "contains arrays of specific images"
}
},
"deprecated": true
},
"Response463397119C53_FaqBoxElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the link"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the hotel booking element"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "link of the element"
}
},
"deprecated": true
},
"Response463397119C53_RelatedResult": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"page": {
"type": [
"integer",
"null"
],
"description": "search results page number
indicates the number of the SERP page on which the element is located"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"domain": {
"type": [
"string",
"null"
],
"description": "website domain"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"cache_url": {
"type": [
"string",
"null"
],
"description": "cached version of the page"
},
"related_search_url": {
"type": [
"string",
"null"
],
"description": "URL to a similar search
URL to a new search for the same keyword(s) on related sites"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "name of the website in the ad element"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an_image
Note: this check no longer appears in SERP"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video
Note: this check no longer appears in SERP"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
],
"description": "indicates whether the element contains an_image
Note: this check no longer appears in SERP"
},
"description": "array of properties detected for the SERP element
lists the properties that are true for this element
each value in the array represents a detected property
example:
if is_image is present in the array, the element contains an image
possible values in the array:is_image, is_video, is_featured_snippet, amp_version, is_malicious, is_web_story, is_highly_cited
equals null if none of the properties are detected for the element
learn more about the checks array in this Help Center article"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"pre_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended before the result description in SERP"
},
"extended_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended after the result description in SERP"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the component
if there are none, equals null"
},
"amp_version": {
"type": [
"boolean",
"null"
],
"description": "Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version
Note: this check no longer appears in SERP"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price of booking a place for the specified dates of stay"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"about_this_result": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AboutThisResultElement"
}
],
"description": "contains information from the 'About this result' panel
Note: this object is deprecated and always returns null",
"deprecated": true
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_FeaturedSnippetSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements found in SERPnote values are returned in the ascending order, with values corresponding to advanced SERP features omitted from the results;
to get all items (including SERP features and rich snippets) with their positions, please refer to the Google Organiс Advanced SERP endpoint"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the ad element in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the ad element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the ad element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL of the ad element in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb of the ad element in SERP"
},
"featured_title": {
"type": [
"string",
"null"
],
"description": "title"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table present in the element
the header and content of the table present in the element"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the item"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"card_id": {
"type": [
"string",
"null"
],
"description": "card id"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"logo_url": {
"type": [
"string",
"null"
],
"description": "URL of the logo from knowledge graph"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment;
can be used with Google Reviews API to get a full list of reviews"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_BaseSerpApiKnowledgeGraphElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"page": {
"type": [
"integer",
"null"
],
"description": "search results page number
indicates the number of the SERP page on which the element is located"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP
equals null if calculate_rectangles in the POST request is not set to true"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"knowledge_graph_carousel_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphCarouselItemElementItem",
"knowledge_graph_description_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphDescriptionItemElementItem",
"knowledge_graph_images_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphImagesItemElementItem",
"knowledge_graph_list_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphListItemElementItem",
"knowledge_graph_row_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphRowItemElementItem",
"knowledge_graph_expanded_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphExpandedItemElementItem",
"knowledge_graph_part_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphPartItemElementItem",
"knowledge_graph_shopping_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphShoppingItemElementItem",
"knowledge_graph_hotels_booking_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphHotelsBookingItemElementItem",
"knowledge_graph_ai_overview_item": "#/components/schemas/Response463397119C53_SerpApiKnowledgeGraphAiOverviewItemElementItem"
}
}
},
"Response463397119C53_SerpApiKnowledgeGraphCarouselItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphListElement"
}
]
},
"description": "elements of search results found in SERP"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphDescriptionItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"text": {
"type": [
"string",
"null"
],
"description": "text or description of the element in SERP"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphImagesItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphImagesElement"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphListItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:ss:/webfacts:net_worth"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphListElement"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphRowItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the link"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:kc:/common/topic:social media presence"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphExpandedItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:kc:/local:place qa"
},
"expanded_element": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphExpandedElement"
}
]
},
"description": "link of the element"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphExpandedElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"featured_title": {
"type": [
"string",
"null"
],
"description": "title of a given element"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL "
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table present in the element
the header and content of the table present in the element"
}
}
},
"Response463397119C53_SerpApiKnowledgeGraphPartItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the place"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:kc:/local:place qa"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphShoppingItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:kc:/shopping/gpc:organic-offers"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphShoppingElement"
}
]
},
"description": "keywords relevant to the initial search query
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_SerpApiKnowledgeGraphHotelsBookingItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of stay
in the format “year-month-date”
example:
2019-11-15"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of stay
in the format “year-month-date”
example:
2019-11-17"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:kc:/local:hotel booking"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphHotelsBookingElement"
}
]
},
"description": "popular keywords relevant to the initial search query
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphHotelsBookingElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"source": {
"type": [
"string",
"null"
],
"description": "name of the source of the video"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "image source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "website domain"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing details
contains the pricing details of the product or service featured in the result"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is an ad"
}
}
},
"Response463397119C53_SerpApiKnowledgeGraphAiOverviewItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiKnowledgeGraphElementItem"
}
]
},
{
"type": "object",
"properties": {
"asynchronous_ai_overview": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is loaded asynchronously
if true, the ai_overview element is loaded asynchronously;
if false, the ai_overview element is loaded from cache;
to obtain the content of ai_overview elements, use the load_async_ai_overview parameter in the POST request"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "additional references relevant to the item
includes references to webpages that may have been used to generate the ai_overview"
}
}
}
]
},
"Response463397119C53_AiModeRectangleInfo": {
"type": "object",
"properties": {
"x": {
"type": [
"number",
"null"
],
"description": "x-axis coordinate\nx-axis coordinate of the top-left corner of the result’s snippet, where top-left corner of the screen is the origin",
"format": "double"
},
"y": {
"type": [
"number",
"null"
],
"description": "y-axis coordinate\ny-axis coordinate of the top-left corner of the result’s snippet, where top-left corner of the screen is the origin",
"format": "double"
},
"width": {
"type": [
"number",
"null"
],
"description": "width of the element in pixels",
"format": "double"
},
"height": {
"type": [
"number",
"null"
],
"description": "height of the element in pixels",
"format": "double"
}
}
},
"Response463397119C53_TopStoriesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopStoriesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_PeopleAlsoAskSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PeopleAlsoAskElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_PeopleAlsoSearchSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_ImagesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "contains arrays of elements available in the list"
},
"related_image_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedImageSearchesElement"
}
]
},
"description": "contains keywords and images related to the specified search term
Note: this array is deprecated and always returns null",
"deprecated": true
}
}
}
]
},
"Response463397119C53_TwitterSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TwitterElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_GoogleReviewsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews",
"format": "int64"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "the identifier of a place"
},
"feature": {
"type": [
"string",
"null"
],
"description": "the additional feature of the review"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
}
}
}
]
},
"Response463397119C53_JobsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_JobsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_MapSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
}
}
}
]
},
"Response463397119C53_AppSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AppElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_AppElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price indicated in the element"
}
}
},
"Response463397119C53_LocalPackSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the link"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the website hosting the video"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number"
},
"booking_url": {
"type": [
"string",
"null"
],
"description": "URL of the booking page"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is an ad"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
}
}
}
]
},
"Response463397119C53_CarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpApiCarouselElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_VideoSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_VideoElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_AnswerBoxSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"text": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "text
if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_ShoppingSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ShoppingElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_GoogleFlightsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFlightsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_EventsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_EventsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_RelatedSearchesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_MultiCarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MultiCarouselElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_RecipesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RecipesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_TopSightsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopSightsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_ScholarlyArticlesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ScholarlyArticlesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_PopularProductsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PopularProductsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_StocksBoxSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"source": {
"type": [
"string",
"null"
],
"description": "source of the element
indicates the source of information included in the recipes_element"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price indicated in the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the website hosting the video"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table present in the element
the header and content of the table present in the element"
},
"graph": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Graph"
}
],
"description": "contains data provided in the graph of the element"
}
}
}
]
},
"Response463397119C53_FindResultsOnSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FindResultsOnElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_QuestionsAndAnswersSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_QuestionsAndAnswersElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_HotelsPackSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of stay
in the format \"year-month-date\"
example:
2019-11-15"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of stay
in the format \"year-month-date\"
example:
2019-11-17"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelsPackElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_CommercialUnitsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CommercialUnitsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_LocalServicesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the website hosting the video"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocalServicesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_LocalServicesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
},
"profile_image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image featured in the element"
}
}
},
"Response463397119C53_GoogleHotelsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"hotel_identifier": {
"type": [
"string",
"null"
],
"description": "unique hotel identifier
unique hotel identifier assigned by Google;
example: \"CgoIjaeSlI6CnNpVEAE\""
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
}
}
}
]
},
"Response463397119C53_MathSolverSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"result": {
"type": [
"string",
"null"
],
"description": "solution to the equation
solution to the mathematical equation specified in the keyword field when setting a task"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MathSolverElement"
}
]
},
"description": "contains arrays of elements available in the list"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_CurrencyBoxSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"value": {
"type": [
"number",
"null"
],
"description": "the value of the rating"
},
"converted_value": {
"type": [
"number",
"null"
],
"description": "value converted to a requested currency
indicates the exact value based on Google Fincance data at the time when our API pulled the results
note that exchange rates displayed in the currency_box element may be delayed according to the Google Finance disclaimer"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency of the listed price
ISO code of the currency applied to the price"
},
"converted_currency": {
"type": [
"string",
"null"
],
"description": "converted currency"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "table present in the element
the header and content of the table present in the element"
},
"graph": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Graph"
}
],
"description": "contains data provided in the graph of the element"
}
}
}
]
},
"Response463397119C53_ProductConsiderationsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ProductConsiderationsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_ProductConsiderationsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"consideration_category": {
"type": [
"string",
"null"
],
"description": "category of the consideration element
the category is indicated just above the title fo the consideration element"
},
"expanded_element": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiProductConsiderationExpandedElementItem"
}
]
},
"description": "expanded element"
}
}
},
"Response463397119C53_BaseSerpApiProductConsiderationExpandedElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"product_considerations_expanded_element": "#/components/schemas/Response463397119C53_SerpApiProductConsiderationsExpandedElementItem",
"product_considerations_ai_overview_expanded_element": "#/components/schemas/Response463397119C53_SerpApiProductConsiderationsAiOverviewExpandedElementItem"
}
}
},
"Response463397119C53_SerpApiProductConsiderationsExpandedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiProductConsiderationExpandedElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the carousel item"
},
"featured_title": {
"type": [
"string",
"null"
],
"description": "the title of the featured snippets source page"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb of the Ad element in SERP"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text alongside the link title"
},
"domain": {
"type": [
"string",
"null"
],
"description": "source domain"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"related_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"about_this_result": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AboutThisResultElement"
}
],
"description": "contains information from the 'About this result' panel
Note: this object is deprecated and always returns null",
"deprecated": true
}
}
}
]
},
"Response463397119C53_SerpApiProductConsiderationsAiOverviewExpandedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiProductConsiderationExpandedElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOverviewElement"
}
]
},
"description": "items present in the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "additional references relevant to the item
includes references to webpages that may have been used to generate the ai_overview"
}
}
}
]
},
"Response463397119C53_AiOverviewElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"text": {
"type": [
"string",
"null"
],
"description": "content within the item"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
},
"Response463397119C53_ShortVideosSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ShortVideosElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_ShortVideosElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
}
}
},
"Response463397119C53_RefineProductsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefineProductsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_RefineProductsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword for the related refined search"
},
"refine_type": {
"type": [
"string",
"null"
],
"description": "type of search refinement"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
}
},
"Response463397119C53_PerspectivesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PerspectivesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_PerspectivesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"date": {
"type": [
"string",
"null"
],
"description": "the date when the page source of the element was published"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
}
}
},
"Response463397119C53_DiscussionsAndForumsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DiscussionsAndForumsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_DiscussionsAndForumsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"posts_count": {
"type": [
"integer",
"null"
],
"description": "number of posts from the discussion on the related source",
"format": "int64"
}
}
},
"Response463397119C53_CompareSitesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CompareSitesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_CompareSitesElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"url": {
"type": [
"string",
"null"
],
"description": "source URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where a link points"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
}
}
},
"Response463397119C53_KnowledgeGraphCarouselItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphListElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphDescriptionItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphImagesItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphImagesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphListItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"link": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
],
"description": "link of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphListElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphRowItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphHotelsBookingItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of stay
in the format \"year-month-date\"
example:
2019-11-15"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of stay
in the format \"year-month-date\"
example:
2019-11-17"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphHotelsBookingElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphExpandedItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"expanded_element": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphExpandedElement"
}
]
},
"description": "expanded element"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphPartItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphShoppingItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"data_attrid": {
"type": [
"string",
"null"
],
"description": "google defined data attribute ID
example:action:listen_artist"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_KnowledgeGraphShoppingElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
]
},
"Response463397119C53_KnowledgeGraphAiOverviewItemSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"asynchronous_ai_overview": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is loaded asynchronously
if true, the ai_overview element is loaded asynchronously;
if false, the ai_overview element is loaded from cache"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
"description": "contains arrays of elements available in the list"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
}
]
},
"Response463397119C53_AiOverviewSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"asynchronous_ai_overview": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is loaded asynchronously
if true, the ai_overview element is loaded asynchronously;
if false, the ai_overview element is loaded from cache;
to obtain the content of ai_overview elements, use the load_async_ai_overview parameter in the POST request"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
the text of the ai_overview formatted in the markdown markup language"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiOverviewElementItem"
}
]
},
"description": "contains arrays of elements available in the list"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
}
]
},
"Response463397119C53_ThirdPartyReviewsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop"
},
"reviews_count": {
"type": [
"integer",
"null"
],
"description": "the number of reviews",
"format": "int64"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the row"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the third-party review source"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element's rating
the popularity rate based on reviews and displayed in SERP;
if there is none, equals null"
}
}
}
]
},
"Response463397119C53_DictionarySerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL of the Ad element in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb of the Ad element in SERP"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword highlighted in the result"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "snippet of the element"
},
"text": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of search results
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_GooglePostsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"posts_id": {
"type": [
"string",
"null"
],
"description": "the identifier of the google_posts feature"
},
"feature": {
"type": [
"string",
"null"
],
"description": "the additional feature of the review"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id"
}
}
}
],
"deprecated": true
},
"Response463397119C53_MentionCarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_MentionCarouselElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
],
"deprecated": true
},
"Response463397119C53_PodcastsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PodcastsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
],
"deprecated": true
},
"Response463397119C53_VisualStoriesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
],
"deprecated": true
},
"Response463397119C53_FoundOnWebSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"related_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "search queries related to the elment"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FoundOnWebElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
],
"deprecated": true
},
"Response463397119C53_ExploreBrandsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ExploreBrandsElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
],
"deprecated": true
},
"Response463397119C53_CoursesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP\nposition within a group of elements with identical type values;\npositions of elements with different type values are omitted from rank_group;\nalways equals 0 for desktop"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of a given link element"
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "array of course categories\ncontains a list of categories relevant to courses"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_CoursesElement"
}
]
},
"description": "contains arrays of elements available in the list"
}
}
}
],
"deprecated": true
},
"Response463397119C53_SerpBaiduOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpBaiduOrganicTaskGetRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskGetRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskGetRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTaskGetRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTaskGetRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:organic, paid"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpBaiduOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority
You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 10
max value: 700
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesnote that the only language supported in Baidu search engine is Chinese (Simplified). However, Baidu may as well return results for queries in other languages, so specifying keyword in Chinese is not mandatoryChinese (Simplified)"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesnote that the only language supported in Baidu search engine is Chinese (Simplified) with the zh_CN language code. However, Baidu may as well return results for queries in other languages, so specifying keyword in Chinese is not mandatoryzh_CN"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:New York,New York,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2156"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)if you use this field, the returned results will be based on the closest city found for your coordinates. Thus, we don't recommend using this field as the results might not be relevant to the specified coordinates
example:53.476225,-2.243572,200"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values: desktop, mobile, tablet
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android
if you specify tablet in the device field, choose from the following values: android, ios
default value: android"
},
"get_website_url": {
"type": [
"boolean",
"null"
],
"description": "include direct URL for each ranked result
optional field
if set to true, the returned results will contain direct URLs of the ranked websites
by default, the URLs in Baidu results are encoded by the search engine,
for example:http://www.baidu.com/link?url=KQt6LSwU5OHnPtB8210R8flBP40grY6lTPxH_0UO7S2kgiZMTmw3ztV0hCo5c1kLdefault value: false
Note: if set to true, the charge per task will be multiplied by 10 as our system runs a separate request for each ranked website to return its direct URL"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:regular, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBaiduOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBaiduOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpBingLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBingLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBingLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_SerpBingLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBingLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBingLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:
`\"location_code\": 9041134`,
`\"location_name\": \"Vienna International Airport,Lower Austria,Austria\"`,
`\"location_code_parent\": 20044`
`\"location_name\": \"Lower Austria,Austria\"`"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
indicates the geographic classification of the location
example:
`\"location_type\": \"Country\"`, or `\"location_type\": \"State\"`"
}
}
},
"Provider463397119C53_SerpBingOrganicLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsehttps:// and www.target-specific tasks will only include SERP elements that contain a url string;example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;example.com* - returns results for the domain, including all its pages;*example.com* - returns results for the entire domain, including all its pages and subdomains;*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;example.com/example-page - returns results for the exact URL;example.com/example-page* - returns results for all domain's URLs that start with the specified stringstop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"1100max_crawl_pages and depth parameters complement each other;false240-9999;1920 for desktop;360 for mobile on android;375 for mobile on iOS;calculate_rectangles to true240-9999;1080 for desktop;640 for mobile on android;812 for mobile on iOS;calculate_rectangles to true0.5-3;1 for desktop;3 for mobile on android;3 for mobile on iOS;calculate_rectangles to truehttps://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGElocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format53.476225,-2.243572
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection
equals null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:
answer_box, carousel, events, featured_snippet, hotels_pack, images, jobs, local_pack, map, organic, paid, people_also_ask, people_also_search, questions_and_answers,recipes, related_searches, shopping, top_stories, video, ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_BaseBingSerpApiElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements in SERP"
},
"page": {
"type": [
"integer",
"null"
],
"description": "search results page number
indicates the number of the SERP page on which the element is located"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:
left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP
equals null if calculate_rectangles in the POST request is not set to true"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"organic": "#/components/schemas/Response463397119C53_BingOrganicSerpElementItem",
"paid": "#/components/schemas/Response463397119C53_BingPaidSerpElementItem",
"featured_snippet": "#/components/schemas/Response463397119C53_BingFeaturedSnippetSerpElementItem",
"related_searches": "#/components/schemas/Response463397119C53_BingRelatedSearchesSerpElementItem",
"ai_overview": "#/components/schemas/Response463397119C53_BingAiOverviewSerpElementItem",
"images": "#/components/schemas/Response463397119C53_BingImagesSerpElementItem",
"video": "#/components/schemas/Response463397119C53_BingVideoSerpElementItem",
"shopping": "#/components/schemas/Response463397119C53_BingShoppingSerpElementItem",
"answer_box": "#/components/schemas/Response463397119C53_BingAnswerBoxSerpElementItem",
"local_pack": "#/components/schemas/Response463397119C53_BingLocalPackSerpElementItem",
"questions_and_answers": "#/components/schemas/Response463397119C53_BingQuestionsAndAnswersSerpElementItem",
"hotels_pack": "#/components/schemas/Response463397119C53_BingHotelsPackSerpElementItem",
"jobs": "#/components/schemas/Response463397119C53_BingJobsSerpElementItem",
"top_stories": "#/components/schemas/Response463397119C53_BingTopStoriesSerpElementItem",
"carousel": "#/components/schemas/Response463397119C53_BingCarouselSerpElementItem",
"map": "#/components/schemas/Response463397119C53_BingMapSerpElementItem",
"events": "#/components/schemas/Response463397119C53_BingEventsSerpElementItem",
"recipes": "#/components/schemas/Response463397119C53_BingRecipesSerpElementItem",
"people_also_ask": "#/components/schemas/Response463397119C53_BingPeopleAlsoAskSerpElementItem",
"people_also_search": "#/components/schemas/Response463397119C53_BingPeopleAlsoSearchSerpElementItem"
}
}
},
"Response463397119C53_BingOrganicSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the results element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": " relevant URL in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"cache_url": {
"type": [
"string",
"null"
],
"description": "cached version of the page"
},
"related_search_url": {
"type": [
"string",
"null"
],
"description": "URL to a similar search
URL to a new search for the same keyword(s) on related sites"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "name of the source website"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an image"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video"
},
"is_featured_snippet": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is a featured_snippet"
},
"is_malicious": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as malicious"
},
"is_web_story": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as a web story"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
],
"description": "indicates whether the element contains a video"
}
},
"pre_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended before the result description in SERP"
},
"extended_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended after the result description in SERP"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element"
},
"amp_version": {
"type": [
"boolean",
"null"
],
"description": "Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing details
contains the pricing details of the product or service featured in the result"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some search results
if there are none, equals null"
},
"faq": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FaqBox"
}
],
"description": "frequently asked questions
questions and answers extension shown below some search results
if there are none, equals null",
"deprecated": true
},
"extended_people_also_search": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extension of the organic element
extension of the organic result containing related search queries
Note: extension appears in SERP upon clicking on the result and then bouncing back to search results"
},
"about_this_result": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AboutThisResultElement"
}
],
"description": "contains information from the 'About this result' panel
note: about_this_result feature is not available in Bing search engine, that’s why it always equals null",
"deprecated": true
},
"related_result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedResult"
}
]
},
"description": "related result from the same domain
related result from the same domain appears as a part of the main result snippet;
note: related_result feature is not available in Bing search engine, that’s why it always equals null"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_BingPaidSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the ad element in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the ad element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the ad element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL of the ad element in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb of the ad element in SERP"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "website name in SERP"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an image"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"extra": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "additional information about the result"
},
"description_rows": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extended description
if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AdLinkElement"
}
]
},
"description": "links featured in the organic result"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "price of booking a place for the specified dates of stay"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
}
}
}
]
},
"Response463397119C53_BingFeaturedSnippetSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain of the ad element in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the ad element in SERP"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the ad element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL of the ad element in SERP"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb of the ad element in SERP"
},
"featured_title": {
"type": [
"string",
"null"
],
"description": "the title of the featured snippets source page"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Table"
}
],
"description": "results table
if there are none, equals null"
}
}
}
]
},
"Response463397119C53_BingRelatedSearchesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "items in SERP"
}
}
}
]
},
"Response463397119C53_BingAiOverviewSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiBingAiOverviewElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "additional references relevant to the item
includes references to webpages that may have been used to generate the ai_overview"
}
}
}
]
},
"Response463397119C53_BaseSerpApiBingAiOverviewElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"ai_overview_element": "#/components/schemas/Response463397119C53_SerpApiBingAiOverviewElementItem",
"ai_overview_video_element": "#/components/schemas/Response463397119C53_SerpApiBingAiOverviewVideoElementItem",
"ai_overview_videos_element": "#/components/schemas/Response463397119C53_SerpApiBingAiOverviewVideosElementItem",
"ai_overview_images_element": "#/components/schemas/Response463397119C53_SerpApiBingAiOverviewImagesElementItem",
"ai_overview_organic_element": "#/components/schemas/Response463397119C53_SerpApiBingAiOverviewOrganicElementItem"
}
}
},
"Response463397119C53_SerpApiBingAiOverviewElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiBingAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:
left, right"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"text": {
"type": [
"string",
"null"
],
"description": "text or description of the element in SERP"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some search results
if there are none, equals null"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
}
]
},
"Response463397119C53_SerpApiBingAiOverviewVideoElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiBingAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:
left, right"
},
"title": {
"type": [
"string",
"null"
],
"description": "link anchor text"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text snippet of the video"
},
"url": {
"type": [
"string",
"null"
],
"description": "link URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"source": {
"type": [
"string",
"null"
],
"description": "source of the element
indicates the source of information included in the questions_and_answers_element"
},
"date": {
"type": [
"string",
"null"
],
"description": "the date when the page source of the element was published"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:
2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_SerpApiBingAiOverviewVideosElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiBingAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_VideoElement"
}
]
},
"description": "elements of search results found in SERP"
}
}
}
]
},
"Response463397119C53_SerpApiBingAiOverviewImagesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiBingAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "URL link"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the link element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "items featured in the faq_box"
}
}
}
]
},
"Response463397119C53_SerpApiBingAiOverviewOrganicElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiBingAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the link"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL "
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "text snippet from the organic result"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "website name in SERP"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "links featured in the faq_box_element"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
}
}
}
]
},
"Response463397119C53_BingImagesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
},
"related_image_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedImageSearchesElement"
}
]
},
"description": "contains keywords and images related to the specified search term
if there are none, equals null",
"deprecated": true
}
}
}
]
},
"Response463397119C53_BingVideoSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_VideoElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingShoppingSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ShoppingElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingAnswerBoxSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "text
if there is none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "links featured in the organic result"
}
}
}
]
},
"Response463397119C53_BingLocalPackSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain where the video is hosted"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number"
},
"booking_url": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"is_paid": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is an ad"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
},
"cid": {
"type": [
"string",
"null"
],
"description": "bing-defined client id
unique id of a local establishment"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "business listing is claimed
if true, the business listing is claimed by the owner or representative"
}
}
}
]
},
"Response463397119C53_BingQuestionsAndAnswersSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_QuestionsAndAnswersElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingHotelsPackSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of stay
in the format “year-month-date”
example:
2019-11-15"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of stay
in the format “year-month-date”
example:
2019-11-17"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HotelsPackElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingJobsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_JobsElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingTopStoriesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopStoriesElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingCarouselSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpApiCarouselElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingMapSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
}
}
}
]
},
"Response463397119C53_BingEventsSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_EventsElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingRecipesSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RecipesElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingPeopleAlsoAskSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PeopleAlsoAskElement"
}
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Response463397119C53_BingPeopleAlsoSearchSerpElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the item"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "contains results featured in the 'hotels_pack' element of SERP"
}
}
}
]
},
"Provider463397119C53_SerpBingOrganicLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsestop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"1100max_crawl_pages and depth parameters complement each other;https://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGElocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format53.476225,-2.243572
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpBingOrganicLiveRegularRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsehttps:// and www.target-specific tasks will only include SERP elements that contain a url string;example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;example.com* - returns results for the domain, including all its pages;*example.com* - returns results for the entire domain, including all its pages and subdomains;*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;example.com/example-page - returns results for the exact URL;example.com/example-page* - returns results for all domain's URLs that start with the specified stringstop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"1100max_crawl_pages and depth parameters complement each other;https://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGElocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format53.476225,-2.243572
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types: organic, paid"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Response463397119C53_SerpBingOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:
answer_box, carousel, events, featured_snippet, hotels_pack, images, jobs, local_pack, map, organic, paid, people_also_ask, people_also_search, questions_and_answers,recipes, related_searches, shopping, top_stories, video, ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
},
"Response463397119C53_SerpBingOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpBingOrganicTaskGetRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTaskGetRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTaskGetRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTaskGetRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTaskGetRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types: organic, paid"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseBingSerpApiElementItem"
}
]
},
"description": "items inside the element
array of 8 search queries related to the keyword"
}
}
},
"Provider463397119C53_SerpBingOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10700
Your account will be billed per each SERP containing up to 10 results;
You will be additionally charged for the tasks with high execution priority.desktop, mobiledesktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urlregular, advanced, htmllocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsestop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"1100max_crawl_pages and depth parameters complement each other;false240-9999;1920 for desktop;360 for mobile on android;375 for mobile on iOS;calculate_rectangles to true240-9999;1080 for desktop;640 for mobile on android;812 for mobile on iOS;calculate_rectangles to true0.5-3;1 for desktop;3 for mobile on android;3 for mobile on iOS;calculate_rectangles to truehttps://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGElocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format53.476225,-2.243572
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpBingOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpBingOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleAdsAdvertisersLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsAdvertisersLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsAdvertisersLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:\"location_code\": 9041134,
\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",
\"location_code_parent\": 20044location_code_parent corresponds to:\"location_code\": 20044,"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Response463397119C53_SerpGoogleAdsAdvertisersTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsAdvertisersTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsAdvertisersTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
\"location_name\": \"Lower Austria,Austria\"
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, equals null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:ads_muti_account_advertiser, ads_advertiser, ads_domain"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAdsAdvertiserElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_BaseSerpApiAdsAdvertiserElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"ads_multi_account_advertiser": "#/components/schemas/Response463397119C53_SerpApiAdsMultiAccountAdvertiserElementItem",
"ads_advertiser": "#/components/schemas/Response463397119C53_SerpApiAdsAdvertiserElementItem",
"ads_domain": "#/components/schemas/Response463397119C53_SerpApiAdsDomainElementItem"
}
}
},
"Response463397119C53_SerpApiAdsMultiAccountAdvertiserElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAdsAdvertiserElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"location": {
"type": [
"string",
"null"
],
"description": "advertiser location"
},
"approx_ads_count": {
"type": [
"integer",
"null"
],
"description": "ads count
the approximate number of ads that are run by the advertiser across all available Google Ads platforms",
"format": "int64"
},
"advertisers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Advertiser"
}
]
},
"description": "associated advertiser accounts
contains objects with data on associated advertiser accounts"
}
}
}
]
},
"Response463397119C53_Advertiser": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "unique identifier of the advertiser account
can be used to obtain data on advertising campaigns from the Google Ads Search endpoint"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the advertiser account
country code associated with the advertiser account"
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "verified advertiser account
equals true if advertiser account is verified by Google Ads"
},
"approx_ads_count": {
"type": [
"integer",
"null"
],
"description": "ads count
the approximate number of ads that are run by the advertiser account across all available Google Ads platforms",
"format": "int64"
}
}
},
"Response463397119C53_SerpApiAdsAdvertiserElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAdsAdvertiserElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "unique identifier of the advertiser account
can be used to obtain data on advertising campaigns from the Google Ads Search endpoint"
},
"location": {
"type": [
"string",
"null"
],
"description": "advertiser location"
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "verified advertiser account
equals true if advertiser account is verified by Google Ads"
},
"approx_ads_count": {
"type": [
"integer",
"null"
],
"description": "ads count
the approximate number of ads that are run by the advertiser across all available Google Ads platforms",
"format": "int64"
}
}
}
]
},
"Response463397119C53_SerpApiAdsDomainElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAdsAdvertiserElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
}
}
}
]
},
"Provider463397119C53_SerpGoogleAdsAdvertisersTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article
You will be additionally charged for the tasks with high execution priority.location_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_advertisers/locations2840location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvancedlocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_advertisers/locationsLondon,England,United Kingdomlocation_name, location_code, or location_coordinate, advertisers will be searched across all the available locationslocation_name or location_code52.6178549,-155.352142location_name, location_code, or location_coordinate, advertisers will be searched across all the available locationstag value in the data object of the response
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsAdvertisersTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsAdvertisersTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsAdvertisersTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleAdsSearchLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsSearchLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsSearchLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:
`\"location_code\": 9041134`,
`\"location_name\": \"Vienna International Airport,Lower Austria,Austria\"`,
`\"location_code_parent\": 20044`
`\"location_name\": \"Lower Austria,Austria\"`"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Response463397119C53_SerpGoogleAdsSearchTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsSearchTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsSearchTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
in this case, equals null"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, equals null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:ads_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AdsSearch"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_AdsSearch": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "unique identifier of the advertiser account"
},
"creative_id": {
"type": [
"string",
"null"
],
"description": "unique identifier of the advertisement"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "verified advertiser account
equals true if advertiser account is verified by Google Ads"
},
"format": {
"type": [
"string",
"null"
],
"description": "format of the advertisement
possible values: text, image, video"
},
"preview_image": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PreviewImage"
}
],
"description": "preview image of the advertisement"
},
"preview_url": {
"type": [
"string",
"null"
],
"description": "url pointing to the ad preview"
},
"first_shown": {
"type": [
"string",
"null"
],
"description": "date and time when the ad was shown for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”"
},
"last_shown": {
"type": [
"string",
"null"
],
"description": "date and time when the ad was shown the last time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”"
}
}
},
"Response463397119C53_PreviewImage": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"height": {
"type": [
"integer",
"null"
],
"description": "height of the preview image"
},
"width": {
"type": [
"integer",
"null"
],
"description": "width of the preview image",
"format": "int64"
}
}
},
"Provider463397119C53_SerpGoogleAdsSearchTaskPostRequestInfo": {
"type": "object",
"properties": {
"advertiser_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "target is not specifiedadvertiser_ids values for this parameter can be found in the Google Ads Advertisers endpoint;advertiser_ids is not specifiedlocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_search/locations2840location_name, location_code, or location_coordinate, the ads will be searched across all the available locations40700
Your account will be billed per each SERP containing up to 40 results;
You will be additionally charged for the tasks with high execution priority.$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvancedlocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ads_search/locationsLondon,England,United Kingdomlocation_name, location_code, or location_coordinate, the ads will be searched across all the available locationslocation_name or location_code52.6178549,-155.352142location_name, location_code, or location_coordinate, the ads will be searched across all the available locationstag value in the data object of the responseall, google_play, google_maps, google_search, google_shopping, youtubeallall, text, image, videodate_to is specified; \"yyyy-mm-dd\"\"2020-01-01\"date_from is specified; \"yyyy-mm-dd\"\"2020-01-01\"
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsSearchTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAdsSearchTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAdsSearchTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleAiModeLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Provider463397119C53_SerpGoogleAiModeLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationslanguage_name;language_name;language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languagesdesktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationslanguage_code;language_code;language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages;desktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsefalsetrue, the charge per task will be multiplied by 2240-9999;1920 for desktop;360 for mobile on android;375 for mobile on iOS;calculate_rectangles to true240-9999;1080 for desktop;640 for mobile on android;812 for mobile on iOS;calculate_rectangles to true0.5-3;1 for desktop;3 for mobile on android;3 for mobile on iOS;calculate_rectangles to truelocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,18z
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, the value will be null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewInfo"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_AiModeAiOverviewInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"page": {
"type": [
"integer",
"null"
],
"description": "SERP page
SERP page on which the element ranks"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
the text of the ai_overview formatted in the markdown markup language"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
"description": "items present in the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "additional references relevant to the item
includes references to webpages that may have been used to generate the ai_overview"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP
equals null if calculate_rectangles in the POST request is not set to true"
}
}
},
"Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"ai_overview_element": "#/components/schemas/Response463397119C53_SerpApiAiModeAiOverviewElementItem",
"ai_overview_expanded_element": "#/components/schemas/Response463397119C53_SerpApiAiModeAiOverviewExpandedElementItem",
"ai_overview_video_element": "#/components/schemas/Response463397119C53_SerpApiAiModeAiOverviewVideoElementItem",
"ai_overview_table_element": "#/components/schemas/Response463397119C53_SerpApiAiModeAiOverviewTableElementItem",
"ai_overview_shopping": "#/components/schemas/Response463397119C53_SerpApiAiModeAiOverviewShoppingItem",
"ai_overview_paid": "#/components/schemas/Response463397119C53_SerpApiAiModeAiOverviewPaidItem"
}
}
},
"Response463397119C53_SerpApiAiModeAiOverviewElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"text": {
"type": [
"string",
"null"
],
"description": "text or description of the element in SERP"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeLinkElementInfo"
}
]
},
"description": "website links featured in the element
if there are none, equals null"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element
if there are none, equals null"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
}
]
},
"Response463397119C53_AiModeLinkElementInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"description": {
"type": [
"string",
"null"
],
"description": "link description"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
}
}
},
"Response463397119C53_SerpApiAiModeAiOverviewExpandedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "link anchor text"
},
"text": {
"type": [
"string",
"null"
],
"description": "reference text
text snippet from the page that was used to generate the ai_overview_element"
},
"components": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewExpandedComponentInfo"
}
]
},
"description": "array of components of the element"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "additional references relevant to the item
includes references to webpages that may have been used to generate the ai_overview"
}
}
}
]
},
"Response463397119C53_AiModeAiOverviewExpandedComponentInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "reference page title"
},
"text": {
"type": [
"string",
"null"
],
"description": "additional text of the element in SERP"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the component
if there are none, equals null"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeLinkElementInfo"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewReferenceInfo"
}
]
},
"description": "references relevant to the element
includes references to webpages that were used to generate the ai_overview_element"
}
}
},
"Response463397119C53_SerpApiAiModeAiOverviewVideoElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information for the video"
},
"url": {
"type": [
"string",
"null"
],
"description": "relevant URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain name of the reference"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"source": {
"type": [
"string",
"null"
],
"description": "reference source name or title"
},
"date": {
"type": [
"string",
"null"
],
"description": "date when the video was published or indexed
example: Apr 26, 2024"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the video was published or indexed
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_SerpApiAiModeAiOverviewTableElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"markdown": {
"type": [
"string",
"null"
],
"description": "text of the component in the markdwon format"
},
"table": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeTableInfo"
}
],
"description": "table present in the element
the header and content of the table present in the element"
}
}
}
]
},
"Response463397119C53_AiModeTableInfo": {
"type": "object",
"properties": {
"table_header": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "content in the header of the table"
},
"table_content": {
"type": [
"array",
"null"
],
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
}
},
"description": "array of contents of the table present in the element
each array represents the table row"
}
}
},
"Response463397119C53_SerpApiAiModeAiOverviewShoppingItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the link"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
the text of the ai_overview formatted in the markdown markup language"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewShoppingElementInfo"
}
]
},
"description": "items of the element"
}
}
}
]
},
"Response463397119C53_AiModeAiOverviewShoppingElementInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"product_id": {
"type": [
"string",
"null"
],
"description": "unique product identifier on Google Shopping
learn more about the parameter in this help center guide"
},
"data_docid": {
"type": [
"string",
"null"
],
"description": "unique identifier of the SERP data element"
},
"gid": {
"type": [
"string",
"null"
],
"description": "global product identifier on Google Shopping
learn more about the parameter in this help center guide"
},
"title": {
"type": [
"string",
"null"
],
"description": "reference page title"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL in link"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in link"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "product rating
the popularity rate based on reviews
if there is none, the value will be null"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "product price
product price details on the seller's website;
if there is none, the value will be null"
},
"seller": {
"type": [
"string",
"null"
],
"description": "product seller
name of the product's seller as displayed in search results"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "additional information about the result"
},
"marketplace": {
"type": [
"string",
"null"
],
"description": "merchant account provider
e-commerce site that hosts products or websites of individual sellers under the same merchant account
example:by Google"
},
"marketplace_url": {
"type": [
"string",
"null"
],
"description": "URL to the merchant account provider
e-commerce site that hosts products or websites of individual sellers under the same merchant account"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
}
}
},
"Response463397119C53_SerpApiAiModeAiOverviewPaidItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiAiModeAiOverviewElementItem"
}
]
},
{
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "introductory text of the element in the response
text preceding the paid ad items"
},
"markdown": {
"type": [
"string",
"null"
],
"description": "content of the element in markdown format
the text of the ai_overview_paid formatted in the markdown markup language"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewPaidElementInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
}
]
},
"Response463397119C53_AiModeAiOverviewPaidElementInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "reference page URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain name of the reference"
},
"ad_aclk": {
"type": [
"string",
"null"
],
"description": "unique ad click referral parameter
using this parameter you can get a URL of the advertisement in Google Shopping Sellers Ad URL"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "displayed name of the advertiser's website"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb path displayed in the ad"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "description text of the ad"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images present in the ad
if there are none, equals null"
}
}
},
"Provider463397119C53_SerpGoogleAiModeLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”;"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages;"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languagesn"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_SerpGoogleAiModeLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleAiModeTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, the value will be null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeAiOverviewInfo"
}
]
},
"description": "items present in the element"
}
}
},
"Response463397119C53_SerpGoogleAiModeTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleAiModeTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationslanguage_name;language_name;language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages
You will be additionally charged for the tasks with high execution priority.desktop, mobiledesktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, htmllocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationslanguage_code;language_code;language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages;desktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsefalsetrue, the charge per task will be multiplied by 2240-9999;1920 for desktop;360 for mobile on android;375 for mobile on iOS;calculate_rectangles to true240-9999;1080 for desktop;640 for mobile on android;812 for mobile on iOS;calculate_rectangles to true0.5-3;1 for desktop;3 for mobile on android;3 for mobile on iOS;calculate_rectangles to truelocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,18z
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAiModeTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAiModeTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleAutocompleteLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name;location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_name;language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en0keyword|which query are s - \"cursor_pointer\": 0which query is s| - \"cursor_pointer\": 16which que|ry is s - \"cursor_pointer\": 9location_codelocation_code;location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/autocomplete/locationsLondon,England,United Kingdomlanguage_codelanguage_code;language_name by making a separate request to https://api.dataforseo.com/v3/serp/google/languagesEnglishchrome — used when google search is opened in google chrome;chrome-omni — used in the address bar in chrome;gws-wiz — used in google search home page;gws-wiz-serp — used in google search engine results page;safari — used when google search is opened in safari browser;firefox — used when google search is opened in firefox browser;psy-ab — may be used when google search is opened in google chrome browser;toolbar — returns XML;youtube — returns JSONP;gws-wiz-local — used in google local;img — used in google's image search;products-cc — used in google shopping searchtag value in the data object of the response
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, will equal null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:autocomplete"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Autocomplete"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_Autocomplete": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"relevance": {
"type": [
"integer",
"null"
],
"description": "relevance of suggested keyword
represents the relevant of the autocomplete suggestion to the target keyword
can take values from 500 to 2000
the higher the value, the more relevant is the suggestion
Note: only available for the following client:chrome/chrome-omni"
},
"suggestion": {
"type": [
"string",
"null"
],
"description": "google autocomplete keyword suggestion"
},
"suggestion_type": {
"type": [
"string",
"null"
],
"description": "google autocomplete suggestion type
Note: only available for the following client:chrome/chrome-omni"
},
"search_query_url": {
"type": [
"string",
"null"
],
"description": "url to search results
url to search results relevant to the google autocomplete suggestion"
},
"thumbnail_url": {
"type": [
"string",
"null"
],
"description": "url of the thumbnail image
url of the thumbnail image of the google autocomplete suggestion
Note: only available for the following client:gws-wizgws-wiz-serp"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords highlighted in autocomplete
contains a list of google autocomplete suggestions that are highlighted in the search bar;
Note: array is only available for the following client:gws-wizpsy-abgws-wiz-local"
}
}
},
"Response463397119C53_SerpGoogleAutocompleteTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAutocompleteTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAutocompleteTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAutocompleteTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAutocompleteTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, will equal null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:autocomplete"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Autocomplete"
}
]
},
"description": "items of the element"
}
}
},
"Provider463397119C53_SerpGoogleAutocompleteTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name;location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_name;language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en0keyword|which query are s - \"cursor_pointer\": 0which query is s| - \"cursor_pointer\": 16which que|ry is s - \"cursor_pointer\": 9
You will be additionally charged for the tasks with high execution priority;$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be url-encoded;# character will be encoded into %23postback_urladvancedchrome — used when google search is opened in google chrome;chrome-omni — used in the address bar in chrome;gws-wiz — used in google search home page;gws-wiz-serp — used in google search engine results page;safari — used when google search is opened in safari browser;firefox — used when google search is opened in firefox browser;psy-ab — may be used when google search is opened in google chrome browser;toolbar — returns XML;youtube — returns JSONP;gws-wiz-local — used in google local;img — used in google's image search;products-cc — used in google shopping searchlocation_codelocation_code;location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/autocomplete/locationsLondon,England,United Kingdomlanguage_codelanguage_code;language_name by making a separate request to https://api.dataforseo.com/v3/serp/google/languagesEnglishtag value in the data object of the response
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleAutocompleteTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAutocompleteTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleAutocompleteTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleAutocompleteTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleAutocompleteTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleDatasetInfoLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"dataset_id": {
"type": "string",
"description": "dataset item of Google Dataset Search resultL2cvMTFqbl85ZHN6MQ==language_nameendesktoplanguage_codeEnglishwindows, macoswindowstag value in the data object of the response
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item type: dataset"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Dataset"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_Dataset": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"dataset_id": {
"type": [
"string",
"null"
],
"description": "ID of the dataset"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"scholarly_citations_count": {
"type": [
"integer",
"null"
],
"description": "count of articles that refer to the dataset",
"format": "int64"
},
"scholarly_articles_url": {
"type": [
"string",
"null"
],
"description": "url of scholarly articles
link to the list of scholarly articles on Google Scholar
example: https://scholar.google.com/scholar?q=%2210.6084%20m9%20figshare%207427933%20v1%22"
},
"unique_identifier": {
"type": [
"string",
"null"
],
"description": "digital identifier of an object
unique digital identifier of the dataset
example: https://doi.org/10.5061/dryad.hmgqnk9m3"
},
"related_article": {
"type": [
"string",
"null"
],
"description": "link to related article
link to the published article that is related to the dataset"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google Dataset's search results
if there are none, equals null"
},
"dataset_providers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "the list of institutions that provided the dataset"
},
"formats": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FormatsElement"
}
]
},
"description": "the list of file formats of the dataset"
},
"authors": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AuthorsElement"
}
]
},
"description": "the list of authors of the dataset"
},
"licenses": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AmazonLabelElement"
}
]
},
"description": "the list of licenses issued to the dataset"
},
"updated_date": {
"type": [
"string",
"null"
],
"description": "date and time when the result was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2022-11-27 02:00:00 +00:00"
},
"area_covered": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "the list of areas covered in the dataset
for example: Africa, Global"
},
"period_covered": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PeriodCovered"
}
],
"description": "period covered in the dataset"
},
"dataset_description": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_DatasetDescription"
}
],
"description": "description of the dataset"
}
}
},
"Response463397119C53_FormatsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"format": {
"type": [
"string",
"null"
],
"description": "type of file format of the dataset
for example: zip, html, csv"
},
"size": {
"type": [
"integer",
"null"
],
"description": "file size in bytes",
"format": "int64"
}
}
},
"Response463397119C53_AuthorsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"name": {
"type": [
"string",
"null"
],
"description": "name of the dataset author"
},
"url": {
"type": [
"string",
"null"
],
"description": "author’s link URL"
},
"domain": {
"type": [
"string",
"null"
],
"description": "author’s link domain"
}
}
},
"Response463397119C53_PeriodCovered": {
"type": "object",
"properties": {
"start_date": {
"type": [
"string",
"null"
],
"description": "date and time when the period starts
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2020-03-02 02:00:00 +00:00"
},
"end_date": {
"type": [
"string",
"null"
],
"description": "date and time when the period ends
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2022-12-09 02:00:00 +00:00"
},
"displayed_date": {
"type": [
"string",
"null"
],
"description": "period displayed in SERP
example:Mar 2, 2020 - Dec 9, 2022"
}
}
},
"Response463397119C53_DatasetDescription": {
"type": "object",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "text of the description"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "links featured in the 'dataset_description'"
}
}
},
"Response463397119C53_SerpGoogleDatasetInfoTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetInfoTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetInfoTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetInfoTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetInfoTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item type: dataset"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Dataset"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleDatasetInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"dataset_id": {
"type": "string",
"description": "dataset item of Google Dataset Search resultL2cvMTFqbl85ZHN6MQ==language_nameen
You will be additionally charged for the tasks with high execution priority.desktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvancedlanguage_codeEnglishwindows, macoswindowstag value in the data object of the response
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetInfoTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetInfoTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetInfoTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetInfoTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetInfoTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleDatasetSearchLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelanguage_namelanguage_nameen20200
Your account will be billed per each SERP containing up to 20 results;desktoplanguage_codeEnglishwindows, macoswindowstag value in the data object of the response1m, 1y, 3yother, archive, text, image, document, tabularcommercial, noncommercialtrue, falsehumanities, social_sciences, life_sciences, agriculture, natural_sciences, geo, computer, architecture_and_urban_planning, engineering
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item type: dataset"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Dataset"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_SerpGoogleDatasetSearchTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetSearchTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetSearchTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetSearchTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetSearchTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item type: dataset"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Dataset"
}
]
},
"description": "items of the element"
}
}
},
"Provider463397119C53_SerpGoogleDatasetSearchTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”.keyword and keywords fields in DataForSEO APIs in this Help Center articleen20700
Your account will be billed per each SERP containing up to 20 results;
You will be additionally charged for the tasks with high execution priority.desktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvancedlanguage_codeEnglishwindows, macoswindowstag value in the data object of the response1m, 1y, 3yother, archive, text, image, document, tabularcommercial, noncommercialtrue, falsehumanities, social_sciences, life_sciences, agriculture, natural_sciences, geo, computer, architecture_and_urban_planning, engineering
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetSearchTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetSearchTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetSearchTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleDatasetSearchTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleDatasetSearchTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleFinanceExploreLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktoplocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsetop_stories, local_market, world_marketstop_storieslocal_market or world_markets, the charge per task will be multiplied by 2
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_hero_groups, google_finance_interested, google_finance_news, google_finance_earnings_calendar, google_finance_most_followed, google_finance_market_trends, google_finance_people_also_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_BaseSerpApiGoogleFinanceElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"google_finance_asset_pair_element": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceAssetPairElementElementItem",
"google_finance_market_index_element": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceMarketIndexElementElementItem",
"google_finance_market_instrument_element": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceMarketInstrumentElementElementItem",
"google_finance_hero_groups": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceHeroGroupsElementItem",
"google_finance_interested": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceInterestedElementItem",
"google_finance_news": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceNewsElementItem",
"google_finance_earnings_calendar": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceEarningsCalendarElementItem",
"google_finance_most_followed": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceMostFollowedElementItem",
"google_finance_market_trends": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceMarketTrendsElementItem",
"google_finance_people_also_search": "#/components/schemas/Response463397119C53_SerpApiGoogleFinancePeopleAlsoSearchElementItem",
"google_finance_explore_market_trends": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceExploreMarketTrendsElementItem",
"google_finance_quote": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceQuoteElementItem",
"google_finance_compare_to": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceCompareToElementItem",
"google_finance_financial": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceFinancialElementItem",
"google_finance_futures_chain": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceFuturesChainElementItem",
"google_finance_details": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceDetailsElementItem",
"google_finance_about": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceAboutElementItem"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceAssetPairElementElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"base_symbol": {
"type": [
"string",
"null"
],
"description": "identifier of the base asset in a pair
example: EUR"
},
"quote_symbol": {
"type": [
"string",
"null"
],
"description": "identifier of the quote asset in a pair
example: USD"
},
"base_display_name": {
"type": [
"string",
"null"
],
"description": "full name of the base asset in a pair
example: Euro"
},
"quote_display_name": {
"type": [
"string",
"null"
],
"description": "full name of the base asset in a pair
example: Euro"
},
"price": {
"type": [
"number",
"null"
],
"description": "value of the base asset compared to the quote asset"
},
"price_delta": {
"type": [
"number",
"null"
],
"description": "change in price
change in price at a given timestamp"
},
"identifier": {
"type": [
"string",
"null"
],
"description": "identifier of the element
full identifier of the element that consists from ticker and market_identifier
example: PX1:INDEXDB"
},
"displayed_name": {
"type": [
"string",
"null"
],
"description": "name of the market index as displayed on Google Finance
example: CAC 40"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the page of the market index on Google Finance"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the market index
example: Europe/Paris"
},
"trend": {
"type": [
"string",
"null"
],
"description": "growth trend of the market index
possible values: up, down, stable"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"percentage_delta": {
"type": [
"number",
"null"
],
"description": "percentage of change in value of the market index"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceMarketIndexElementElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"ticker": {
"type": [
"string",
"null"
],
"description": "ticker of the market index
example: DAX"
},
"market_identifier": {
"type": [
"string",
"null"
],
"description": "market identifier
example: INDEXDB"
},
"index_value": {
"type": [
"number",
"null"
],
"description": "value of the market index
numerical value of the index at a given timestamp"
},
"index_value_delta": {
"type": [
"number",
"null"
],
"description": "change in value of the market index
change in the index_value at a given timestamp"
},
"identifier": {
"type": [
"string",
"null"
],
"description": "identifier of the element
full identifier of the element that consists from ticker and market_identifier
example: PX1:INDEXDB"
},
"displayed_name": {
"type": [
"string",
"null"
],
"description": "name of the market index as displayed on Google Finance
example: CAC 40"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the page of the market index on Google Finance"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the market index
example: Europe/Paris"
},
"trend": {
"type": [
"string",
"null"
],
"description": "growth trend of the market index
possible values: up, down, stable"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"percentage_delta": {
"type": [
"number",
"null"
],
"description": "percentage of change in value of the market index"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceMarketInstrumentElementElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"ticker": {
"type": [
"string",
"null"
],
"description": "ticker of the market index
example: DAX"
},
"price": {
"type": [
"number",
"null"
],
"description": "value of the base asset compared to the quote asset"
},
"price_delta": {
"type": [
"number",
"null"
],
"description": "change in price
change in price at a given timestamp"
},
"price_currency": {
"type": [
"string",
"null"
],
"description": "price currency
example: USD"
},
"identifier": {
"type": [
"string",
"null"
],
"description": "identifier of the element
full identifier of the element that consists from ticker and market_identifier
example: PX1:INDEXDB"
},
"displayed_name": {
"type": [
"string",
"null"
],
"description": "name of the market index as displayed on Google Finance
example: CAC 40"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the page of the market index on Google Finance"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the market index
example: Europe/Paris"
},
"trend": {
"type": [
"string",
"null"
],
"description": "growth trend of the market index
possible values: up, down, stable"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"percentage_delta": {
"type": [
"number",
"null"
],
"description": "percentage of change in value of the market index"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceHeroGroupsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"markets": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Markets"
}
]
},
"description": "financial markets data
array of items containing market indexes and other financial information related to these indexes"
}
}
}
]
},
"Response463397119C53_Markets": {
"type": "object",
"properties": {
"market": {
"type": [
"string",
"null"
],
"description": "financial market identifier
possible values: US, Europe, Asia, Currencies, Crypto, Futures"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceInterestedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceNewsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the news element
example: In the news"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "sub-title of the news element
example: Based on Europe, Middle East, and Africa"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceNewsElement"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_GoogleFinanceNewsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the news article"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the page of the market index on Google Finance"
},
"source": {
"type": [
"string",
"null"
],
"description": "name of the news source
name of the website where the news article is published"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "featured image URL
URL of the news article's featured image"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"quotes": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes quoted in the news article
information about market indexes quoted in the google_finance_news_element"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceEarningsCalendarElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceEarningsCalendarElement"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_GoogleFinanceEarningsCalendarElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the news article"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the page of the market index on Google Finance"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceMostFollowedElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceMarketTrendsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreAdvancedItem"
}
],
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreAdvancedItem": {
"type": "object",
"properties": {
"most_active": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceMarketTrendsElement"
}
]
},
"description": "array of items
this array can take the following names: most_active, gainers, losers"
},
"gainers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceMarketTrendsElement"
}
]
}
},
"losers": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceMarketTrendsElement"
}
]
}
}
}
},
"Response463397119C53_GoogleFinanceMarketTrendsElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"quote": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
],
"description": "object of items
array contains the following type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
},
"news": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceNewsElement"
}
]
},
"description": "array of items
array contains the following type of items: google_finance_news_element"
}
}
},
"Response463397119C53_SerpApiGoogleFinancePeopleAlsoSearchElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceExploreMarketTrendsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the market trends element
example: Europe, Middle East, and Africa"
},
"sub_title": {
"type": [
"string",
"null"
],
"description": "sub-title of the market trends element"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to finance pair on Google Finance"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceQuoteElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"quote": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
],
"description": "quoted market indexes"
},
"graph_items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GraphItems"
}
]
},
"description": "values on graph"
}
}
}
]
},
"Response463397119C53_GraphItems": {
"type": "object",
"properties": {
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"value": {
"type": [
"number",
"null"
],
"description": "point value on graph"
},
"volume": {
"type": [
"number",
"null"
],
"description": "volume value on graph"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceCompareToElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes data
array of items containing market indexes data;
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceFinancialElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"quarterly_metrics": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceMetricsBundleInfo"
}
]
},
"description": "quarterly google finance metrics"
},
"annual_metrics": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceMetricsBundleInfo"
}
]
},
"description": "annual google finance metrics"
}
}
}
]
},
"Response463397119C53_GoogleFinanceMetricsBundleInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"revenue": {
"type": [
"number",
"null"
],
"description": "revenue value"
},
"revenue_delta": {
"type": [
"number",
"null"
],
"description": "change in revenue"
},
"operating_expense": {
"type": [
"number",
"null"
],
"description": "operating expense value"
},
"operating_expense_delta": {
"type": [
"number",
"null"
],
"description": "change in operating expense"
},
"net_income": {
"type": [
"number",
"null"
],
"description": "net income value"
},
"net_income_delta": {
"type": [
"number",
"null"
],
"description": "change in net income"
},
"net_profit_margin": {
"type": [
"number",
"null"
],
"description": "net profit margin value"
},
"net_profit_margin_delta": {
"type": [
"number",
"null"
],
"description": "change in net profit margin"
},
"earnings_per_share": {
"type": [
"number",
"null"
],
"description": "earnings per share value"
},
"earnings_per_share_delta": {
"type": [
"number",
"null"
],
"description": "change in earnings per share"
},
"ebitda": {
"type": [
"number",
"null"
],
"description": "earnings before interest, taxes, deprecation, amortisation"
},
"ebitda_delta": {
"type": [
"number",
"null"
],
"description": "change in ebitda"
},
"effective_tax_rate": {
"type": [
"number",
"null"
],
"description": "effective tax rate value"
},
"cash_and_short_term_investments": {
"type": [
"number",
"null"
],
"description": "cash and short-term investments value"
},
"cash_and_short_term_investments_delta": {
"type": [
"number",
"null"
],
"description": "change in cash and short-term investments"
},
"total_assets": {
"type": [
"number",
"null"
],
"description": "total assets value"
},
"total_assets_delta": {
"type": [
"number",
"null"
],
"description": "change in total assets"
},
"total_liabilities": {
"type": [
"number",
"null"
],
"description": "total liabilities value"
},
"total_liabilities_delta": {
"type": [
"number",
"null"
],
"description": "change in total liabilities"
},
"total_equity": {
"type": [
"number",
"null"
],
"description": "total equity value"
},
"shares_outstanding": {
"type": [
"number",
"null"
],
"description": "outstanding shares value"
},
"price_to_book": {
"type": [
"number",
"null"
],
"description": "price to book"
},
"return_on_assets": {
"type": [
"number",
"null"
],
"description": "return on assets"
},
"return_on_capital": {
"type": [
"number",
"null"
],
"description": "return on capital"
},
"cash_from_operations": {
"type": [
"number",
"null"
],
"description": "cash from operations"
},
"cash_from_operations_delta": {
"type": [
"number",
"null"
],
"description": "change in cash from operations"
},
"cash_from_investing": {
"type": [
"number",
"null"
],
"description": "cash from investing"
},
"cash_from_investing_delta": {
"type": [
"number",
"null"
],
"description": "change in cash from investing"
},
"cash_from_financing": {
"type": [
"number",
"null"
],
"description": "cash from financing/em>"
},
"cash_from_financing_delta": {
"type": [
"number",
"null"
],
"description": "change in cash from financing"
},
"net_change_in_cash": {
"type": [
"number",
"null"
],
"description": "net change in cash"
},
"net_change_in_cash_delta": {
"type": [
"number",
"null"
],
"description": "change in net change in cash"
},
"free_cash_flow": {
"type": [
"number",
"null"
],
"description": "free cash flow value"
},
"free_cash_flow_delta": {
"type": [
"number",
"null"
],
"description": "change in free cash flow"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceFuturesChainElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"markets": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleFinanceFuturesChainElement"
}
]
},
"description": "financial markets data
array of items containing market indexes and other financial information related to these indexes"
}
}
}
]
},
"Response463397119C53_GoogleFinanceFuturesChainElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"expiration_timestamp": {
"type": [
"string",
"null"
],
"description": "futures' date and time of expiration
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"symbol": {
"type": [
"string",
"null"
],
"description": "futures' symbol"
},
"price": {
"type": [
"number",
"null"
],
"description": "price of the market instrument
price of the market instrument at a given timestamp"
},
"price_currency": {
"type": [
"string",
"null"
],
"description": "currency of the price value"
},
"price_delta": {
"type": [
"number",
"null"
],
"description": "change in price of the market instrument
change in price at a given timestamp"
},
"percentage_delta": {
"type": [
"number",
"null"
],
"description": "percentage of change in value of the market index"
},
"trend": {
"type": [
"string",
"null"
],
"description": "growth trend of the market index
possible values: up, down, stable"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceDetailsElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"badges": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "google finance badges relevant to the element
example: Futures Contract"
},
"previous_close": {
"type": [
"number",
"null"
],
"description": "value of the previous close"
},
"start_day_range": {
"type": [
"number",
"null"
],
"description": "value of the start day range"
},
"end_day_range": {
"type": [
"number",
"null"
],
"description": "value of the end day range"
},
"start_year_range": {
"type": [
"number",
"null"
],
"description": "value of the start year range"
},
"end_year_range": {
"type": [
"number",
"null"
],
"description": "value of the end year range"
},
"market_cap": {
"type": [
"number",
"null"
],
"description": "market cap value"
},
"volume": {
"type": [
"number",
"null"
],
"description": "total volume value"
},
"avg_volume": {
"type": [
"number",
"null"
],
"description": "average volume value"
},
"pe_ratio": {
"type": [
"number",
"null"
],
"description": "price-earnings ratio"
},
"dividend_yield": {
"type": [
"number",
"null"
],
"description": "dividend yield value"
},
"primary_exchange": {
"type": [
"string",
"null"
],
"description": "primary exchange value"
},
"ytd_return": {
"type": [
"number",
"null"
],
"description": "year-to-date return value"
},
"expense_ratio": {
"type": [
"number",
"null"
],
"description": "expense ratio value"
},
"category": {
"type": [
"string",
"null"
],
"description": "category name"
},
"net_assets": {
"type": [
"number",
"null"
]
},
"yield": {
"type": [
"number",
"null"
],
"description": "yield value"
},
"front_load": {
"type": [
"number",
"null"
],
"description": "front load value"
},
"market_segment": {
"type": [
"string",
"null"
],
"description": "name of the relevant market segment"
},
"open_interest": {
"type": [
"number",
"null"
],
"description": "open interest value"
},
"settlement_price": {
"type": [
"number",
"null"
],
"description": "settlement price value"
},
"cdp_climate_change_score": {
"type": [
"string",
"null"
],
"description": "climate change score by carbon disclosure project methodology"
},
"metrics_currency": {
"type": [
"string",
"null"
],
"description": "currency of the metrics"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceAboutElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
{
"type": "object",
"properties": {
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"displayed_name": {
"type": [
"string",
"null"
],
"description": "displayed name of the market index
example: E-mini Dow ($5)"
},
"description": {
"type": [
"string",
"null"
],
"description": "company description"
},
"description_source_url": {
"type": [
"string",
"null"
],
"description": "source of information provided in description"
},
"ceo": {
"type": [
"string",
"null"
],
"description": "Chief Executive Officer of the company"
},
"founded": {
"type": [
"string",
"null"
],
"description": "date when the company was founded
in the format: \"yyyy-mm-ddThh-mm-ssZ\"
example:1993-04-05T00:00:00Z"
},
"headquarters": {
"type": [
"string",
"null"
],
"description": "company headquarters"
},
"website": {
"type": [
"string",
"null"
],
"description": "company website"
},
"employees": {
"type": [
"integer",
"null"
],
"description": "number of company employees"
}
}
}
]
},
"Provider463397119C53_SerpGoogleFinanceExploreLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktoplocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsetop_stories, local_market, world_marketstop_stories
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleFinanceExploreTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_hero_groups, google_finance_interested, google_finance_news, google_finance_earnings_calendar, google_finance_most_followed, google_finance_market_trends, google_finance_people_also_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes related to the market trends element
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
},
"Response463397119C53_SerpGoogleFinanceExploreTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleFinanceExploreTaskPostRequestInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, html
You will be additionally charged for the tasks with high execution priority;location_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsetop_stories, local_market, world_marketstop_storieslocal_market or world_markets, the charge per task will be multiplied by 2
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceExploreTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceExploreTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleFinanceMarketsLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktoplocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsemost-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currenciesmost-active
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, the value will be null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_hero_groups, google_finance_explore_market_trends, google_finance_news, google_finance_interested, google_finance_people_also_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleFinanceMarketsLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktoplocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsemost-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currenciesmost-active
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleFinanceMarketsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceMarketsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceMarketsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_hero_groups, google_finance_explore_market_trends, google_finance_news, google_finance_interested, google_finance_people_also_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes related to the market trends element
possible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element"
}
}
},
"Response463397119C53_SerpGoogleFinanceMarketsTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceMarketsTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceMarketsTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleFinanceMarketsTaskPostRequestInfo": {
"type": "object",
"properties": {
"location_code": {
"type": "integer",
"description": "location_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, html
You will be additionally charged for the tasks with high execution priority;location_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsemost-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currenciesmost-active
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceMarketsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceMarketsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceMarketsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleFinanceQuoteLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword field;keyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktoplocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsegoogle_finance_quote graph1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAX1D1D, the charge per task will be multiplied by 2
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_hero_groups, google_finance_quote, google_finance_compare_to, google_finance_news, google_finance_financial, google_finance_futures_chain, google_finance_details, google_finance_about, google_finance_interested, google_finance_people_also_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleFinanceQuoteLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword field;keyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktoplocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsegoogle_finance_quote graph1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAX1D
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleFinanceQuoteTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceQuoteTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceQuoteTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_hero_groups, google_finance_quote, google_finance_compare_to, google_finance_news, google_finance_financial, google_finance_futures_chain, google_finance_details, google_finance_about, google_finance_interested, google_finance_people_also_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceElementItem"
}
]
},
"description": "market indexes related to the market trends element"
}
}
},
"Response463397119C53_SerpGoogleFinanceQuoteTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceQuoteTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceQuoteTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleFinanceQuoteTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword field;keyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:endesktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, html
You will be additionally charged for the tasks with high execution priority;location_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindowstag value in the data object of the responsegoogle_finance_quote graph1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAX1D1D, the charge per task will be multiplied by 2
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceQuoteTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceQuoteTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceQuoteTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleFinanceTickerSearchLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword field;keyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:enlocation_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishtag value in the data object of the responseall, stock, index, mutual_fund, currency, futuresall
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceTickerSearchElementItem"
}
]
},
"description": "items of search results found in SERP
array of items containing market indexes data;
possible type of items: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument"
}
}
},
"Response463397119C53_BaseSerpApiGoogleFinanceTickerSearchElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"identifier": {
"type": [
"string",
"null"
],
"description": "identifier of the element
full identifier of the element that consists from ticker and market_identifier
example: PX1:INDEXDB"
},
"displayed_name": {
"type": [
"string",
"null"
],
"description": "name of the market index as displayed on Google Finance
example: CAC 40"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the page of the market index on Google Finance"
},
"location": {
"type": [
"string",
"null"
],
"description": "location of the market index
example: Europe/Paris"
},
"trend": {
"type": [
"string",
"null"
],
"description": "growth trend of the market index
possible values: up, down, stable"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time of the value readout
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2025-02-10 09:40:00 +00:00"
},
"percentage_delta": {
"type": [
"number",
"null"
],
"description": "percentage of change in value of the market index"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"google_finance_asset_pair": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceAssetPairElementItem",
"google_finance_market_instrument": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceMarketInstrumentElementItem",
"google_finance_market_index": "#/components/schemas/Response463397119C53_SerpApiGoogleFinanceMarketIndexElementItem"
}
}
},
"Response463397119C53_SerpApiGoogleFinanceAssetPairElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceTickerSearchElementItem"
}
]
},
{
"type": "object",
"properties": {
"base_symbol": {
"type": [
"string",
"null"
],
"description": "identifier of the base asset in a pair
example: EUR"
},
"quote_symbol": {
"type": [
"string",
"null"
],
"description": "identifier of the quote asset in a pair
example: USD"
},
"base_display_name": {
"type": [
"string",
"null"
],
"description": "full name of the base asset in a pair
example: Euro"
},
"quote_display_name": {
"type": [
"string",
"null"
],
"description": "full name of the base asset in a pair
example: Euro"
},
"price": {
"type": [
"number",
"null"
],
"description": "value of the base asset compared to the quote asset"
},
"price_delta": {
"type": [
"number",
"null"
],
"description": "change in price
change in price at a given timestamp"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceMarketInstrumentElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceTickerSearchElementItem"
}
]
},
{
"type": "object",
"properties": {
"ticker": {
"type": [
"string",
"null"
],
"description": "ticker of the market index
example: DAX"
},
"price": {
"type": [
"number",
"null"
],
"description": "value of the base asset compared to the quote asset"
},
"price_delta": {
"type": [
"number",
"null"
],
"description": "change in price
change in price at a given timestamp"
},
"price_currency": {
"type": [
"string",
"null"
],
"description": "price currency
example: USD"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleFinanceMarketIndexElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceTickerSearchElementItem"
}
]
},
{
"type": "object",
"properties": {
"ticker": {
"type": [
"string",
"null"
],
"description": "ticker of the market index
example: DAX"
},
"market_identifier": {
"type": [
"string",
"null"
],
"description": "market identifier
example: INDEXDB"
},
"index_value": {
"type": [
"number",
"null"
],
"description": "value of the market index
numerical value of the index at a given timestamp"
},
"index_value_delta": {
"type": [
"number",
"null"
],
"description": "change in value of the market index
change in the index_value at a given timestamp"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceTickerSearchTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceTickerSearchTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceTickerSearchTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceTickerSearchTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceTickerSearchTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
in this case, the value will be null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP;
possible item types: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleFinanceTickerSearchElementItem"
}
]
},
"description": "items of search results found in SERP
array of items containing market indexes data;
possible type of items: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument"
}
}
},
"Provider463397119C53_SerpGoogleFinanceTickerSearchTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword field;keyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_namelocation_namelocation_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, html
You will be additionally charged for the tasks with high execution priority;location_codelocation_codelocation_name by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_code language_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishtag value in the data object of the responseall, stock, index, mutual_fund, currency, futuresall
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceTickerSearchTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceTickerSearchTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceTickerSearchTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleFinanceTickerSearchTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleFinanceTickerSearchTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleImagesLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en100200
Your account will be billed per each SERP containing up to 100 results;location_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindows, macoswindowstag value in the data object of the response100max_crawl_pages and depth parameters complement each other;https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:carousel, images_search, related_searches"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleImagesElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_BaseSerpApiGoogleImagesElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP for the target domain
absolute position among all the elements in SERP"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"carousel": "#/components/schemas/Response463397119C53_SerpApiGoogleImagesCarouselElementItem",
"images_search": "#/components/schemas/Response463397119C53_SerpApiGoogleImagesImagesSearchElementItem",
"related_searches": "#/components/schemas/Response463397119C53_SerpApiGoogleImagesRelatedSearchesElementItem"
}
}
},
"Response463397119C53_SerpApiGoogleImagesCarouselElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleImagesElementItem"
}
]
},
{
"type": "object",
"properties": {
"page": {
"type": [
"integer",
"null"
]
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpApiCarouselElement"
}
]
},
"description": "items of the element"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result’s snippet in SERP
note: calculate_rectangles parameter is not yet available when setting tasks for this search engine type, that’s why rectangle always equals null"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleImagesImagesSearchElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleImagesElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the result in SERP"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "subtitle of the result in SERP"
},
"alt": {
"type": [
"string",
"null"
],
"description": "the alt tag of the image"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"source_url": {
"type": [
"string",
"null"
],
"description": "the URL of the source image"
},
"encoded_url": {
"type": [
"string",
"null"
],
"description": "the URL of the cached version of the image stored on Google's servers"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleImagesRelatedSearchesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleImagesElementItem"
}
]
},
{
"type": "object",
"properties": {
"page": {
"type": [
"integer",
"null"
]
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "items of the element"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result’s snippet in SERP
note: calculate_rectangles parameter is not yet available when setting tasks for this search engine type, that’s why rectangle always equals null"
}
}
}
]
},
"Provider463397119C53_SerpGoogleImagesLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en100200
Your account will be billed per each SERP containing up to 100 results;location_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishwindows, macoswindowstag value in the data object of the response100max_crawl_pages and depth parameters complement each other;https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleImagesTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleImagesTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleImagesTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:carousel, images_search, related_searches"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleImagesElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleImagesTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleImagesTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleImagesTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleImagesTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en100700
Your account will be billed per each SERP containing up to 100 results;
You will be additionally charged for the tasks with high execution priority.$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, htmllocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishwindows, macoswindowstag value in the data object of the response100max_crawl_pages and depth parameters complement each other;https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleImagesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleImagesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleImagesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleJobsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleJobsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleJobsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
in this case, equals null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:google_jobs_item"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_GoogleJobsItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_GoogleJobsItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"job_id": {
"type": [
"string",
"null"
],
"description": "ID of the job on Google Jobs"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"employer_name": {
"type": [
"string",
"null"
],
"description": "name of the employer"
},
"employer_url": {
"type": [
"string",
"null"
],
"description": "URL to the employer's website"
},
"employer_image_url": {
"type": [
"string",
"null"
],
"description": "URL to the image used in the job posting"
},
"location": {
"type": [
"string",
"null"
],
"description": "location for which the job vacancy is posted"
},
"source_name": {
"type": [
"string",
"null"
],
"description": "original source of the job vacancy"
},
"source_url": {
"type": [
"string",
"null"
],
"description": "URL to the original source of the job vacancy"
},
"salary": {
"type": [
"string",
"null"
],
"description": "the salary indicated in the job vacancy
if the salary isn't indicated, this field will equal null"
},
"contract_type": {
"type": [
"string",
"null"
],
"description": "employment contract type"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:2019-11-15 12:57:46 +00:00"
},
"time_ago": {
"type": [
"string",
"null"
],
"description": "indicates how long ago the job vacancy was posted"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP;
in this case, will equal null"
}
}
},
"Response463397119C53_SerpGoogleJobsTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleJobsTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleJobsTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleJobsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;.net developerkeyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name;location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/jobs/locations2840language_namelanguage_name;language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;
You will be additionally charged for the tasks with high execution priority;$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urlregular, advanced, htmllocation_codelocation_code;location_name by making a separate request to https://api.dataforseo.com/v3/serp/google/jobs/locationsLondon,England,United Kingdomlanguage_codelanguage_code;language_name by making a separate request to https://api.dataforseo.com/v3/serp/google/languagesEnglishtag value in the data object of the response1.609;300> 0fulltime, partime, contractor, intern
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleJobsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleJobsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleJobsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Provider463397119C53_SerpGoogleLocalFinderLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesen10100
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the response
You will be additionally charged for the tasks with high execution priority.location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,20z
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array
"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:local_pack"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocalPackSerpElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Provider463397119C53_SerpGoogleLocalFinderLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”location_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesen10100
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responselocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,20zdesktop: 3.5, 4, 4.5;mobile: 2, 2.5, 3, 3.5, 4, 4.5\"open_now\", \"24_hours\", \"$day_value\", \"$day_value;$time_value\";$day_value use one of these values: \"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\", \"saturday\", \"sunday\";$time_value use one of these values: \"00\", \"01\", \"02\", \"03\", \"04\", \"05\", \"06\", \"07\", \"08\", \"09\", \"10\", \"11\", \"12\", \"13\", \"14\", \"15\", \"16\", \"17\", \"18\", \"19\", \"20\", \"21\", \"22\", \"23\"\"tuesday;18\"
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleLocalFinderTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocalFinderTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocalFinderTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:local_pack"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocalPackSerpElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_SerpGoogleLocalFinderTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocalFinderTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocalFinderTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleLocalFinderTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesen10350
your account will be billed per each SERP containing up to 10 results;
setting depth above 10 may result in additional charges if the search engine returns more than 10 results respectively;
The cost can be calculated on the Pricing page."
},
"priority": {
"type": [
"integer",
"null"
],
"description": "
You will be additionally charged for the tasks with high execution priority.desktop, mobiledesktop$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, htmllocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responselocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,18z
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocalFinderTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocalFinderTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocalFinderTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:
`\"location_code\": 9041134`,
`\"location_name\": \"Vienna International Airport,Lower Austria,Austria\"`,
`\"location_code_parent\": 20044`
`\"location_name\": \"Lower Austria,Austria\"`"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
indicates the geographic classification of the location
example:
`\"location_type\": \"Country\"`, or `\"location_type\": \"State\"`"
}
}
},
"Provider463397119C53_SerpGoogleMapsLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en100700
Your account will be billed per each SERP containing up to 100 results;desktop, mobiledesktopmobile device, only 20 results are returned for every SERPlocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the response100max_crawl_pages and depth parameters complement each other;https://google.com/maps/search/pizza/@37.09024,-95.712891,4z
Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: allinanchor:, allintext:, allintitle:, allinurl:, cache:, define:, definition:, filetype:, id:, inanchor:, info:, intext:, intitle:, inurl:, link:, site:."
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,20zgoogle.co.uk, google.com.au, google.de, etc.true, falsetruefalse, the search_this_area mode will be turned offsearch_this_area mode is turned off, Google Maps listings might contain results beyond the displayed areafalse;truesearch_places mode is turned off and no results were found in the search area, the results array will be empty
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array
"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results
Note: to check location-specific results, follow the provided check url, scroll up and down, then click the \"Search this area\" button"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:maps_search, maps_paid_item"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleMapsElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_BaseSerpApiGoogleMapsElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements in SERP"
},
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the element's rating
the popularity rate based on reviews and displayed in SERP"
},
"rating_distribution": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"integer",
"null"
],
"format": "Int64"
},
"description": "the distribution of ratings of the business entity
the object displays the number of 1-star to 5-star ratings, as reviewed by users"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"maps_search": "#/components/schemas/Response463397119C53_SerpApiMapsSearchElementItem",
"maps_paid_item": "#/components/schemas/Response463397119C53_SerpApiMapsPaidItemElementItem"
}
}
},
"Response463397119C53_SerpApiMapsSearchElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleMapsElementItem"
}
]
},
{
"type": "object",
"properties": {
"original_title": {
"type": [
"string",
"null"
],
"description": "original title of the element
original title not translated by Google"
},
"contact_url": {
"type": [
"string",
"null"
],
"description": "URL of the preferred contact page"
},
"contributor_url": {
"type": [
"string",
"null"
],
"description": "URL of the user's or entity's Local Guides profile, if available"
},
"book_online_url": {
"type": [
"string",
"null"
],
"description": "URL in the 'book online' button of the element
URL directing users to the online booking or order page of the business entity"
},
"hotel_rating": {
"type": [
"number",
"null"
],
"description": "hotel class rating
class ratings range between 1-5 stars, learn more
if there is no hotel class rating information, the value will be null"
},
"price_level": {
"type": [
"string",
"null"
],
"description": "property price level
can take values: inexpensive, moderate, expensive, very_expensive
if there is no price level information, the value will be null"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "element snippet
contains the address and other information about the local establishment featured in the element"
},
"address": {
"type": [
"string",
"null"
],
"description": "address line
address of the local establishment featured in the element"
},
"address_info": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AddressInfo"
}
],
"description": "object containing address components of the local establishment"
},
"place_id": {
"type": [
"string",
"null"
],
"description": "unique place identifier
place id of the local establishment featured in the element"
},
"phone": {
"type": [
"string",
"null"
],
"description": "phone number
phone number of the local establishment featured in the element"
},
"main_image": {
"type": [
"string",
"null"
],
"description": "URL of the main image featured in Google My Business profile"
},
"total_photos": {
"type": [
"integer",
"null"
],
"description": "total count of images featured in Google My Business profile",
"format": "int64"
},
"category": {
"type": [
"string",
"null"
],
"description": "business category
Google My Business general category that best describes the services provided by the business entity"
},
"additional_categories": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "additional business categories
additional Google My Business categories that describe the services provided by the business entity in more detail"
},
"category_ids": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "global category IDs
universal category IDs that do not change based on the selected country"
},
"work_hours": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_WorkHours"
}
],
"description": "open hours
information about work hours of the local establishment"
},
"feature_id": {
"type": [
"string",
"null"
],
"description": "the unique identifier of the element in SERP"
},
"cid": {
"type": [
"string",
"null"
],
"description": "google-defined client id
unique id of a local establishment;
can be used with Google Reviews API to get a full list of reviews"
},
"latitude": {
"type": [
"number",
"null"
],
"description": "latitude coordinate of the local establishments in google maps
example:\"latitude\": 51.584091"
},
"longitude": {
"type": [
"number",
"null"
],
"description": "longitude coordinate of the local establishment in google maps
example:\"longitude\": -0.31365919999999997"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "indicates whether ownership of this local establishment is claimed"
},
"local_justifications": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LocalJustificationInfo"
}
]
},
"description": "Google local justifications
snippets of text that \"justify\" why the business is showing up for search query"
},
"is_directory_item": {
"type": [
"boolean",
"null"
],
"description": "indicates whether this local establishment is a directory "
}
}
}
]
},
"Response463397119C53_SerpApiMapsPaidItemElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleMapsElementItem"
}
]
},
{
"type": "object"
}
]
},
"Response463397119C53_SerpGoogleMapsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleMapsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleMapsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleMapsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleMapsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results
Note: to check location-specific results, follow the provided check url, scroll up and down, then click the \"Search this area\" button"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:maps_search, maps_paid_item"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleMapsElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Provider463397119C53_SerpGoogleMapsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en100700
Your account will be billed per each SERP containing up to 100 results;
You will be additionally charged for the tasks with high execution priority.desktop, mobiledesktopmobile device, only 20 results are returned for every SERP$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvancedlocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroid100max_crawl_pages and depth parameters complement each other;https://google.com/maps/search/pizza/@37.09024,-95.712891,4z
Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: allinanchor:, allintext:, allintitle:, allinurl:, cache:, define:, definition:, filetype:, id:, inanchor:, info:, intext:, intitle:, inurl:, link:, site:."
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,zoom\" format52.6178549,-155.352142,20zgoogle.co.uktrue, falsetruefalse, the search_this_area mode will be turned offsearch_this_area mode is turned off, Google Maps listings might contain results beyond the displayed areafalse;default value: truesearch_places mode is turned off and no results were found in the search area, the results array will be emptytag value in the data object of the response
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleMapsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleMapsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleMapsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleMapsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleMapsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleNewsLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;location_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishwindows, macoswindows100max_crawl_pages and depth parameters complement each other;falsetrue, the charge per task will be multiplied by 21920;calculate_rectangles to true1080;calculate_rectangles to true1;calculate_rectangles to truehttps://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200google.co.uk, google.com.au, google.de, etc.
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"includes_non_news_search_results": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the response contains non-news search results in addition to news content"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:top_stories, news_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleNewsElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_BaseSerpApiGoogleNewsElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP
absolute position among all the elements in SERP"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP
equals null if calculate_rectangles in the POST request is not set to true"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"news_search": "#/components/schemas/Response463397119C53_SerpApiGoogleNewsNewsSearchElementItem",
"top_stories": "#/components/schemas/Response463397119C53_SerpApiGoogleNewsTopStoriesElementItem"
}
}
},
"Response463397119C53_SerpApiGoogleNewsNewsSearchElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleNewsElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL of the image
the URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)"
},
"snippet": {
"type": [
"string",
"null"
],
"description": "snippet of the result in SERP"
},
"time_published": {
"type": [
"string",
"null"
],
"description": "indicates the time the result was published"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the news was published
in the format “year-month-date:minutes:UTC_difference_hours:UTC_difference_minutes”
example:2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleNewsTopStoriesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleNewsElementItem"
}
]
},
{
"type": "object",
"properties": {
"page": {
"type": [
"integer",
"null"
]
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:left"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_TopStoriesElement"
}
]
},
"description": "items of the element"
}
}
}
]
},
"Provider463397119C53_SerpGoogleNewsLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;location_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishwindows, macoswindowstag value in the data object of the response100max_crawl_pages and depth parameters complement each other;https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200google.co.uk, google.com.au, google.de, etc.
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleNewsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleNewsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleNewsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"includes_non_news_search_results": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the response contains non-news search results in addition to news content"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:top_stories, news_search"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleNewsElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleNewsTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleNewsTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleNewsTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleNewsTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en10700
Your account will be billed per each SERP containing up to 10 results;
You will be additionally charged for the tasks with high execution priority.$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, htmllocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishwindows, macoswindowstag value in the data object of the response100max_crawl_pages and depth parameters complement each other;falsetrue, the charge per task will be multiplied by 21920;calculate_rectangles to true1080;calculate_rectangles to true1;calculate_rectangles to truehttps://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleNewsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleNewsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleNewsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpGoogleOrganicLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character ‘+’ will be decoded to a space character)if you need to use the “%” character for your keyword, please specify it as “%25”;if you need to use the “+” character for your keyword, please specify it as “%2B”;if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘cache:’, ‘define:’, ‘definition:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘site:’, the charge per task will be multiplied by 5learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location coderequired field if you don't specify location_name or location_coordinateif you use this field, you don't need to specify location_name or location_coordinateyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsexample:2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language codeoptional field if you specify language_nameif you use this field, you don't need to specify language_nameyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depthoptional fieldnumber of results in SERPdefault value: 10max value: 200Your account will be billed per each SERP containing up to 10 results;Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;The cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop"
},
"load_async_ai_overview": {
"type": [
"boolean",
"null"
],
"description": "load asynchronous ai overviewoptional fieldset to true to obtain ai_overview items is SERPs even if they are loaded asynchronously;if set to false, you will only obtain ai_overview items from cache;default value: falseif the element is absent or contains \"asynchronous_ai_overview\": false, all extra charges will be returned to your account balance\n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine locationrequired field if you don't specify location_code or location_coordinateif you use this field, you don't need to specify location_code or location_coordinateyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsexample:London,England,United Kingdom"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine languageoptional field if you specify language_codeif you use this field, you don't need to specify language_codeyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating systemoptional fieldif you specify desktop in the device field, choose from the following values: windows, macosdefault value: windowsif you specify mobile in the device field, choose from the following values: android, iosdefault value: android"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"match_type": {
"type": [
"string",
"null"
],
"description": "target match typerequired field if stop_crawl_on_match is specifiedtype of match for the match_valuepossible values:domain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard pattern"
},
"match_value": {
"type": [
"string",
"null"
],
"description": "target domain, subdomain, or wildcard valuerequired field if stop_crawl_on_match is specifiedspecify a target domain, subdomain, or wildcard value;Note: domain or subdomain must be specified without a request protocol;example: \"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\""
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: you will be charged for each page crawled (10 organic results per page);learn more about pricing on our Pricing page;Note#2: the max_crawl_pages and depth parameters complement each other;learn more at our help center"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details hereNote: the following search engine parameters are not supported and will be automatically unset if specified: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"remove_from_url": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "remove specific parameters from URLsoptional fieldusing this field, you can specify up to 10 parameters to remove from URLs in the resultexample:\"remove_from_url\": [\"srsltid\"]Note: if the target field is specified, the specified URL parameters will be removed before the search"
},
"people_also_ask_click_depth": {
"type": [
"integer",
"null"
],
"description": "clicks on the corresponding elementoptional fieldspecify the click depth on the people_also_ask element to get additional people_also_ask_element items;if the element is absent or we perform fewer clicks than you specified, all extra charges will be returned to your account balancepossible values: from 1 to 4\n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"group_organic_results": {
"type": [
"boolean",
"null"
],
"description": "display related resultsoptional fieldif set to true, the related_result element in the response will be provided as a snippet of its parent organic result;if set to false, the related_result element will be provided as a separate organic result;default value: true"
},
"calculate_rectangles": {
"type": [
"boolean",
"null"
],
"description": "calcualte pixel rankings for SERP elements in advanced resultsoptional fieldpixel ranking refers to the distance between the result snippet and top left corner of the screen;Visit Help Center to learn more>>by default, the parameter is set to false;\n\nFor current API pricing, see the published x-aisa-pricing metadata. Where supported, obtain a quote for your exact request."
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "browser screen widthoptional fieldyou can set a custom browser screen width to calculate pixel rankings for a particular device;can be specified within the following range: 240-9999;by default, the parameter is set to:1920 for desktop;360 for mobile on android;375 for mobile on iOS;Note: to use this parameter, set calculate_rectangles to true",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "browser screen heightoptional fieldyou can set a custom browser screen height to calculate pixel rankings for a particular device;can be specified within the following range: 240-9999;by default, the parameter is set to:1080 for desktop;640 for mobile on android;812 for mobile on iOS;Note: to use this parameter, set calculate_rectangles to true"
},
"browser_screen_resolution_ratio": {
"type": [
"integer",
"null"
],
"description": "browser screen resolution ratiooptional fieldyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;can be specified within the following range: 0.5-3;by default, the parameter is set to:1 for desktop;3 for mobile on android;3 for mobile on iOS;Note: to use this parameter, set calculate_rectangles to true"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search queryoptional fieldyou can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZSNote: the following search engine parameters are not supported and will be automatically unset if specified in the URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a locationoptional field if you specify location_name or location_codeif you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" formatthe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"radius\": 199 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domainoptional fieldwe choose the relevant search engine domain automatically according to the location and language you specifyhowever, you can set a custom search engine domain in this fieldexample:google.co.uk, google.com.au, google.de, etc."
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain, subdomain, or webpage to get results foroptional fielda domain or a subdomain should be specified without https:// and www.note that the results of target-specific tasks will only include SERP elements that contain a url string;you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;examples:example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;example.com* - returns results for the domain, including all its pages;*example.com* - returns results for the entire domain, including all its pages and subdomains;*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;example.com/example-page - returns results for the exact URL;example.com/example-page* - returns results for all domain's URLs that start with the specified string"
},
"target_search_mode": {
"type": [
"string",
"null"
],
"description": "target matching modeoptional fieldto enable this parameter, stop_crawl_on_match must also be enableddefines how the crawl should stop when multiple targets are specified in stop_crawl_on_matchpossible values: all, anyall – the crawl stops only when all specified targets are foundany – the crawl stops when any single target is founddefault value: anylearn more about this parameter on our Help Center"
},
"find_targets_in": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "SERP element types to check for targetsoptional fieldto enable this parameter, stop_crawl_on_match must also be enabledspecifies which SERP element types should be checked for target matchesif not specified, all first-level elements with url and domain fields are checked for targetspossible values: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterNote: cannot contain the same element types as ignore_targets_inexample:\"find_targets_in\": [\"organic\", \"featured_snippet\"]learn more about this parameter on our Help Center"
},
"ignore_targets_in": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "SERP element types to exclude from target searchoptional fieldto enable this parameter, stop_crawl_on_match must also be enabledspecifies which SERP element types should be excluded when searching for target matchespossible values: organic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterNote: cannot contain the same element types as find_targets_inexample:\"ignore_targets_in\": [\"paid\", \"images\"]learn more about this parameter on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein",
"calculate_rectangles": true
}
]
},
"Response463397119C53_SerpGoogleOrganicLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine resultsyou can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was receivedin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engineif the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERPcontains types of search results (items) found in SERP.possible item types:answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, recipes, top_sights, scholarly_articles, popular_products, questions_and_answers, find_results_on, stocks_box, commercial_units, local_services, google_hotels, math_solver, currency_box,product_considerations, short_videos, refine_products, perspectives, discussions_and_forums, compare_sites, ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total search results pages retrievedtotal number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Provider463397119C53_SerpGoogleOrganicLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;location_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoptrue to obtain ai_overview items is SERPs even if they are loaded asynchronously;false, you will only obtain ai_overview items from cache;false\"asynchronous_ai_overview\": false, all extra charges will be returned to your account balancelocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsestop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"100max_crawl_pages and depth parameters complement each other;
Note: the following search engine parameters are not supported and will be automatically unset if specified: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"expand_ai_overview": {
"type": [
"boolean",
"null"
],
"description": "true to expand the ai_overview item;falsehttps://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200google.co.uk, google.com.au, google.de, etc.stop_crawl_on_match must also be enabledstop_crawl_on_matchall, anyall – the crawl stops only when all specified targets are foundany – the crawl stops when any single target is foundanystop_crawl_on_match must also be enabledurl and domain fields are checked for targetsorganic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterignore_targets_in\"find_targets_in\": [\"organic\", \"featured_snippet\"]stop_crawl_on_match must also be enabledorganic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterfind_targets_in\"ignore_targets_in\": [\"paid\", \"images\"]
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpGoogleOrganicLiveRegularRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as \"%25\";keyword, please specify it as “%2B”;location_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en10200
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoplocation_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishdesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidtag value in the data object of the responsestop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"100max_crawl_pages and depth parameters complement each other;
Note: the following search engine parameters are not supported and will be automatically unset if specified: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"group_organic_results": {
"type": [
"boolean",
"null"
],
"description": "true, the related_result element in the response will be provided as a snippet of its parent organic result;false, the related_result element will be provided as a separate organic result;truehttps://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200google.co.uk, google.com.au, google.de, etc.https:// and www.target-specific tasks will only include SERP elements that contain a url string;example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;example.com* - returns results for the domain, including all its pages;*example.com* - returns results for the entire domain, including all its pages and subdomains;*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;example.com/example-page - returns results for the exact URL;example.com/example-page* - returns results for all domain's URLs that start with the specified stringstop_crawl_on_match must also be enabledstop_crawl_on_matchall, anyall – the crawl stops only when all specified targets are foundany – the crawl stops when any single target is foundanystop_crawl_on_match must also be enabledurl and domain fields are checked for targetsorganic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterignore_targets_in\"find_targets_in\": [\"organic\", \"featured_snippet\"]stop_crawl_on_match must also be enabledorganic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterfind_targets_in\"ignore_targets_in\": [\"paid\", \"images\"]
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, recipes, top_sights, scholarly_articles, popular_products, questions_and_answers, find_results_on, stocks_box, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, short_videos, refine_products, perspectives, discussions_and_forums, compare_sites, ai_overview
however, this endpoint provides data for featured_snippet, organic and paid types only
to get all items (inlcuding SERP features and rich snippets) found in the returned SERP, please refer to the Google Organiс Advanced SERP endpoint"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total search results pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items of the element"
}
}
},
"Response463397119C53_SerpGoogleOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, recipes, top_sights, scholarly_articles, popular_products, questions_and_answers, find_results_on, stocks_box, commercial_units, local_services, google_hotels, math_solver, currency_box,product_considerations, short_videos, refine_products, perspectives, discussions_and_forums, compare_sitesai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total search results pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "link of the element"
}
}
},
"Response463397119C53_SerpGoogleOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpGoogleOrganicTaskGetRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTaskGetRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTaskGetRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTaskGetRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTaskGetRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection;
if there is none, the value is null"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
if there are none, the value is null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:answer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, third_party_reviews, images, jobs, knowledge_graph, local_pack, hotels_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, recipes, top_sights, scholarly_articles, popular_products, questions_and_answers, find_results_on, stocks_box, commercial_units, local_services, google_hotels, math_solver, currency_box, product_considerations, short_videos, refine_products, perspectives, discussions_and_forums, compare_sites, ai_overview
however, this endpoint provides data for featured_snippet, organic and paid types only;
to get all items (including SERP features and rich snippets) found in the returned SERP, please refer to the Google Organiс Advanced SERP endpoint"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total search results pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Provider463397119C53_SerpGoogleOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword fieldkeyword, please specify it as “%25”;keyword, please specify it as “%2B”;keyword and keywords fields in DataForSEO APIs in this Help Center articlelocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en10700
Your account will be billed per each SERP containing up to 10 results;desktop, mobiledesktoptrue to obtain ai_overview items is SERPs even if they are loaded asynchronously;false, you will only obtain ai_overview items from cache;false\"asynchronous_ai_overview\": false, all extra charges will be returned to your account balance$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the requesthttp://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urlregular, advanced, html
You will be additionally charged for the tasks with high execution priority.location_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/locationsLondon,England,United Kingdomlocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200language_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesEnglishtag value in the data object of the responsedesktop in the device field, choose from the following values: windows, macoswindowsmobile in the device field, choose from the following values: android, iosandroidstop_crawl_on_match is specifiedmatch_valuedomain – specific domain or subdomainwith_subdomains – main domain and subdomainswildcard – wildcard patternstop_crawl_on_match is specified\"match_value\": \"dataforseo.com\",\"match_value\": \"/blog/post-*\"100max_crawl_pages and depth parameters complement each other;
Note: the following search engine parameters are not supported and will be automatically unset if specified: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"remove_from_url": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "\"remove_from_url\": [\"srsltid\"]true to expand the ai_overview item;false;people_also_ask element to get additional people_also_ask_element items;1 to 4true, the related_result element in the response will be provided as a snippet of its parent organic result;false, the related_result element will be provided as a separate organic result;truefalse240-9999;1920 for desktop;360 for mobile on android;375 for mobile on iOS;calculate_rectangles to true240-9999;1080 for desktop;640 for mobile on android;812 for mobile on iOS;calculate_rectangles to true0.5-3;1 for desktop;3 for mobile on android;3 for mobile on iOS;calculate_rectangles to truehttps://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
Note: the following search engine parameters are not supported and will be automatically unset if specified in the URL: lr, cr, as_qdr, as_sitesearch, as_occt, as_filetype."
},
"target_search_mode": {
"type": [
"string",
"null"
],
"description": "stop_crawl_on_match must also be enabledstop_crawl_on_matchall, anyall – the crawl stops only when all specified targets are foundany – the crawl stops when any single target is foundanystop_crawl_on_match must also be enabledurl and domain fields are checked for targetsorganic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterignore_targets_in\"find_targets_in\": [\"organic\", \"featured_snippet\"]stop_crawl_on_match must also be enabledorganic, paid, local_pack, featured_snippet, events, google_flights, images, jobs, knowledge_graph, local_service, map, scholarly_articles, third_party_reviews, twitterfind_targets_in\"ignore_targets_in\": [\"paid\", \"images\"]google.co.uk, google.com.au, google.de, etc.
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpGoogleSearchByImageTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleSearchByImageTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleSearchByImageTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleSearchByImageTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleSearchByImageTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"image_url": {
"type": [
"string",
"null"
],
"description": "URL specified in a POST array"
},
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword Google associated with the specified image"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:
organic,
images"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleSearchByImagesElementItem"
}
]
},
"description": "items featured in the faq_box"
}
}
},
"Response463397119C53_BaseSerpApiGoogleSearchByImagesElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": "absolute rank in SERP
absolute position among all the elements in SERP"
},
"page": {
"type": [
"integer",
"null"
]
},
"position": {
"type": [
"string",
"null"
],
"description": "the alignment of the element in SERP
can take the following values:
left, right"
},
"xpath": {
"type": [
"string",
"null"
],
"description": "the XPath of the element"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element"
},
"url": {
"type": [
"string",
"null"
],
"description": "search URL with refinement parameters"
},
"rectangle": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeRectangleInfo"
}
],
"description": "rectangle parameters
contains cartesian coordinates and pixel dimensions of the result's snippet in SERP
equals null if calculate_rectangles in the POST request is not set to true"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"organic": "#/components/schemas/Response463397119C53_SerpApiGoogleSearchByImagesOrganicElementItem",
"images": "#/components/schemas/Response463397119C53_SerpApiGoogleSearchByImagesImagesElementItem"
}
}
},
"Response463397119C53_SerpApiGoogleSearchByImagesOrganicElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleSearchByImagesElementItem"
}
]
},
{
"type": "object",
"properties": {
"domain": {
"type": [
"string",
"null"
],
"description": "domain in SERP"
},
"cache_url": {
"type": [
"string",
"null"
],
"description": "cached version of the page"
},
"related_search_url": {
"type": [
"string",
"null"
],
"description": "URL to a similar search
URL to a new search for the same keyword(s) on related sites"
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "breadcrumb in SERP"
},
"website_name": {
"type": [
"string",
"null"
],
"description": "name of the website in SERP"
},
"is_image": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains an image"
},
"is_video": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element contains a video"
},
"is_featured_snippet": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is a featured_snippet"
},
"is_malicious": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as malicious"
},
"is_web_story": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the element is marked as Google web story"
},
"checks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
],
"description": "indicates whether the element contains a video"
}
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the results element in SERP"
},
"pre_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended before the result description in SERP"
},
"extended_snippet": {
"type": [
"string",
"null"
],
"description": "includes additional information appended after the result description in SERP"
},
"images": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "images of the element"
},
"amp_version": {
"type": [
"boolean",
"null"
],
"description": "Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version"
},
"rating": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RatingInfo"
}
],
"description": "the item's rating
the popularity rate based on reviews and displayed in SERP"
},
"price": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PriceInfo"
}
],
"description": "pricing details
contains the pricing details of the product or service featured in the result"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "words highlighted in bold within the results description"
},
"links": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_LinkElement"
}
]
},
"description": "sitelinks
the links shown below some of Google's search results
if there are none, equals null"
},
"faq": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_FaqBox"
}
],
"description": "frequently asked questions
questions and answers extension shown below some of Google's search results
if there are none, equals null",
"deprecated": true
},
"extended_people_also_search": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "extension of the organic element
extension of the organic result containing related search queries
Note: extension appears in SERP upon clicking on the result and then bouncing back to search results"
},
"about_this_result": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AboutThisResultElement"
}
],
"description": "contains information from the 'About this result' panel
'About this result' panel provides additional context about why Google returned this result for the given query;
this feature appears after clicking on the three dots next to most results",
"deprecated": true
},
"related_result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedResult"
}
]
},
"description": "related result from the same domain
related result from the same domain appears as a part of the main result snippet;
you can derive the related_result snippets as \"type\": \"organic\" results by setting the group_organic_results parameter to false in the POST request"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\"
example:
2019-11-15 12:57:46 +00:00"
}
}
}
]
},
"Response463397119C53_SerpApiGoogleSearchByImagesImagesElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiGoogleSearchByImagesElementItem"
}
]
},
{
"type": "object",
"properties": {
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiModeImagesElementInfo"
}
]
},
"description": "elements of search results found in SERP"
},
"related_image_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RelatedImageSearchesElement"
}
]
},
"description": "contains keywords and images related to the specified search term
if there are none, equals null",
"deprecated": true
}
}
}
]
},
"Provider463397119C53_SerpGoogleSearchByImageTaskPostRequestInfo": {
"type": "object",
"properties": {
"image_url": {
"type": "string",
"description": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpglocation_name or location_coordinatelocation_name or location_coordinatelocation_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations2840language_namelanguage_namelanguage_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesexample:en$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagpingback_url will be urlencoded;# character will be encoded into %23gzip format to the postback_url you specified$id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagpostback_url will be urlencoded;# character will be encoded into %23postback_urladvanced, html
You will be additionally charged for the tasks with high execution priority.location_code or location_coordinatelocation_code or location_coordinatelocation_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locationsLondon,England,United Kingdomlanguage_codelanguage_codelanguage_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languagesEnglishtag value in the data object of the response100max_crawl_pages and depth parameters complement each other;falsetrue, the charge per task will be multiplied by 21920;calculate_rectangles to true1080;calculate_rectangles to true1;calculate_rectangles to truelocation_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200google.co.uk, google.com.au, google.de, etc.
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpGoogleSearchByImageTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleSearchByImageTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpGoogleSearchByImageTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpGoogleSearchByImageTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpGoogleSearchByImageTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
can take the following values: search_by_image"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpNaverOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:images, local_pack, map, organic, paid, related_searches, video"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
},
"Response463397119C53_SerpNaverOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpNaverOrganicTaskGetRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskGetRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskGetRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTaskGetRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTaskGetRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:images, local_pack, map, organic, paid, related_searches, video
however, this endpoint provides data for organic and paid types only
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Provider463397119C53_SerpNaverOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields
in most cases, we wouldn’t recommend using this method;
example:https://search.naver.com/search.naver?where=nexearch&sm=top_hty&fbm=1&ie=utf8&query=iphone"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 15
max value: 700
Your account will be billed per each SERP containing up to 15 results;
Setting depth above 15 may result in additional charges if the search engine returns more than 15 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically
however, you can set a custom search engine domain in this field
example:
optional field
get the list of available parameters and additional details here"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:regular, advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpNaverOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpNaverOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpScreenshotRequestInfo": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "task identifier
required field
unique identifier of the associated task in the UUID format
you will be able to use it within 7 days to request the results of the task at any time"
},
"browser_preset": {
"type": [
"string",
"null"
],
"description": "browser resolution preset
optional field
browser preset associated with a certain device type
can take the following values: desktop, tablet, mobile
Note: by default, browser preset corresponds to the device type specified in the POST request"
},
"browser_screen_width": {
"type": [
"integer",
"null"
],
"description": "width of the browser resolution
optional field
can be specified in the following range: 240-9999
default value for desktop: 1920
default value for mobile: 390
default value for table: 1024",
"format": "int64"
},
"browser_screen_height": {
"type": [
"integer",
"null"
],
"description": "height of the browser resolution
optional field
can be specified in the following range: 240-9999
default value for desktop: 1080
default value for mobile: 844
default value for table: 1366"
},
"browser_screen_scale_factor": {
"type": [
"number",
"null"
],
"description": "browser scale factor
optional field
can be specified in the following range: 0.5-3
default value for desktop: 1
default value for mobile: 3
default value for table: 2"
},
"page": {
"type": [
"integer",
"null"
],
"description": "number of SERP pages
optional field
if depth in the corresponding Task POST request exceeds 10 results (or 1 SERP page), specify the number of SERP pages to screenshot;
default value: 1"
}
},
"example": [
{
"task_id": "06211235-0696-0139-1000-36727fbd3c90",
"browser_screen_scale_factor": 0.5
}
]
},
"Response463397119C53_SerpScreenshotResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpScreenshotTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpScreenshotTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpScreenshotResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpScreenshotResultInfo": {
"type": "object",
"properties": {
"items_count": {
"type": [
"integer",
"null"
],
"description": "number of items in the results array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ScreenshotItem"
}
]
},
"description": "items array"
}
}
},
"Response463397119C53_SerpSeznamLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpSeznamLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_SerpSeznamLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpSeznamLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
only City location_type is supported for all countries except China (where Country is also supported);
don't match locations by location_code_parent because the results for Region and Country-level results for most countries are not supported by Baidu SERP API"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type"
}
}
},
"Response463397119C53_SerpSeznamOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:images, local_pack, organic, related_searches, top_stories, featured_snippet, video, shopping"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
},
"Response463397119C53_SerpSeznamOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpSeznamOrganicTaskGetRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskGetRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskGetRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTaskGetRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTaskGetRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:images, local_pack, organic, related_searches, top_stories, featured_snippet, video
however, this endpoint provides data for the organic type only
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Provider463397119C53_SerpSeznamOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:Czech"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:csn"
},
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields;
note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL;
in most cases, we wouldn’t recommend using this method."
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority
You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 10;
maximum value: 500;
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 10
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically
however, you can set a custom search engine domain in this field
example:
optional field"
},
"calculate_rectangles": {
"type": [
"boolean",
"null"
],
"description": "calculate pixel rankings for SERP elements in advanced results
optional field
pixel ranking refers to the distance between the result snippet and top left corner of the screen;
Visit Help Center to learn more>>
by default, the parameter is set to false
Note: if set to true, the charge per task will be multiplied by 2"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:regular, advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpSeznamOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpSeznamOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpYahooLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_SerpYahooLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:
`\"location_code\": 9041134`,
`\"location_name\": \"Vienna International Airport,Lower Austria,Austria\"`,
`\"location_code_parent\": 20044`
`\"location_name\": \"Lower Austria,Austria\"`"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
indicates the geographic classification of the location
example:
`\"location_type\": \"Country\"`, or `\"location_type\": \"State\"`"
}
}
},
"Provider463397119C53_SerpYahooOrganicLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8"
},
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:enn"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:au.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 6
max value: 200
Your account will be billed per each SERP;
Each Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;example.com* - returns results for the domain, including all its pages;*example.com* - returns results for the entire domain, including all its pages and subdomains;*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com; example.com/example-page - returns results for the exact URL;example.com/example-page* - returns results for all domain's URLs that start with the specified string"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
get the list of available parameters and additional details here"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_SerpYahooOrganicLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:featured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpYahooOrganicLiveHtmlRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8"
},
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:enn"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:au.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 10
max value: 200
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
get the list of available parameters and additional details here"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_SerpYahooOrganicLiveHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicLiveHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicLiveHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicLiveHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicLiveHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpYahooOrganicLiveRegularRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8"
},
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:enn"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:au.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 6
max value: 200
Your account will be billed per each SERP;
Each Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"target": {
"type": [
"string",
"null"
],
"description": "target domain, subdomain, or webpage to get results for
optional field
a domain or a subdomain should be specified without https:// and www.
note that the results of target-specific tasks will only include SERP elements that contain a url string;
you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;
examples:example.com - returns results for the website's home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;example.com* - returns results for the domain, including all its pages;*example.com* - returns results for the entire domain, including all its pages and subdomains;*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com; example.com/example-page - returns results for the exact URL;example.com/example-page* - returns results for all domain's URLs that start with the specified string"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
get the list of available parameters and additional details here"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
},
"Response463397119C53_SerpYahooOrganicLiveRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicLiveRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicLiveRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicLiveRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicLiveRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
You can use it to make sure that we provided exact results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:featured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview;
note that this array contains all types of search results found in the returned SERP;
however, this endpoint provides data for organic, paid, and featured_snippet types only;
to get all items (including SERP features and rich snippets) found in the returned SERP, please refer to the Yahoo Organiс Advanced SERP endpoint"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Response463397119C53_SerpYahooOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:featured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "additional items present in the element
if there are none, equals null"
}
}
},
"Response463397119C53_SerpYahooOrganicTaskGetHtmlResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskGetHtmlTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskGetHtmlTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskGetHtmlResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskGetHtmlResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_HtmlItemInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_SerpYahooOrganicTaskGetRegularResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskGetRegularTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskGetRegularTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTaskGetRegularResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTaskGetRegularResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"refinement_chips": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_RefinementChipsInfo"
}
],
"description": "search refinement chips
equals null"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results found in SERP
contains types of all search results (items) found in the returned SERP
possible item types:featured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview;
note that this array contains all types of search results found in the returned SERP;
however, this endpoint provides data for organic, paid, and featured_snippet types only;
to get all items (including SERP features and rich snippets) found in the returned SERP, please refer to the Yahoo Organiс Advanced SERP endpoint"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"pages_count": {
"type": [
"integer",
"null"
],
"description": "total pages retrieved
total number of retrieved SERPs in the result",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiElementItem"
}
]
},
"description": "items in SERP"
}
}
},
"Provider463397119C53_SerpYahooOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "direct URL of the search query
optional field
you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.
example:https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8"
},
"keyword": {
"type": "string",
"description": "keyword
required field
you can specify up to 700 characters in the keyword field
all %## will be decoded (plus character '+' will be decoded to a space character)
if you need to use the \"%\" character for your keyword, please specify it as \"%25\";
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages
example:enn"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
return results for a specific device type
can take the values:desktop, mobile
default value: desktop"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system
optional field
if you specify desktop in the device field, choose from the following values: windows, macos
default value: windows
if you specify mobile in the device field, choose from the following values: android, ios
default value: android"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain
optional field
we choose the relevant search engine domain automatically according to the location and language you specify
however, you can set a custom search engine domain in this field
example:au.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 6
max value: 700
Your account will be billed per each SERP;
Each Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;
The cost can be calculated on the Pricing page."
},
"max_crawl_pages": {
"type": [
"integer",
"null"
],
"description": "page crawl limit
optional field
number of search results pages to crawl
default value: 1
max value: 100
Note: the max_crawl_pages and depth parameters complement each other;
learn more at our help center"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query
optional field
get the list of available parameters and additional details here"
},
"stop_crawl_on_match": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Provider463397119C53_SerpApiStopCrawlOnMatchInfo"
}
]
},
"description": "array of targets to stop crawling\noptional field\nif specified, the response will contain SERP results up to and including the specified match_value;\nyou can specify up to 10 target values in this array\nexample:\n\"stop_crawl_on_match\":[{\"match_value\":\"dataforseo.com\",\"match_type\":\"with_subdomains\"}]\nlearn more about this parameter on our Help Center - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api\nYour account will be billed per each SERP crawled through the specified targets"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:regular, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
in this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYahooOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYahooOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Response463397119C53_SerpYoutubeLanguagesResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeLanguagesTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeLanguagesTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeLanguagesResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeLanguagesResultInfo": {
"type": "object",
"properties": {
"language_name": {
"type": [
"string",
"null"
],
"description": "language name"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code according to ISO 639-1"
}
}
},
"Response463397119C53_SerpYoutubeLocationsResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeLocationsTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeLocationsTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeLocationsResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeLocationsResultInfo": {
"type": "object",
"properties": {
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of the location"
},
"location_code_parent": {
"type": [
"integer",
"null"
],
"description": "the code of the superordinate location
example:
`\"location_code\": 9041134`,
`\"location_name\": \"Vienna International Airport,Lower Austria,Austria\"`,
`\"location_code_parent\": 20044`
`\"location_name\": \"Lower Austria,Austria\"`"
},
"country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location"
},
"location_type": {
"type": [
"string",
"null"
],
"description": "location type
indicates the geographic classification of the location
example:
`\"location_type\": \"Country\"`, or `\"location_type\": \"State\"`"
}
}
},
"Provider463397119C53_SerpYoutubeOrganicLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile"
},
"block_depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "audi"
}
]
},
"Response463397119C53_SerpYoutubeOrganicLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array the keyword is returned with decoded %## (plus character '+' will be decoded to a space character)"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP contains types of search results (items) found in SERP. possible item types: youtube_channel, youtube_video, youtube_video_paid, youtube_playlist"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": "total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiYoutubeOrganicElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_BaseSerpApiYoutubeOrganicElementItem": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP for the target domain
absolute position among all the elements in SERP"
},
"block_rank": {
"type": [
"integer",
"null"
],
"description": "block rank in SERP
position among all the blocks in SERP"
},
"block_name": {
"type": [
"string",
"null"
],
"description": "name of the block in SERP
example:
\"People also watched\"
"
},
"channel_id": {
"type": [
"string",
"null"
],
"description": "ID of the channel"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the channel"
}
},
"additionalProperties": false,
"discriminator": {
"propertyName": "type",
"mapping": {
"youtube_channel": "#/components/schemas/Response463397119C53_SerpApiYoutubeChannelElementItem",
"youtube_video": "#/components/schemas/Response463397119C53_SerpApiYoutubeVideoElementItem",
"youtube_video_paid": "#/components/schemas/Response463397119C53_SerpApiYoutubeVideoPaidElementItem",
"youtube_playlist": "#/components/schemas/Response463397119C53_SerpApiYoutubePlaylistElementItem"
}
}
},
"Response463397119C53_SerpApiYoutubeChannelElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiYoutubeOrganicElementItem"
}
]
},
{
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "name of the channel"
},
"logo": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the logo image is hosted"
},
"video_count": {
"type": [
"integer",
"null"
],
"description": "the number of videos counted on the channel",
"format": "int64"
},
"is_verified": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the channel has a \"verified\" label"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the channel"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "highlighted keywords in the description"
}
}
}
]
},
"Response463397119C53_SerpApiYoutubeVideoElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiYoutubeOrganicElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video"
},
"thumbnail_url": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the thumbnail is hosted"
},
"channel_name": {
"type": [
"string",
"null"
],
"description": "the name of the channel where the video is published"
},
"channel_url": {
"type": [
"string",
"null"
],
"description": "the URL of the channel where the video is published"
},
"channel_logo": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the logo image of the channel is hosted"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the channel"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "highlighted keywords in the description"
},
"badges": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "video badges
example:
New, CC, 4K
"
},
"is_live": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is a live broadcast"
},
"is_shorts": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is shorts"
},
"is_movie": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is a movie"
},
"views_count": {
"type": [
"integer",
"null"
],
"description": "number of views of the video",
"format": "int64"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "the date when the video is published"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result is published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2022-11-15 12:57:46 +00:00
"
},
"duration_time": {
"type": [
"string",
"null"
],
"description": "duration of the video"
},
"duration_time_seconds": {
"type": [
"integer",
"null"
],
"description": "duration of the video in seconds"
}
}
}
]
},
"Response463397119C53_SerpApiYoutubeVideoPaidElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiYoutubeOrganicElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video"
},
"thumbnail_url": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the thumbnail is hosted"
},
"channel_name": {
"type": [
"string",
"null"
],
"description": "the name of the channel where the video is published"
},
"channel_url": {
"type": [
"string",
"null"
],
"description": "the URL of the channel where the video is published"
},
"channel_logo": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the logo image of the channel is hosted"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the channel"
},
"highlighted": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "highlighted keywords in the description"
},
"badges": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "video badges
example:
New, CC, 4K
"
},
"is_live": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is a live broadcast"
},
"is_shorts": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is shorts"
},
"is_movie": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is a movie"
},
"views_count": {
"type": [
"integer",
"null"
],
"description": "number of views of the video",
"format": "int64"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "the date when the video is published"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result is published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2022-11-15 12:57:46 +00:00
"
},
"duration_time": {
"type": [
"string",
"null"
],
"description": "duration of the video"
},
"duration_time_seconds": {
"type": [
"integer",
"null"
],
"description": "duration of the video in seconds"
}
}
}
]
},
"Response463397119C53_SerpApiYoutubePlaylistElementItem": {
"type": "object",
"allOf": [
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiYoutubeOrganicElementItem"
}
]
},
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"playlist_id": {
"type": [
"string",
"null"
],
"description": "ID of the video"
},
"thumbnail_url": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the thumbnail is hosted"
},
"channel_name": {
"type": [
"string",
"null"
],
"description": "the name of the channel where the video is published"
},
"channel_url": {
"type": [
"string",
"null"
],
"description": "the URL of the channel where the video is published"
},
"channel_logo": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the logo image of the channel is hosted"
},
"videos_count": {
"type": [
"integer",
"null"
],
"description": "the number of videos in playlist",
"format": "int64"
},
"preview_videos": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_PreviewVideos"
}
]
},
"description": "information about preview videos
array of objects containing information about videos in the preview block of the playlist element"
}
}
}
]
},
"Response463397119C53_PreviewVideos": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the video"
},
"duration_time": {
"type": [
"string",
"null"
],
"description": "duration of the video"
},
"duration_time_seconds": {
"type": [
"integer",
"null"
],
"description": "duration of the video in seconds"
}
}
},
"Response463397119C53_SerpYoutubeOrganicTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "keyword received in a POST array
the keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item types:
youtube_channel, youtube_video, youtube_video_paid"
},
"se_results_count": {
"type": [
"integer",
"null"
],
"description": " total number of results in SERP",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseSerpApiYoutubeOrganicElementItem"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpYoutubeOrganicTaskPostRequestInfo": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name\nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority\noptional field\ncan take the following values:\n1 – normal execution priority (set by default)\n2 – high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page."
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task\noptional field\nwhen a task is completed we will notify you by GET request sent to the URL you have specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/pingscript?id=$id\nhttp://your-server.com/pingscript?id=$id&tag=$tag\nNote: special characters in pingback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "return URL for sending task results\noptional field\nonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/postbackscript?id=$id\nhttp://your-server.com/postbackscript?id=$id&tag=$tag\nNote: special characters in postback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
],
"description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible value:\nadvanced"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
},
"search_param": {
"type": [
"string",
"null"
],
"description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D"
},
"block_depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 700\nNote: your account will be billed per each SERP containing up to 20 blocks of results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "audi"
}
]
},
"Response463397119C53_SerpYoutubeOrganicTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of resultsin this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeOrganicTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeOrganicTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpYoutubeVideoCommentsLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video
required field
you can find video ID in the URL or 'youtube_video' item of YouTube Organic result
example:vQXvyV0zIP4"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations
example:2840n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages
example:enn"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type
optional field
only value: desktop"
},
"os": {
"type": [
"string",
"null"
]
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 20
max value: 200
Note: your account will be billed per each SERP containing up to 20 results;
thus, setting a depth above 20 may result in additional charges if the search engine returns more than 20 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"video_id": "vQXvyV0zIP4"
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item:youtube_comment"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"comments_count": {
"type": [
"integer",
"null"
],
"description": "number of comments on the video",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_YoutubeComment"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_YoutubeComment": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP for the target domain
absolute position among all the elements in SERP"
},
"author_name": {
"type": [
"string",
"null"
],
"description": "name of the author of the comment"
},
"author_thumbnail": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the author's channel logo is hosted"
},
"author_url": {
"type": [
"string",
"null"
],
"description": "URL of the author's channel"
},
"text": {
"type": [
"string",
"null"
],
"description": "text of the comment"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "displayed publication date"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result was published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2022-11-15 12:57:46 +00:00"
},
"likes_count": {
"type": [
"integer",
"null"
],
"description": "number of likes on the comment",
"format": "int64"
},
"reply_count": {
"type": [
"integer",
"null"
],
"description": "number of replies on the comment",
"format": "int64"
}
}
},
"Response463397119C53_SerpYoutubeVideoCommentsTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item:youtube_comment"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"comments_count": {
"type": [
"integer",
"null"
],
"description": "number of comments on the video",
"format": "int64"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_YoutubeComment"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpYoutubeVideoCommentsTaskPostRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video\nrequired field\nyou can find video ID in the URL or 'youtube_video' item of YouTube Organic result\nexample:\nvQXvyV0zIP4"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name\nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 20\nmax value: 700\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority\noptional field\ncan take the following values:\n1 – normal execution priority (set by default)\n2 – high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nonly value: desktop"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task\noptional field\nwhen a task is completed we will notify you by GET request sent to the URL you have specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/pingscript?id=$id\nhttp://your-server.com/pingscript?id=$id&tag=$tag\nNote: special characters in pingback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "return URL for sending task results\noptional field\nonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/postbackscript?id=$id\nhttp://your-server.com/postbackscript?id=$id&tag=$tag\nNote: special characters in postback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
],
"description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible value:\nadvanced"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"video_id": "vQXvyV0zIP4"
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of resultsin this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoCommentsTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoCommentsTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpYoutubeVideoInfoLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video\nrequired field\nyou can find video ID in the URL or 'youtube_video' item of YouTube Organic result\nexample:\nvQXvyV0zIP4"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nonly value: desktop"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"video_id": "vQXvyV0zIP4"
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received\nin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”\nexample:\n2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine\nif the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_video_info"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_YoutubeVideoInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_YoutubeVideoInfo": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP for the target domain
absolute position among all the elements in SERP"
},
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL of the video"
},
"thumbnail_url": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the thumbnail is hosted"
},
"channel_id": {
"type": [
"string",
"null"
],
"description": "the ID of the channel where the video is published"
},
"channel_name": {
"type": [
"string",
"null"
],
"description": "the name of the channel where the video is published"
},
"channel_url": {
"type": [
"string",
"null"
],
"description": "the URL of the channel where the video is published"
},
"channel_logo": {
"type": [
"string",
"null"
],
"description": "the URL of the page where the logo image of the channel is hosted"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the video"
},
"views_count": {
"type": [
"integer",
"null"
],
"description": "number of views of the video",
"format": "int64"
},
"likes_count": {
"type": [
"integer",
"null"
],
"description": "number of likes on the video",
"format": "int64"
},
"comments_count": {
"type": [
"integer",
"null"
],
"description": "number of comments on the video",
"format": "int64"
},
"channel_subscribers_count": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_ChannelSubscribersCount"
}
],
"description": "number of subscribers of the channel"
},
"publication_date": {
"type": [
"string",
"null"
],
"description": "the date when the video is published"
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "date and time when the result is published
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2022-11-15 12:57:46 +00:00"
},
"keywords": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "keywords relevant to the video
also known as 'YouTube tags'"
},
"category": {
"type": [
"string",
"null"
],
"description": "the category the video belongs to"
},
"is_live": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is on live"
},
"is_embeddable": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the video is embeddable"
},
"duration_time": {
"type": [
"string",
"null"
],
"description": "duration of the video"
},
"duration_time_seconds": {
"type": [
"integer",
"null"
],
"description": "duration of the video in seconds"
},
"subtitles": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_Subtitles"
}
]
},
"description": "array of elements describing properties of subtitles in the video"
},
"streaming_quality": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_StreamingQualityElement"
}
]
},
"description": "array of elements that contain information about all possible streaming qualities of the video"
}
}
},
"Response463397119C53_ChannelSubscribersCount": {
"type": "object",
"properties": {
"displayed_count": {
"type": [
"string",
"null"
],
"description": "displayed subscriber count
subscriber count as displayed on YouTube"
},
"count": {
"type": [
"integer",
"null"
],
"description": "subscriber count",
"format": "int64"
}
}
},
"Response463397119C53_Subtitles": {
"type": "object",
"properties": {
"language": {
"type": [
"string",
"null"
],
"description": "language of subtitles"
},
"is_translatable": {
"type": [
"boolean",
"null"
],
"description": "defines if subtitles are translatable"
},
"is_auto_generated": {
"type": [
"boolean",
"null"
],
"description": "defines if subtitles are auto generated"
}
}
},
"Response463397119C53_StreamingQualityElement": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"label": {
"type": [
"string",
"null"
],
"description": "label of the quality element"
},
"width": {
"type": [
"integer",
"null"
],
"description": "video width in pixels",
"format": "int64"
},
"height": {
"type": [
"integer",
"null"
],
"description": "video height in pixels"
},
"bitrate": {
"type": [
"integer",
"null"
],
"description": "bit rate of the video"
},
"mime_type": {
"type": [
"string",
"null"
],
"description": "media type of the video"
},
"fps": {
"type": [
"integer",
"null"
],
"description": "frame rate of the video"
}
}
},
"Response463397119C53_SerpYoutubeVideoInfoTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:
2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item:
youtube_video_info"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_YoutubeVideoInfo"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpYoutubeVideoInfoTaskPostRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video\nrequired field\nyou can find video ID in the URL or 'youtube_video' item of YouTube Organic result\nexample:\nvQXvyV0zIP4"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name\nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority\noptional field\ncan take the following values:\n1 – normal execution priority (set by default)\n2 – high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nonly value: desktop"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task\noptional field\nwhen a task is completed we will notify you by GET request sent to the URL you have specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/pingscript?id=$id\nhttp://your-server.com/pingscript?id=$id&tag=$tag\nNote: special characters in pingback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "return URL for sending task results\noptional field\nonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/postbackscript?id=$id\nhttp://your-server.com/postbackscript?id=$id&tag=$tag\nNote: special characters in postback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
],
"description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible value:\nadvanced"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"video_id": "vQXvyV0zIP4"
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of resultsin this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoInfoTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoInfoTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
},
"Provider463397119C53_SerpYoutubeVideoSubtitlesLiveAdvancedRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video\nrequired field\nyou can find video ID in the URL or 'youtube_video' item of YouTube Organic result\nexample:\nY8Wu4rSNJms"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nonly value: desktop"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
},
"subtitles_language": {
"type": [
"string",
"null"
],
"description": "language code of original text\nyou can get the language code from YouTube Video Info result"
},
"subtitles_translate_language": {
"type": [
"string",
"null"
],
"description": "language code of translated text\npossible values:\n\"az\", \"ay\", \"ak\", \"sq\", \"am\", \"en\", \"ar\", \"hy\", \"as\", \"af\", \"eu\", \"be\", \"bn\", \"my\", \"bg\", \"bs\", \"bho\", \"cy\", \"hu\", \"vi\", \"haw\", \"ht\", \"gl\", \"lg\", \"el\", \"ka\", \"gn\", \"gu\", \"gd\", \"da\", \"fy\", \"zu\", \"iw\", \"ig\", \"yi\", \"id\", \"ga\", \"is\", \"es\", \"it\", \"yo\", \"kk\", \"kn\", \"ca\", \"qu\", \"rw\", \"ky\", \"zh-Hant\", \"zh-Hans\", \"ko\", \"co\", \"xh\", \"ku\", \"km\", \"lo\", \"la\", \"lv\", \"ln\", \"lt\", \"lb\", \"mk\", \"mg\", \"ms\", \"ml\", \"dv\", \"mt\", \"mi\", \"mr\", \"mn\", \"und\", \"de\", \"ne\", \"nl\", \"no\", \"ny\", \"or\", \"om\", \"pa\", \"fa\", \"pl\", \"pt\", \"ps\", \"ro\", \"ru\", \"sm\", \"sa\", \"ceb\", \"nso\", \"sr\", \"si\", \"sd\", \"sk\", \"sl\", \"so\", \"sw\", \"su\", \"tg\", \"th\", \"ta\", \"tt\", \"te\", \"ti\", \"ts\", \"tr\", \"tk\", \"uz\", \"ug\", \"uk\", \"ur\", \"fil\", \"fi\", \"fr\", \"ha\", \"hi\", \"hmn\", \"hr\", \"cs\", \"sv\", \"sn\", \"ee\", \"eo\", \"et\", \"st\", \"jv\", \"ja\", \"kri\""
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"video_id": "Y8Wu4rSNJms"
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesLiveAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesLiveAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesLiveAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesLiveAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesLiveAdvancedResultInfo": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine resultsyou can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was receivedin the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engineif the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERPcontains types of search results (items) found in SERP.possible item:youtube_subtitles"
},
"unsupported_language": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the language is unsupported by the system"
},
"translate_language": {
"type": [
"string",
"null"
],
"description": "language code of translated text"
},
"origin_language": {
"type": [
"string",
"null"
],
"description": "language code of original text"
},
"category": {
"type": [
"string",
"null"
],
"description": "the category the video belongs toNote: this field is deprecated and always returns null"
},
"subtitles_count": {
"type": [
"integer",
"null"
],
"description": "number of subtitles in the video",
"format": "int64"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_YoutubeSubtitles"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Response463397119C53_YoutubeSubtitles": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "type of element"
},
"rank_group": {
"type": [
"integer",
"null"
],
"description": "group rank in SERP
position within a group of elements with identical type values
positions of elements with different type values are omitted from rank_group"
},
"rank_absolute": {
"type": [
"integer",
"null"
],
"description": " absolute rank in SERP for the target domain
absolute position among all the elements in SERP"
},
"text": {
"type": [
"string",
"null"
],
"description": "text translated in subtitles"
},
"start_time": {
"type": [
"number",
"null"
],
"description": "the second subtitled text starts"
},
"end_time": {
"type": [
"number",
"null"
],
"description": "the second subtitled text ends"
},
"duration_time": {
"type": [
"number",
"null"
],
"description": "duration of subtitles in seconds"
}
}
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTaskGetAdvancedResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesTaskGetAdvancedTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTaskGetAdvancedTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesTaskGetAdvancedResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTaskGetAdvancedResultInfo": {
"type": "object",
"properties": {
"video_id": {
"type": [
"string",
"null"
],
"description": "ID of the video received in a POST array"
},
"se_domain": {
"type": [
"string",
"null"
],
"description": "search engine domain in a POST array"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "location code in a POST array"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "language code in a POST array"
},
"check_url": {
"type": [
"string",
"null"
],
"description": "direct URL to search engine results
you can use it to make sure that we provided accurate results"
},
"datetime": {
"type": [
"string",
"null"
],
"description": "date and time when the result was received
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2019-11-15 12:57:46 +00:00"
},
"spell": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SpellInfo"
}
],
"description": "autocorrection of the search engine
if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection"
},
"item_types": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "types of search results in SERP
contains types of search results (items) found in SERP.
possible item:youtube_subtitles"
},
"unsupported_language": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the language is unsupported by the system"
},
"translate_language": {
"type": [
"string",
"null"
],
"description": "language code of translated text"
},
"origin_language": {
"type": [
"string",
"null"
],
"description": "language code of original text"
},
"category": {
"type": [
"string",
"null"
],
"description": "the category the video belongs to
Note: this field is deprecated and always returns null"
},
"subtitles_count": {
"type": [
"integer",
"null"
],
"description": "number of subtitles in the video",
"format": "int64"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the video"
},
"items_count": {
"type": [
"integer",
"null"
],
"description": "the number of results returned in the items array",
"format": "int64"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_YoutubeSubtitles"
}
]
},
"description": "elements of search results found in SERP"
}
}
},
"Provider463397119C53_SerpYoutubeVideoSubtitlesTaskPostRequestInfo": {
"type": "object",
"properties": {
"video_id": {
"type": "string",
"description": "ID of the video\nrequired field\nyou can find video ID in the URL or 'youtube_video' item of YouTube Organic result\nexample:\nY8Wu4rSNJms"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search engine location code\nrequired field if you don't specify location_name\nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority\noptional field\ncan take the following values:\n1 – normal execution priority (set by default)\n2 – high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page."
},
"device": {
"type": [
"string",
"null"
],
"description": "device type\noptional field\nonly value: desktop"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task\noptional field\nwhen a task is completed we will notify you by GET request sent to the URL you have specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/pingscript?id=$id\nhttp://your-server.com/pingscript?id=$id&tag=$tag\nNote: special characters in pingback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "return URL for sending task results\noptional field\nonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified\nyou can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.\nexample:\nhttp://your-server.com/postbackscript?id=$id\nhttp://your-server.com/postbackscript?id=$id&tag=$tag\nNote: special characters in postback_url will be urlencoded;\ni.a., the # character will be encoded into %23\nlearn more on our Help Center"
},
"postback_data": {
"type": [
"string",
"null"
],
"description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible value:\nadvanced"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish"
},
"os": {
"type": [
"string",
"null"
],
"description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response"
},
"subtitles_language": {
"type": [
"string",
"null"
],
"description": "language code of original text\nyou can get the language code from YouTube Video Info result"
},
"subtitles_translate_language": {
"type": [
"string",
"null"
],
"description": "language code of translated text\npossible values:\n\"az\", \"ay\", \"ak\", \"sq\", \"am\", \"en\", \"ar\", \"hy\", \"as\", \"af\", \"eu\", \"be\", \"bn\", \"my\", \"bg\", \"bs\", \"bho\", \"cy\", \"hu\", \"vi\", \"haw\", \"ht\", \"gl\", \"lg\", \"el\", \"ka\", \"gn\", \"gu\", \"gd\", \"da\", \"fy\", \"zu\", \"iw\", \"ig\", \"yi\", \"id\", \"ga\", \"is\", \"es\", \"it\", \"yo\", \"kk\", \"kn\", \"ca\", \"qu\", \"rw\", \"ky\", \"zh-Hant\", \"zh-Hans\", \"ko\", \"co\", \"xh\", \"ku\", \"km\", \"lo\", \"la\", \"lv\", \"ln\", \"lt\", \"lb\", \"mk\", \"mg\", \"ms\", \"ml\", \"dv\", \"mt\", \"mi\", \"mr\", \"mn\", \"und\", \"de\", \"ne\", \"nl\", \"no\", \"ny\", \"or\", \"om\", \"pa\", \"fa\", \"pl\", \"pt\", \"ps\", \"ro\", \"ru\", \"sm\", \"sa\", \"ceb\", \"nso\", \"sr\", \"si\", \"sd\", \"sk\", \"sl\", \"so\", \"sw\", \"su\", \"tg\", \"th\", \"ta\", \"tt\", \"te\", \"ti\", \"ts\", \"tr\", \"tk\", \"uz\", \"ug\", \"uk\", \"ur\", \"fil\", \"fi\", \"fr\", \"ha\", \"hi\", \"hmn\", \"hr\", \"cs\", \"sv\", \"sn\", \"ee\", \"eo\", \"et\", \"st\", \"jv\", \"ja\", \"kri\""
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"video_id": "Y8Wu4rSNJms"
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTaskPostResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesTaskPostTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTaskPostTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "array of resultsin this case, the value will be null"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTasksReadyResponseInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesTasksReadyTaskInfo"
}
]
},
"description": "array of tasks"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTasksReadyTaskInfo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response463397119C53_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_SerpYoutubeVideoSubtitlesTasksReadyResultInfo"
}
]
},
"description": "array of results"
}
}
}
]
},
"Response463397119C53_SerpYoutubeVideoSubtitlesTasksReadyResultInfo": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "task identifier of the completed task
unique task identifier in our system in the UUID format"
},
"se": {
"type": [
"string",
"null"
],
"description": "search engine specified when setting the task"
},
"se_type": {
"type": [
"string",
"null"
],
"description": "type of search engine
example: {{low_se_type_under}}"
},
"date_posted": {
"type": [
"string",
"null"
],
"description": "date when the task was posted (in the UTC format)"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier"
},
"endpoint_regular": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Regular task
if SERP Regular is not supported in the specified endpoint, the value will be null"
},
"endpoint_advanced": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP Advanced task
if SERP Advanced is not supported in the specified endpoint, the value will be null"
},
"endpoint_html": {
"type": [
"string",
"null"
],
"description": "URL for collecting the results of the SERP HTML task
if SERP HTML is not supported in the specified endpoint, the value will be null"
}
}
}
},
"responses": {},
"parameters": {},
"examples": {},
"requestBodies": {},
"headers": {},
"links": {},
"callbacks": {},
"pathItems": {}
},
"info": {
"description": "",
"title": "DataForSEO",
"version": "1",
"x-aisa-capabilities": {
"idempotency": "Idempotency-Key",
"max_price": "X-AISA-Max-Price-USD",
"quote": {
"header": "X-AISA-Cost-Mode",
"value": "quote"
}
},
"x-aisa-configured-paths": [
"/apis/v1/dataforseo/ai_optimization/ai_keyword_data/keywords_search_volume/live",
"/apis/v1/dataforseo/ai_optimization/ai_keyword_data/locations_and_languages",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/live",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/models",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/task_get/{id}",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/task_post",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/tasks_ready",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/live/advanced",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/live/html",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_get/advanced/{id}",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_get/html/{id}",
"/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_post",
"/apis/v1/dataforseo/ai_optimization/claude/llm_responses/live",
"/apis/v1/dataforseo/ai_optimization/claude/llm_responses/models",
"/apis/v1/dataforseo/ai_optimization/claude/llm_responses/task_get/{id}",
"/apis/v1/dataforseo/ai_optimization/claude/llm_responses/task_post",
"/apis/v1/dataforseo/ai_optimization/claude/llm_responses/tasks_ready",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/live",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/models",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/task_get/{id}",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/task_post",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/tasks_ready",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/languages",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/live/advanced",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/live/html",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/locations",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/task_get/advanced/{id}",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/task_get/html/{id}",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/task_post",
"/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/tasks_ready",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/aggregated_metrics/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/available_filters",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/cross_aggregated_metrics/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/historical/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/locations_and_languages",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/multi_target_metrics/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/search/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/search_mentions/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/target_metrics/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/target_metrics_lite/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/timeseries_delta/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/timeseries_new_lost/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_domains/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brand_categories/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brand_categories_lite/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brands/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brands_lite/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_domains/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_domains_lite/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_pages/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_pages_lite/live",
"/apis/v1/dataforseo/ai_optimization/llm_mentions/top_pages/live",
"/apis/v1/dataforseo/ai_optimization/perplexity/llm_responses/live",
"/apis/v1/dataforseo/ai_optimization/perplexity/llm_responses/models",
"/apis/v1/dataforseo/app_data/apple/app_info/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/apple/app_info/task_post",
"/apis/v1/dataforseo/app_data/apple/app_list/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/apple/app_list/task_post",
"/apis/v1/dataforseo/app_data/apple/app_listings/categories",
"/apis/v1/dataforseo/app_data/apple/app_listings/search/live",
"/apis/v1/dataforseo/app_data/apple/app_reviews/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/apple/app_reviews/task_post",
"/apis/v1/dataforseo/app_data/apple/app_searches/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/apple/app_searches/task_post",
"/apis/v1/dataforseo/app_data/apple/categories",
"/apis/v1/dataforseo/app_data/apple/languages",
"/apis/v1/dataforseo/app_data/apple/locations",
"/apis/v1/dataforseo/app_data/google/app_info/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/google/app_info/task_get/html/{id}",
"/apis/v1/dataforseo/app_data/google/app_info/task_post",
"/apis/v1/dataforseo/app_data/google/app_list/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/google/app_list/task_get/html/{id}",
"/apis/v1/dataforseo/app_data/google/app_list/task_post",
"/apis/v1/dataforseo/app_data/google/app_listings/categories",
"/apis/v1/dataforseo/app_data/google/app_listings/search/live",
"/apis/v1/dataforseo/app_data/google/app_reviews/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/google/app_reviews/task_get/html/{id}",
"/apis/v1/dataforseo/app_data/google/app_reviews/task_post",
"/apis/v1/dataforseo/app_data/google/app_searches/task_get/advanced/{id}",
"/apis/v1/dataforseo/app_data/google/app_searches/task_get/html/{id}",
"/apis/v1/dataforseo/app_data/google/app_searches/task_post",
"/apis/v1/dataforseo/app_data/google/categories",
"/apis/v1/dataforseo/app_data/google/languages",
"/apis/v1/dataforseo/app_data/google/locations",
"/apis/v1/dataforseo/backlinks/anchors/live",
"/apis/v1/dataforseo/backlinks/backlinks/live",
"/apis/v1/dataforseo/backlinks/bulk_backlinks/live",
"/apis/v1/dataforseo/backlinks/bulk_new_lost_backlinks/live",
"/apis/v1/dataforseo/backlinks/bulk_new_lost_referring_domains/live",
"/apis/v1/dataforseo/backlinks/bulk_pages_summary/live",
"/apis/v1/dataforseo/backlinks/bulk_ranks/live",
"/apis/v1/dataforseo/backlinks/bulk_referring_domains/live",
"/apis/v1/dataforseo/backlinks/bulk_spam_score/live",
"/apis/v1/dataforseo/backlinks/competitors/live",
"/apis/v1/dataforseo/backlinks/domain_intersection/live",
"/apis/v1/dataforseo/backlinks/domain_pages/live",
"/apis/v1/dataforseo/backlinks/domain_pages_summary/live",
"/apis/v1/dataforseo/backlinks/history/live",
"/apis/v1/dataforseo/backlinks/index",
"/apis/v1/dataforseo/backlinks/page_intersection/live",
"/apis/v1/dataforseo/backlinks/referring_domains/live",
"/apis/v1/dataforseo/backlinks/referring_networks/live",
"/apis/v1/dataforseo/backlinks/summary/live",
"/apis/v1/dataforseo/backlinks/timeseries_new_lost_summary/live",
"/apis/v1/dataforseo/backlinks/timeseries_summary/live",
"/apis/v1/dataforseo/business_data/business_listings/search/live",
"/apis/v1/dataforseo/business_data/google/extended_reviews/task_get/{id}",
"/apis/v1/dataforseo/business_data/google/extended_reviews/task_post",
"/apis/v1/dataforseo/business_data/google/extended_reviews/tasks_ready",
"/apis/v1/dataforseo/business_data/google/hotel_info/live/advanced",
"/apis/v1/dataforseo/business_data/google/hotel_info/live/html",
"/apis/v1/dataforseo/business_data/google/hotel_info/task_get/advanced/{id}",
"/apis/v1/dataforseo/business_data/google/hotel_info/task_get/html/{id}",
"/apis/v1/dataforseo/business_data/google/hotel_info/task_post",
"/apis/v1/dataforseo/business_data/google/hotel_info/tasks_ready",
"/apis/v1/dataforseo/business_data/google/hotel_searches/live",
"/apis/v1/dataforseo/business_data/google/hotel_searches/task_get/{id}",
"/apis/v1/dataforseo/business_data/google/hotel_searches/task_post",
"/apis/v1/dataforseo/business_data/google/hotel_searches/tasks_ready",
"/apis/v1/dataforseo/business_data/google/my_business_info/live",
"/apis/v1/dataforseo/business_data/google/my_business_info/task_get/{id}",
"/apis/v1/dataforseo/business_data/google/my_business_info/task_post",
"/apis/v1/dataforseo/business_data/google/my_business_info/tasks_ready",
"/apis/v1/dataforseo/business_data/google/my_business_updates/task_get/{id}",
"/apis/v1/dataforseo/business_data/google/my_business_updates/task_post",
"/apis/v1/dataforseo/business_data/google/my_business_updates/tasks_ready",
"/apis/v1/dataforseo/business_data/google/questions_and_answers/live",
"/apis/v1/dataforseo/business_data/google/questions_and_answers/task_get/{id}",
"/apis/v1/dataforseo/business_data/google/questions_and_answers/task_post",
"/apis/v1/dataforseo/business_data/google/questions_and_answers/tasks_ready",
"/apis/v1/dataforseo/business_data/google/reviews/task_get/{id}",
"/apis/v1/dataforseo/business_data/google/reviews/task_post",
"/apis/v1/dataforseo/business_data/google/reviews/tasks_ready",
"/apis/v1/dataforseo/business_data/social_media/pinterest/live",
"/apis/v1/dataforseo/business_data/social_media/reddit/live",
"/apis/v1/dataforseo/business_data/tripadvisor/reviews/task_get/{id}",
"/apis/v1/dataforseo/business_data/tripadvisor/reviews/task_post",
"/apis/v1/dataforseo/business_data/tripadvisor/reviews/tasks_ready",
"/apis/v1/dataforseo/business_data/tripadvisor/search/task_get/{id}",
"/apis/v1/dataforseo/business_data/tripadvisor/search/task_post",
"/apis/v1/dataforseo/business_data/tripadvisor/search/tasks_ready",
"/apis/v1/dataforseo/business_data/trustpilot/reviews/task_get/{id}",
"/apis/v1/dataforseo/business_data/trustpilot/reviews/task_post",
"/apis/v1/dataforseo/business_data/trustpilot/reviews/tasks_ready",
"/apis/v1/dataforseo/business_data/trustpilot/search/task_get/{id}",
"/apis/v1/dataforseo/business_data/trustpilot/search/task_post",
"/apis/v1/dataforseo/business_data/trustpilot/search/tasks_ready",
"/apis/v1/dataforseo/content_analysis/available_filters",
"/apis/v1/dataforseo/content_analysis/categories",
"/apis/v1/dataforseo/content_analysis/category_trends/live",
"/apis/v1/dataforseo/content_analysis/languages",
"/apis/v1/dataforseo/content_analysis/locations",
"/apis/v1/dataforseo/content_analysis/phrase_trends/live",
"/apis/v1/dataforseo/content_analysis/rating_distribution/live",
"/apis/v1/dataforseo/content_analysis/search/live",
"/apis/v1/dataforseo/content_analysis/sentiment_analysis/live",
"/apis/v1/dataforseo/content_analysis/summary/live",
"/apis/v1/dataforseo/dataforseo_labs/amazon/bulk_search_volume/live",
"/apis/v1/dataforseo/dataforseo_labs/amazon/product_competitors/live",
"/apis/v1/dataforseo/dataforseo_labs/amazon/product_keyword_intersections/live",
"/apis/v1/dataforseo/dataforseo_labs/amazon/product_rank_overview/live",
"/apis/v1/dataforseo/dataforseo_labs/amazon/ranked_keywords/live",
"/apis/v1/dataforseo/dataforseo_labs/amazon/related_keywords/live",
"/apis/v1/dataforseo/dataforseo_labs/apple/app_competitors/live",
"/apis/v1/dataforseo/dataforseo_labs/apple/app_intersection/live",
"/apis/v1/dataforseo/dataforseo_labs/apple/bulk_app_metrics/live",
"/apis/v1/dataforseo/dataforseo_labs/apple/keywords_for_app/live",
"/apis/v1/dataforseo/dataforseo_labs/available_filters",
"/apis/v1/dataforseo/dataforseo_labs/google/app_competitors/live",
"/apis/v1/dataforseo/dataforseo_labs/google/app_intersection/live",
"/apis/v1/dataforseo/dataforseo_labs/google/available_history",
"/apis/v1/dataforseo/dataforseo_labs/google/bulk_app_metrics/live",
"/apis/v1/dataforseo/dataforseo_labs/google/bulk_keyword_difficulty/live",
"/apis/v1/dataforseo/dataforseo_labs/google/bulk_traffic_estimation/live",
"/apis/v1/dataforseo/dataforseo_labs/google/categories_for_domain/live",
"/apis/v1/dataforseo/dataforseo_labs/google/categories_for_keywords/languages",
"/apis/v1/dataforseo/dataforseo_labs/google/categories_for_keywords/live",
"/apis/v1/dataforseo/dataforseo_labs/google/competitors_domain/live",
"/apis/v1/dataforseo/dataforseo_labs/google/domain_intersection/live",
"/apis/v1/dataforseo/dataforseo_labs/google/domain_metrics_by_categories/live",
"/apis/v1/dataforseo/dataforseo_labs/google/domain_rank_overview/live",
"/apis/v1/dataforseo/dataforseo_labs/google/historical_bulk_traffic_estimation/live",
"/apis/v1/dataforseo/dataforseo_labs/google/historical_keyword_data/live",
"/apis/v1/dataforseo/dataforseo_labs/google/historical_rank_overview/live",
"/apis/v1/dataforseo/dataforseo_labs/google/historical_search_volume/live",
"/apis/v1/dataforseo/dataforseo_labs/google/historical_serps/live",
"/apis/v1/dataforseo/dataforseo_labs/google/keyword_ideas/live",
"/apis/v1/dataforseo/dataforseo_labs/google/keyword_overview/live",
"/apis/v1/dataforseo/dataforseo_labs/google/keyword_suggestions/live",
"/apis/v1/dataforseo/dataforseo_labs/google/keywords_for_app/live",
"/apis/v1/dataforseo/dataforseo_labs/google/keywords_for_categories/live",
"/apis/v1/dataforseo/dataforseo_labs/google/keywords_for_site/live",
"/apis/v1/dataforseo/dataforseo_labs/google/page_intersection/live",
"/apis/v1/dataforseo/dataforseo_labs/google/ranked_keywords/live",
"/apis/v1/dataforseo/dataforseo_labs/google/related_keywords/live",
"/apis/v1/dataforseo/dataforseo_labs/google/relevant_pages/live",
"/apis/v1/dataforseo/dataforseo_labs/google/search_intent/live",
"/apis/v1/dataforseo/dataforseo_labs/google/serp_competitors/live",
"/apis/v1/dataforseo/dataforseo_labs/google/subdomains/live",
"/apis/v1/dataforseo/dataforseo_labs/google/top_searches/live",
"/apis/v1/dataforseo/dataforseo_labs/status",
"/apis/v1/dataforseo/domain_analytics/technologies/aggregation_technologies/live",
"/apis/v1/dataforseo/domain_analytics/technologies/available_filters",
"/apis/v1/dataforseo/domain_analytics/technologies/domain_technologies/live",
"/apis/v1/dataforseo/domain_analytics/technologies/domains_by_html_terms/live",
"/apis/v1/dataforseo/domain_analytics/technologies/domains_by_technology/live",
"/apis/v1/dataforseo/domain_analytics/technologies/languages",
"/apis/v1/dataforseo/domain_analytics/technologies/locations",
"/apis/v1/dataforseo/domain_analytics/technologies/technologies",
"/apis/v1/dataforseo/domain_analytics/technologies/technologies_summary/live",
"/apis/v1/dataforseo/domain_analytics/technologies/technology_stats/live",
"/apis/v1/dataforseo/domain_analytics/whois/available_filters",
"/apis/v1/dataforseo/domain_analytics/whois/overview/live",
"/apis/v1/dataforseo/keywords_data/bing/audience_estimation/industries",
"/apis/v1/dataforseo/keywords_data/bing/audience_estimation/job_functions",
"/apis/v1/dataforseo/keywords_data/bing/audience_estimation/live",
"/apis/v1/dataforseo/keywords_data/bing/audience_estimation/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/audience_estimation/task_post",
"/apis/v1/dataforseo/keywords_data/bing/audience_estimation/tasks_ready",
"/apis/v1/dataforseo/keywords_data/bing/keyword_performance/live",
"/apis/v1/dataforseo/keywords_data/bing/keyword_performance/locations_and_languages",
"/apis/v1/dataforseo/keywords_data/bing/keyword_performance/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/keyword_performance/task_post",
"/apis/v1/dataforseo/keywords_data/bing/keyword_suggestions_for_url/languages",
"/apis/v1/dataforseo/keywords_data/bing/keyword_suggestions_for_url/live",
"/apis/v1/dataforseo/keywords_data/bing/keyword_suggestions_for_url/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/keyword_suggestions_for_url/task_post",
"/apis/v1/dataforseo/keywords_data/bing/keyword_suggestions_for_url/tasks_ready",
"/apis/v1/dataforseo/keywords_data/bing/keywords_for_keywords/live",
"/apis/v1/dataforseo/keywords_data/bing/keywords_for_keywords/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/keywords_for_keywords/task_post",
"/apis/v1/dataforseo/keywords_data/bing/keywords_for_site/live",
"/apis/v1/dataforseo/keywords_data/bing/keywords_for_site/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/keywords_for_site/task_post",
"/apis/v1/dataforseo/keywords_data/bing/languages",
"/apis/v1/dataforseo/keywords_data/bing/locations",
"/apis/v1/dataforseo/keywords_data/bing/search_volume/live",
"/apis/v1/dataforseo/keywords_data/bing/search_volume/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/search_volume/task_post",
"/apis/v1/dataforseo/keywords_data/bing/search_volume_history/live",
"/apis/v1/dataforseo/keywords_data/bing/search_volume_history/locations_and_languages",
"/apis/v1/dataforseo/keywords_data/bing/search_volume_history/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/bing/search_volume_history/task_post",
"/apis/v1/dataforseo/keywords_data/clickstream_data/bulk_search_volume/live",
"/apis/v1/dataforseo/keywords_data/clickstream_data/dataforseo_search_volume/live",
"/apis/v1/dataforseo/keywords_data/clickstream_data/global_search_volume/live",
"/apis/v1/dataforseo/keywords_data/clickstream_data/locations_and_languages",
"/apis/v1/dataforseo/keywords_data/dataforseo_trends/demography/live",
"/apis/v1/dataforseo/keywords_data/dataforseo_trends/explore/live",
"/apis/v1/dataforseo/keywords_data/dataforseo_trends/locations",
"/apis/v1/dataforseo/keywords_data/dataforseo_trends/merged_data/live",
"/apis/v1/dataforseo/keywords_data/dataforseo_trends/subregion_interests/live",
"/apis/v1/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/live",
"/apis/v1/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post",
"/apis/v1/dataforseo/keywords_data/google_ads/keywords_for_keywords/live",
"/apis/v1/dataforseo/keywords_data/google_ads/keywords_for_keywords/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/google_ads/keywords_for_keywords/task_post",
"/apis/v1/dataforseo/keywords_data/google_ads/keywords_for_site/live",
"/apis/v1/dataforseo/keywords_data/google_ads/keywords_for_site/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/google_ads/keywords_for_site/task_post",
"/apis/v1/dataforseo/keywords_data/google_ads/search_volume/live",
"/apis/v1/dataforseo/keywords_data/google_ads/search_volume/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/google_ads/search_volume/task_post",
"/apis/v1/dataforseo/keywords_data/google_ads/status",
"/apis/v1/dataforseo/keywords_data/google_trends/categories",
"/apis/v1/dataforseo/keywords_data/google_trends/explore/live",
"/apis/v1/dataforseo/keywords_data/google_trends/explore/task_get/{id}",
"/apis/v1/dataforseo/keywords_data/google_trends/explore/task_post",
"/apis/v1/dataforseo/merchant/amazon/asin/live/advanced",
"/apis/v1/dataforseo/merchant/amazon/asin/live/html",
"/apis/v1/dataforseo/merchant/amazon/asin/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/amazon/asin/task_get/html/{id}",
"/apis/v1/dataforseo/merchant/amazon/asin/task_post",
"/apis/v1/dataforseo/merchant/amazon/asin/tasks_ready",
"/apis/v1/dataforseo/merchant/amazon/languages",
"/apis/v1/dataforseo/merchant/amazon/locations",
"/apis/v1/dataforseo/merchant/amazon/products/live/advanced",
"/apis/v1/dataforseo/merchant/amazon/products/live/html",
"/apis/v1/dataforseo/merchant/amazon/products/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/amazon/products/task_get/html/{id}",
"/apis/v1/dataforseo/merchant/amazon/products/task_post",
"/apis/v1/dataforseo/merchant/amazon/products/tasks_ready",
"/apis/v1/dataforseo/merchant/amazon/sellers/live/advanced",
"/apis/v1/dataforseo/merchant/amazon/sellers/live/html",
"/apis/v1/dataforseo/merchant/amazon/sellers/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/amazon/sellers/task_get/html/{id}",
"/apis/v1/dataforseo/merchant/amazon/sellers/task_post",
"/apis/v1/dataforseo/merchant/amazon/sellers/tasks_ready",
"/apis/v1/dataforseo/merchant/google/languages",
"/apis/v1/dataforseo/merchant/google/locations",
"/apis/v1/dataforseo/merchant/google/product_info/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/google/product_info/task_post",
"/apis/v1/dataforseo/merchant/google/product_info/tasks_ready",
"/apis/v1/dataforseo/merchant/google/products/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/google/products/task_get/html/{id}",
"/apis/v1/dataforseo/merchant/google/products/task_post",
"/apis/v1/dataforseo/merchant/google/products/tasks_ready",
"/apis/v1/dataforseo/merchant/google/reviews/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/google/reviews/task_post",
"/apis/v1/dataforseo/merchant/google/reviews/tasks_ready",
"/apis/v1/dataforseo/merchant/google/sellers/ad_url",
"/apis/v1/dataforseo/merchant/google/sellers/task_get/advanced/{id}",
"/apis/v1/dataforseo/merchant/google/sellers/task_post",
"/apis/v1/dataforseo/merchant/google/sellers/tasks_ready",
"/apis/v1/dataforseo/on_page/available_filters",
"/apis/v1/dataforseo/on_page/content_parsing",
"/apis/v1/dataforseo/on_page/content_parsing/live",
"/apis/v1/dataforseo/on_page/duplicate_content",
"/apis/v1/dataforseo/on_page/duplicate_tags",
"/apis/v1/dataforseo/on_page/force_stop",
"/apis/v1/dataforseo/on_page/instant_pages",
"/apis/v1/dataforseo/on_page/keyword_density",
"/apis/v1/dataforseo/on_page/lighthouse/audits",
"/apis/v1/dataforseo/on_page/lighthouse/languages",
"/apis/v1/dataforseo/on_page/lighthouse/live/json",
"/apis/v1/dataforseo/on_page/lighthouse/task_get/json/{id}",
"/apis/v1/dataforseo/on_page/lighthouse/task_post",
"/apis/v1/dataforseo/on_page/lighthouse/tasks_ready",
"/apis/v1/dataforseo/on_page/lighthouse/versions",
"/apis/v1/dataforseo/on_page/links",
"/apis/v1/dataforseo/on_page/microdata",
"/apis/v1/dataforseo/on_page/non_indexable",
"/apis/v1/dataforseo/on_page/page_screenshot",
"/apis/v1/dataforseo/on_page/pages",
"/apis/v1/dataforseo/on_page/pages_by_resource",
"/apis/v1/dataforseo/on_page/raw_html",
"/apis/v1/dataforseo/on_page/redirect_chains",
"/apis/v1/dataforseo/on_page/resources",
"/apis/v1/dataforseo/on_page/summary/{id}",
"/apis/v1/dataforseo/on_page/task_post",
"/apis/v1/dataforseo/on_page/tasks_ready",
"/apis/v1/dataforseo/on_page/uncrawlable_resources",
"/apis/v1/dataforseo/on_page/waterfall",
"/apis/v1/dataforseo/serp/ai_summary",
"/apis/v1/dataforseo/serp/baidu/languages",
"/apis/v1/dataforseo/serp/baidu/locations",
"/apis/v1/dataforseo/serp/baidu/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/baidu/organic/task_get/html/{id}",
"/apis/v1/dataforseo/serp/baidu/organic/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/baidu/organic/task_post",
"/apis/v1/dataforseo/serp/baidu/organic/tasks_ready",
"/apis/v1/dataforseo/serp/bing/languages",
"/apis/v1/dataforseo/serp/bing/locations",
"/apis/v1/dataforseo/serp/bing/organic/live/advanced",
"/apis/v1/dataforseo/serp/bing/organic/live/html",
"/apis/v1/dataforseo/serp/bing/organic/live/regular",
"/apis/v1/dataforseo/serp/bing/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/bing/organic/task_get/html/{id}",
"/apis/v1/dataforseo/serp/bing/organic/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/bing/organic/task_post",
"/apis/v1/dataforseo/serp/bing/organic/tasks_ready",
"/apis/v1/dataforseo/serp/google/ads_advertisers/live/advanced",
"/apis/v1/dataforseo/serp/google/ads_advertisers/locations",
"/apis/v1/dataforseo/serp/google/ads_advertisers/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/ads_advertisers/task_post",
"/apis/v1/dataforseo/serp/google/ads_advertisers/tasks_ready",
"/apis/v1/dataforseo/serp/google/ads_search/live/advanced",
"/apis/v1/dataforseo/serp/google/ads_search/locations",
"/apis/v1/dataforseo/serp/google/ads_search/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/ads_search/task_post",
"/apis/v1/dataforseo/serp/google/ads_search/tasks_ready",
"/apis/v1/dataforseo/serp/google/ai_mode/languages",
"/apis/v1/dataforseo/serp/google/ai_mode/live/advanced",
"/apis/v1/dataforseo/serp/google/ai_mode/live/html",
"/apis/v1/dataforseo/serp/google/ai_mode/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/ai_mode/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/ai_mode/task_post",
"/apis/v1/dataforseo/serp/google/ai_mode/tasks_ready",
"/apis/v1/dataforseo/serp/google/autocomplete/live/advanced",
"/apis/v1/dataforseo/serp/google/autocomplete/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/autocomplete/task_post",
"/apis/v1/dataforseo/serp/google/autocomplete/tasks_ready",
"/apis/v1/dataforseo/serp/google/dataset_info/live/advanced",
"/apis/v1/dataforseo/serp/google/dataset_info/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/dataset_info/task_post",
"/apis/v1/dataforseo/serp/google/dataset_info/tasks_ready",
"/apis/v1/dataforseo/serp/google/dataset_search/live/advanced",
"/apis/v1/dataforseo/serp/google/dataset_search/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/dataset_search/task_post",
"/apis/v1/dataforseo/serp/google/dataset_search/tasks_ready",
"/apis/v1/dataforseo/serp/google/events/live/advanced",
"/apis/v1/dataforseo/serp/google/events/locations",
"/apis/v1/dataforseo/serp/google/events/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/events/task_post",
"/apis/v1/dataforseo/serp/google/events/tasks_ready",
"/apis/v1/dataforseo/serp/google/finance_explore/live/advanced",
"/apis/v1/dataforseo/serp/google/finance_explore/live/html",
"/apis/v1/dataforseo/serp/google/finance_explore/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/finance_explore/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/finance_explore/task_post",
"/apis/v1/dataforseo/serp/google/finance_explore/tasks_ready",
"/apis/v1/dataforseo/serp/google/finance_markets/live/advanced",
"/apis/v1/dataforseo/serp/google/finance_markets/live/html",
"/apis/v1/dataforseo/serp/google/finance_markets/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/finance_markets/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/finance_markets/task_post",
"/apis/v1/dataforseo/serp/google/finance_markets/tasks_ready",
"/apis/v1/dataforseo/serp/google/finance_quote/live/advanced",
"/apis/v1/dataforseo/serp/google/finance_quote/live/html",
"/apis/v1/dataforseo/serp/google/finance_quote/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/finance_quote/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/finance_quote/task_post",
"/apis/v1/dataforseo/serp/google/finance_quote/tasks_ready",
"/apis/v1/dataforseo/serp/google/finance_ticker_search/live/advanced",
"/apis/v1/dataforseo/serp/google/finance_ticker_search/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/finance_ticker_search/task_post",
"/apis/v1/dataforseo/serp/google/finance_ticker_search/tasks_ready",
"/apis/v1/dataforseo/serp/google/images/live/advanced",
"/apis/v1/dataforseo/serp/google/images/live/html",
"/apis/v1/dataforseo/serp/google/images/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/images/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/images/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/google/images/task_post",
"/apis/v1/dataforseo/serp/google/images/tasks_ready",
"/apis/v1/dataforseo/serp/google/jobs/locations",
"/apis/v1/dataforseo/serp/google/jobs/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/jobs/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/jobs/task_post",
"/apis/v1/dataforseo/serp/google/jobs/tasks_ready",
"/apis/v1/dataforseo/serp/google/languages",
"/apis/v1/dataforseo/serp/google/local_finder/live/advanced",
"/apis/v1/dataforseo/serp/google/local_finder/live/html",
"/apis/v1/dataforseo/serp/google/local_finder/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/local_finder/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/local_finder/task_post",
"/apis/v1/dataforseo/serp/google/local_finder/tasks_ready",
"/apis/v1/dataforseo/serp/google/locations",
"/apis/v1/dataforseo/serp/google/maps/live/advanced",
"/apis/v1/dataforseo/serp/google/maps/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/maps/task_post",
"/apis/v1/dataforseo/serp/google/maps/tasks_ready",
"/apis/v1/dataforseo/serp/google/news/live/advanced",
"/apis/v1/dataforseo/serp/google/news/live/html",
"/apis/v1/dataforseo/serp/google/news/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/news/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/news/task_post",
"/apis/v1/dataforseo/serp/google/news/tasks_ready",
"/apis/v1/dataforseo/serp/google/organic/live/advanced",
"/apis/v1/dataforseo/serp/google/organic/live/html",
"/apis/v1/dataforseo/serp/google/organic/live/regular",
"/apis/v1/dataforseo/serp/google/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/organic/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/organic/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/google/organic/task_post",
"/apis/v1/dataforseo/serp/google/organic/tasks_ready",
"/apis/v1/dataforseo/serp/google/search_by_image/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/google/search_by_image/task_get/html/{id}",
"/apis/v1/dataforseo/serp/google/search_by_image/task_post",
"/apis/v1/dataforseo/serp/google/search_by_image/tasks_ready",
"/apis/v1/dataforseo/serp/naver/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/naver/organic/task_get/html/{id}",
"/apis/v1/dataforseo/serp/naver/organic/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/naver/organic/task_post",
"/apis/v1/dataforseo/serp/naver/organic/tasks_ready",
"/apis/v1/dataforseo/serp/screenshot",
"/apis/v1/dataforseo/serp/seznam/languages",
"/apis/v1/dataforseo/serp/seznam/locations",
"/apis/v1/dataforseo/serp/seznam/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/seznam/organic/task_get/html/{id}",
"/apis/v1/dataforseo/serp/seznam/organic/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/seznam/organic/task_post",
"/apis/v1/dataforseo/serp/seznam/organic/tasks_ready",
"/apis/v1/dataforseo/serp/yahoo/languages",
"/apis/v1/dataforseo/serp/yahoo/locations",
"/apis/v1/dataforseo/serp/yahoo/organic/live/advanced",
"/apis/v1/dataforseo/serp/yahoo/organic/live/html",
"/apis/v1/dataforseo/serp/yahoo/organic/live/regular",
"/apis/v1/dataforseo/serp/yahoo/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/yahoo/organic/task_get/html/{id}",
"/apis/v1/dataforseo/serp/yahoo/organic/task_get/regular/{id}",
"/apis/v1/dataforseo/serp/yahoo/organic/task_post",
"/apis/v1/dataforseo/serp/yahoo/organic/tasks_ready",
"/apis/v1/dataforseo/serp/youtube/languages",
"/apis/v1/dataforseo/serp/youtube/locations",
"/apis/v1/dataforseo/serp/youtube/organic/live/advanced",
"/apis/v1/dataforseo/serp/youtube/organic/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/youtube/organic/task_post",
"/apis/v1/dataforseo/serp/youtube/organic/tasks_ready",
"/apis/v1/dataforseo/serp/youtube/video_comments/live/advanced",
"/apis/v1/dataforseo/serp/youtube/video_comments/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/youtube/video_comments/task_post",
"/apis/v1/dataforseo/serp/youtube/video_comments/tasks_ready",
"/apis/v1/dataforseo/serp/youtube/video_info/live/advanced",
"/apis/v1/dataforseo/serp/youtube/video_info/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/youtube/video_info/task_post",
"/apis/v1/dataforseo/serp/youtube/video_info/tasks_ready",
"/apis/v1/dataforseo/serp/youtube/video_subtitles/live/advanced",
"/apis/v1/dataforseo/serp/youtube/video_subtitles/task_get/advanced/{id}",
"/apis/v1/dataforseo/serp/youtube/video_subtitles/task_post",
"/apis/v1/dataforseo/serp/youtube/video_subtitles/tasks_ready"
],
"x-aisa-document": {
"facts_hash": "6ab8fec17df1d5dcdff2e036dd1eb40587752b774ec040ab4eb0cc6946c3dd3c",
"generator_version": "3",
"protocol_version": "1",
"schema_version": "1",
"composer_version": "20",
"response_pending": [],
"document_hash": "sha256:247f0a53489bda2c81b4142a1275f7af13128904396e39f2485c6ba921e0d40a"
},
"x-aisa-plans": {
"builder": 1.0,
"display_plan": "payg",
"payg": 1.0,
"similarweb_payg": 1.0,
"team": 1.0,
"version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb"
},
"x-aisa-provider": "dataforseo",
"x-aisa-catalogs": {
"dataforseo": {
"title": "DataForSEO",
"description": "",
"x-aisa-document": {
"facts_hash": "6ab8fec17df1d5dcdff2e036dd1eb40587752b774ec040ab4eb0cc6946c3dd3c",
"generator_version": "3",
"protocol_version": "1",
"schema_version": "1"
},
"x-aisa-plans": {
"builder": 1.0,
"display_plan": "payg",
"payg": 1.0,
"similarweb_payg": 1.0,
"team": 1.0,
"version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb"
},
"x-aisa-capabilities": {
"idempotency": "Idempotency-Key",
"max_price": "X-AISA-Max-Price-USD",
"quote": {
"header": "X-AISA-Cost-Mode",
"value": "quote"
}
}
}
}
},
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"openapi": "3.1.0",
"security": [
{
"bearerAuth": []
}
],
"servers": [
{
"url": "https://api.aisa.one"
}
],
"paths": {
"/apis/v1/dataforseo/ai_optimization/ai_keyword_data/keywords_search_volume/live": {
"post": {
"description": "\nThis endpoint provides search volume data for your target keywords, reflecting their estimated usage in AI tools.\n\n\nUsage-based billing; Default request estimate: $0.011 USD (not a fixed price). Account-specific pricing and final settlement may differ.\n",
"operationId": "post_dataforseo_ai_keyword_volume_live",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response463397119C53_AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResponseInfo"
}
]
}
}
}
},
"default": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Error response; upstream passthrough responses may use provider formats"
}
},
"summary": "AI Keyword Data Keyword Search Volume",
"tags": [
"default"
],
"x-aisa-capabilities": {
"idempotency": "Idempotency-Key",
"max_price": "X-AISA-Max-Price-USD",
"quote": {
"header": "X-AISA-Cost-Mode",
"value": "quote"
},
"mpp": false,
"mpp_methods": [],
"x402": false
},
"x-aisa-category": "13",
"x-aisa-passthrough": true,
"x-aisa-pricing": {
"cost_contract": "response_usd",
"customer_multiplier": 1.0,
"customer_pricing": "provider_cost_multiplier",
"default_request_estimate_usd": 0.011,
"estimate_source": "profile_seed",
"evidence_source": "response_body"
},
"x-aisa-query-policy": {
"ignore_undeclared": false,
"request_wins": true
},
"x-aisa-revision": {
"customer_pricing_ref": "6155513a94fd",
"plan_policy_version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb",
"profile_ref": "8e606c70f96c"
},
"x-aisa-status": "enabled",
"x-aisa-upstream-path": "/v3/ai_optimization/ai_keyword_data/keywords_search_volume/live",
"x-aisa-validation": "provider",
"x-aisa-catalog-id": "dataforseo",
"x-aisa-runtime-operation": {
"operation_id": "post_dataforseo_ai_keyword_volume_live",
"method": "ANY",
"path": "/apis/v1/dataforseo/ai_optimization/ai_keyword_data/keywords_search_volume/live"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "keywords
required field
UTF-8 encoding
The maximum number of keywords you can specify: 1000;
The maximum number of characters in a single keyword: 250;
The keywords will be converted to lowercase format;keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of the location
required field if you don't specify location_code
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:United Kingdom"
},
"location_code": {
"type": "integer",
"description": "unique location identifier
required field if you don't specify location_name
Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of the language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:English"
},
"language_code": {
"type": "string",
"description": "language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languages
example:en"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"keywords": [
"iphone",
"seo"
]
}
]
}
]
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"keywords": [
"iphone",
"seo"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ce207d7e0aca8bc86b351e89d9fb5d2ff9e55a93467d065305c68354bd163855"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/ai_keyword_data/keywords_search_volume/live \\\n --header 'Authorization: Bearer
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;
minimum value for non-reasoning models: 16;
maximum value: 4096;
default value: 2048
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 2
default value: 0.94
Note: not supported in reasoning models"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: 0.92top_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search
optional field
when enabled, the AI model can access and cite current web information;
default value: false;
Note: refer to the Models endpoint for a list of models that support web_search;"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response
Note #2: not supported in reasoning models"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model will search the web from the country you specify;
Note: not supported in o3-mini, o1-pro, o1 models"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location
optional field
Note: not supported in o3-mini, o1-pro, o1 models"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"model_name": "gpt-4.1-mini",
"web_search": true,
"web_search_country_iso_code": "FR",
"web_search_city": "Paris",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"model_name": "gpt-4.1-mini",
"web_search": true,
"web_search_country_iso_code": "FR",
"web_search_city": "Paris",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:2afa7c8fa5672f7d791086678d6c3976eb46c3a745a671b5a9bada91269a20ee"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:c3a95889afca4a64a6ee5839d222bcca6fb6763ee7997cf29670e54d2e914180"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;
minimum value for non-reasoning models: 16;
maximum value: 4096;
default value: 2048"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 2
default value: 0.94
Note: not supported in reasoning models"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: 0.92top_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search
optional field
when enabled, the AI model can access and cite current web information;
default value: false;
Note: refer to the Models endpoint for a list of models that support web_search;"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response
Note #2: not supported in reasoning models"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model will search the web from the country you specify;
Note: not supported in o3-mini, o1-pro, o1 models"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location
optional field
Note: not supported in o3-mini, o1-pro, o1 models"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data array of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"model_name": "gpt-4.1-mini",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"model_name": "gpt-4.1-mini",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:4777b50691289d42da15afaad1f1929e500f70bb35f14f42255fa310e81df544"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_responses/task_post \\\n --header 'Authorization: Bearer
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:f6e09443dba3192fcb8f2f7b7de0b7047848af5642b4d0119da3851307d565e5"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/live/advanced \\\n --header 'Authorization: Bearer
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/{{low_se_name}}/{{low_se_type}}/languages
example:enn"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
to enable this parameter, force_web_search must also be enabled;
when enabled, the endpoint will return HTML data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5d0a0260f6c3429feb0ce3f861b26ce79c2f076cc1d57e7a25d430b73a28795f"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/live/html \\\n --header 'Authorization: Bearer
a universally unique identifier (UUID)
unique task identifier in our system
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ba7c56503da31c3fc612bd032f6ff1d1f29b34d17330cbc6318e18f25fd6634e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5366d0c61c43f16aecb1f392713eb3cc2715cdd4f2d3526f5a1a761448324322"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/chat_gpt/llm_scraper/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locations
example:2840"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languagesn"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
to enable this parameter, force_web_search must also be enabled;
when enabled, the HTML endpoint will return data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 1
default value: 0.7temperature cannot be used together with top_p in the same request"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: nulltop_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location used for searching the web
optional field
possible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location used for searching the web
optional field
"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1025
Note #2: if set to true, force_web_search must be set to false
Note #3: if set to true, the temperature and top_p cannot be used"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"model_name": "claude-opus-5",
"temperature": 0.3,
"web_search": true,
"web_search_country_iso_code": "FR",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"model_name": "claude-opus-5",
"temperature": 0.3,
"web_search": true,
"web_search_country_iso_code": "FR",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:93833e46e1d1bc00f7d89b5485e6c8d4f5fce6bfa30d400b1678e308cf96894e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/claude/llm_responses/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:a6149789d291a1d0c9235b06e5f826462a942cd70c909889b2f240092a5350bf"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/claude/llm_responses/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse;
lower values make output more focused;
minimum value: 0
maximum value: 1
default value: 0.7temperature cannot be used together with top_p in the same request"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection;
minimum value: 0
maximum value: 1
default value: nulltop_p cannot be used together with temperature in the same request"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"force_web_search": {
"type": [
"boolean",
"null"
],
"description": "force AI agent to use web search
optional field
to enable this parameter, web_search must also be enabled;
when enabled, the AI model is forced to access and cite current web information;
default value: false;
Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "ISO country code of the location used for searching the web
optional field
possible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'"
},
"web_search_city": {
"type": [
"string",
"null"
],
"description": "city name of the location used for searching the web
optional field
"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behaviour
optional field
defines the AI's role, tone, or specific behavior;
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1025
Note #2: if set to true, force_web_search must be set to false
Note #3: if set to true, the temperature and top_p cannot be used"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 2
default value: 1.3"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1024
Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"model_name": "gemini-2.5-flash",
"web_search": true,
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"model_name": "gemini-2.5-flash",
"web_search": true,
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d73a55152dc585b5badd7343d9796fae36cdbe892c1616d0105433cf83be50ee"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:558a61c600c721bbfbb6fa1f4bf7322f6940eab31e92fd31dd56a186793eba34"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_responses/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;
you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1;
maximum value: 4096;
default value: 2048;
Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit
Note #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 2
default value: 1.3"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9"
},
"web_search": {
"type": [
"boolean",
"null"
],
"description": "enable web search for current information
optional field
when enabled, the AI model can access and cite current web information;
Note: refer to the Models endpoint for a list of models that support web_search;
default value: false;
The cost of the parameter can be calculated on the Pricing page"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"use_reasoning": {
"type": [
"boolean",
"null"
],
"description": "enable reasoning for the AI model
optional field
when enabled, the model will perform reasoning before generating a response
refer to the Models endpoint for a list of models that support reasoning
default value: false
Note: if set to true, the minimum value for max_output_tokens is 1024
Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special character in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special character in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example: English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example: enn"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:2e031f3448575ba405e5345da64a9f997cd6c01b2d1a1d020baf68a510db812f"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/live/advanced \\\n --header 'Authorization: Bearer
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:enn"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
when enabled, the endpoint will return HTML data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ebe77207895e156f45641bed42ae86c31a02bc7b671c70b9def39175f5c98621"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/live/html \\\n --header 'Authorization: Bearer
a universally unique identifier (UUID)
unique task identifier in our system
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:8d22bff51e7a5c2d52fa013c64cf4ebfcacce0589433491f4d89a2feedc875fb"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:c9cc756a3a964e30a1651e14a97e057f01bb5a7b929bd4f65d18dfd216b0dfa0"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/gemini/llm_scraper/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
you can specify up to 2000 characters in the keyword field
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "location_name or location_codelocation_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format53.476225,-2.243572,200
required field if you don't specify language_code;
if you use this field, you don't need to specify language_code;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name;
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languages
example:en"
},
"expand_citations": {
"type": [
"boolean",
"null"
],
"description": "return expanded citation bar in HTML results
optional field
when enabled, the HTML endpoint will return data from the expanded citation bar;
default value: false"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the function you used for setting a task
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
minimal value 2025-08-01
date format \"yyyy-mm-dd\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "end date of the time range
optional field
Note value specified in date_from cannot exceed the value in date_to
date format \"yyyy-mm-dd\""
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "es",
"location_code": 2840,
"platform": "google",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
]
}
]
}
]
},
"example": [
{
"language_code": "es",
"location_code": 2840,
"platform": "google",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:9989c00f3850b72301b0ba098cf9a145c18f70422a7a8aa45d60104f0c3c863a"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/historical/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned objects
optional field100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000, use the search_after_token if you would like to offset more results"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domain
minimum value: 1
maximum value: 10
default value: 5"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "google",
"targets": [
{
"key": "chat_gpt",
"target": [
{
"keyword": "chat gpt"
}
]
},
{
"key": "claude",
"target": [
{
"keyword": "claude"
}
]
},
{
"key": "gemini",
"target": [
{
"keyword": "gemini"
}
]
},
{
"key": "perplexity",
"target": [
{
"keyword": "perplexity",
"search_filter": "include"
}
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 5
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "google",
"targets": [
{
"key": "chat_gpt",
"target": [
{
"keyword": "chat gpt"
}
]
},
{
"key": "claude",
"target": [
{
"keyword": "claude"
}
]
},
{
"key": "gemini",
"target": [
{
"keyword": "gemini"
}
]
},
{
"key": "perplexity",
"target": [
{
"keyword": "perplexity",
"search_filter": "include"
}
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 5
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:17af716e51add4ffc7644b8efa7abbfe8e6617c0a92a7367332ba3b2481daf99"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/multi_target_metrics/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000, use the search_after_token if you would like to offset more results"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 1000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned objects
optional field100
maximum value: 1000"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"filters": [
[
"ai_search_volume",
">",
1000
]
],
"order_by": [
"ai_search_volume,desc"
],
"offset": 0,
"limit": 3
}
]
}
]
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"filters": [
[
"ai_search_volume",
">",
1000
]
],
"order_by": [
"ai_search_volume,desc"
],
"offset": 0,
"limit": 3
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d9e3f5c96d1204c56b54cd9b978873e4ece0e63491f7975370885e5f8f03ee09"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/search_mentions/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domain
minimum value: 1
maximum value: 10
default value: 10"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 10
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 10
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:e6f55af7e179f06f5d833977075ac4c636a43efa609dc8402fbd3247d0bd210d"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/target_metrics/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of filter expressions applied before aggregation
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "es",
"location_code": 2840,
"platform": "google",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 6
}
]
}
]
},
"example": [
{
"language_code": "es",
"location_code": 2840,
"platform": "google",
"target": [
{
"domain": "en.wikipedia.org",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 6
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:77ce2254dcbff70d0b3aa811f5d8a3ada6e4dedb053a7f04ca75754cb4480f18"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/target_metrics_lite/live \\\n --header 'Authorization: Bearer
required field
minimal value: 2025-08-01
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": "string",
"description": "end date of the time range
required field
Note:the value specified in date_from cannot exceed the value in date_to
date format: \"yyyy-mm-dd\""
},
"group_range": {
"type": "string",
"description": "timeseries delta range
required field
possible values:day, week, month, year"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"date_from": "2025-08-01",
"date_to": "2025-12-01",
"group_range": "month"
}
]
}
]
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "bmw",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"date_from": "2025-08-01",
"date_to": "2025-12-01",
"group_range": "month"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:83d1d211e164e8fe2b935196251e18946d59dbf4f6580e0eb3672a8150b9cbfc"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/timeseries_delta/live \\\n --header 'Authorization: Bearer
required field
minimal value: 2025-08-01
date format: \"yyyy-mm-dd\""
},
"date_to": {
"type": "string",
"description": "end date of the time range
required field
Note:the value specified in date_from cannot exceed the value in date_to
date format: \"yyyy-mm-dd\""
},
"group_range": {
"type": "string",
"description": "timeseries range
required field
possible values:day, week, month, year"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "full name of search location
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "serp",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"date_from": "2025-08-01",
"date_to": "2025-12-01",
"group_range": "month"
}
]
}
]
},
"example": [
{
"language_name": "English",
"location_code": 2840,
"target": [
{
"domain": "dataforseo.com",
"search_filter": "exclude"
},
{
"keyword": "serp",
"search_scope": [
"answer"
]
}
],
"platform": "google",
"date_from": "2025-08-01",
"date_to": "2025-12-01",
"group_range": "month"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:527deaef9a55aaf032465016797e755a9f0ced4e16e4419458f2b0f1209c82df"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/timeseries_new_lost/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand_categories to include in the response
optional field
if specified, only the listed brand categories will be returned in the items array
example:\"include_brand_categories\": [\"business\"]"
},
"exclude_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand categories to exclude from the response
optional field
if specified, the listed brand categories will be omitted from the items array
example:\"exclude_brand_categories\": [\"business\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ae5b1f404d5d49cb7480d66ce06e895d6103cb4a663df6e9d7fa60791927895c"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brand_categories/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand categories to include in the response
optional field
if specified, only the listed brand categories will be returned in the items array
example:[\"company\",\"insurance\"]"
},
"exclude_brand_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brand categories to exclude from the response
optional field
if specified, the listed brand categories will be omitted from the items array
example:[\"company\",\"insurance\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:52c6cddcc5ac08464c4bf466b51eddda727dfda08f05d69cc05674d058679f24"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brand_categories_lite/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to include in the response
optional field
if specified, only the listed brands will be returned in the items array
example:\"include_brands\": [\"Audi\"]"
},
"exclude_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to exclude from the response
optional field
if specified, the listed brands will be omitted from the items array
example:\"exclude_brands\": [\"Audi\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:f1dcc46a8aa8bcc1f0d05a51ea73d190d6fada59f430767a851fb8447bb19e93"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brands/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: data specific to brand entities is available for chat_gpt only;
Note #2:chat_gpt data is available for the United States and English only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\", 1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to include in the response
optional field
if specified, only the listed brands will be returned in the items array
example:[\"BMW\",\"Audi\"]"
},
"exclude_brands": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of brands to exclude from the response
optional field
if specified, the listed brands will be omitted from the items array
example:[\"BMW\",\"Audi\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:e97675ddec5a2a298ba6146555f7da04b88dd389f51f3f8951fd98d6c56bab05"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_brands_lite/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources
Note:if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to include in the response
optional field
if specified, only the listed domains will be returned in the items array
example:\"include_domains\": [\"en.wikipedia.org\"]"
},
"exclude_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to exclude from the response
optional field
if specified, the listed domains will be omitted from the items array
example:\"exclude_domains\": [\"en.wikipedia.org\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:3f9f539614fb4e9659f598deb885d994bdc7b790125d1f4ecbd5045ad70121c4"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_domains/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en onlyn"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources;
Note: if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to include in the response
optional field
if specified, only the listed domains will be returned in the items array
example:[\"dataforseo.com\",\"seoinsider.com\"]"
},
"exclude_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of domains to exclude from the response
optional field
if specified, the listed domains will be omitted from the items array
example:[\"google.com\",\"bing.com\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:6a15b68d90b672d6068d344531fdf1e8b11307c7884885793f42630144b3647f"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_domains_lite/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources;
Note:if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of pages to include in the response
optional field
if specified, only the listed pages will be returned in the items array
example:\"include_pages\": [\"https://example.page/\"]"
},
"exclude_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of pages to exclude from the response
optional field
if specified, the listed pages will be omitted from the items array
example:\"exclude_pages\": [\"https://example.page/\"]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:85f200ccf888c1fc7d9d21828361adc55a17ea47239354509ca1a11d93336189"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_pages/live \\\n --header 'Authorization: Bearer
optional field
if you use this field, you don't need to specify location_code
if you don't specify this field, the location_code with 2840 value will be used by default;
you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for United States only"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "search location code
optional field
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: 2840
Note: chat_gpt data is available for 2840 only"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search language
optional field
if you use this field, you don't need to specify language_code;
if you don't specify this field, the language_code with en value will be used by default;
you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
Note: chat_gpt data is available for English only"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search language code
optional field
if you use this field, you don't need to specify language_name;
you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages
default value: en
Note: chat_gpt data is available for en only"
},
"platform": {
"type": [
"string",
"null"
],
"description": "target platform
optional field
possible values:chat_gpt, google
default value: google
Note: if the platform is not specified, the data is returned for both platforms
Note #2:chat_gpt data is available for the United States and English only"
},
"links_scope": {
"type": [
"string",
"null"
],
"description": "links source scope
optional field
this parameter specifies which links will be used to extract domains and aggregation data
possible values: sources, search_results
default value: sources; ;
Note: if you specify search_results, the data will be available for chat_gpt only"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
optional field
you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"ai_search_volume\",\">\",1000]
learn more about the initial dataset filters in this help center article."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of results in the items array
optional field
you can use this parameter to limit the number of data objects you receive in the items array
minimum value: 1
maximum value: 1000
default value: 100"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:sources_domain, search_results_domain, brand_entities_title, brand_entities_category
minimum value: 1
maximum value: 10
default value: 5"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"ai_search_volume,desc\"]
Note: you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned mentions data
optional field0
example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;
Note: the maximum value is 1000000"
},
"include_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of page URLs to include in the response
optional field
if specified, only the listed pages will be returned in the items array
example:
`[\"https://dataforseo.com/apis/ai-optimization-api/llm-mentions-api\", \"https://dataforseo.com/apis/ai-optimization-api\"]`"
},
"exclude_pages": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "array of page URLs to exclude from the response
optional field
if specified, the listed pages will be omitted from the items array
example:
`[\"https://dataforseo.com/apis/ai-optimization-api/llm-mentions-api\", \"https://dataforseo.com/apis/ai-optimization-api\"]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": [
"answer"
]
},
{
"keyword": "auto",
"search_scope": [
"question"
],
"match_type": "partial_match"
}
],
"links_scope": "sources",
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"limit": 3,
"internal_list_limit": 2
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:f12ae9e4633b02b4d22feece99e1b8c0b8ce97a0b95d9416db238f6495ea15ac"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/llm_mentions/top_mentioned_pages_lite/live \\\n --header 'Authorization: Bearer
required field
the question or task you want to send to the AI model;
you can specify up to 500 characters in the user_prompt field"
},
"model_name": {
"type": "string",
"description": "name of the AI model
required fieldmodel_nameconsists of the actual model name and version name;
if the basic model name is specified, its latest version will be set by default;
you can receive the list of available LLM models by making a separate request to the following endpoint: https://api.dataforseo.com/v3/ai_optimization/perplexity/llm_responses/models"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "maximum number of tokens in the AI response
optional field
minimum value: 1
maximum value: 4096;
default value: 2048;
Note: if the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit"
},
"temperature": {
"type": [
"number",
"null"
],
"description": "randomness of the AI response
optional field
higher values make output more diverse
lower values make output more focused
minimum value: 0
maximum value: 1.9
default value: 0.77"
},
"top_p": {
"type": [
"number",
"null"
],
"description": "diversity of the AI response
optional field
controls diversity of the response by limiting token selection
minimum value: 0
maximum value: 1
default value: 0.9"
},
"web_search_country_iso_code": {
"type": [
"string",
"null"
],
"description": "country code for web search localization
optional field
specify the country ISO code to get localized web search results
Note: available only for Perplexity Sonar models
example: US"
},
"system_message": {
"type": [
"string",
"null"
],
"description": "instructions for the AI behavior
optional field
defines the AI's role, tone, or specific behavior
you can specify up to 500 characters in the system_message field"
},
"message_chain": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"type": "object",
"properties": {
"role": {
"type": [
"string",
"null"
],
"description": "role of the user from whom the message originates"
},
"message": {
"type": [
"string",
"null"
],
"description": "message text"
}
}
}
]
},
"description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user → ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what’s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I’m doing well, thank you. How can I assist you today?\"}]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"web_search_country_iso_code": "FR",
"model_name": "sonar",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
]
},
"example": [
{
"system_message": "communicate as if we are in a business meeting",
"message_chain": [
{
"role": "user",
"message": "Hello, what’s up?"
},
{
"role": "ai",
"message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
}
],
"max_output_tokens": 200,
"temperature": 0.3,
"top_p": 0.5,
"web_search_country_iso_code": "FR",
"model_name": "sonar",
"user_prompt": "provide information on how relevant the amusement park business is in France now"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:752bf75a9f0dbf60ae1fbd1c68aa6693f57ab734c1671b8ad28b4cd16fa09593"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/ai_optimization/perplexity/llm_responses/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:84f70242266ee893bfaee7daf586efc66c0e6f8599a611bb05c6170741fb48fa"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_info/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL `https://apps.apple.com/us/app/id835599320`
the id is `835599320`"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/locations`
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/locations`
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/languages`
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to `https://api.dataforseo.com/v3/app_data/apple/languages`
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priority You will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
`http://your-server.com/postbackscript?id=$id`
`http://your-server.com/postbackscript?id=$id&tag=$tag`
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:
`http://your-server.com/pingscript?id=$id`
`http://your-server.com/pingscript?id=$id&tag=$tag`
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5595a20e71421287c600f0d2d099eea2600a6b0f81c4e507071df6a5fd172a22"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_list/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
optional field
the categories you specify are used to search for app listings;
you can get the full list of available app listing categories by this link
you can specify up to 10 categories"
},
"description": {
"type": [
"string",
"null"
],
"description": "keyword in the app's description
optional field
keywords that occur in the description of the app;
can contain up to 200 characters"
},
"title": {
"type": [
"string",
"null"
],
"description": "keyword in the app's title
optional field
keywords that occur in the title of the app;
can contain up to 200 characters"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rating.value\",\">\",3]https://api.dataforseo.com/v3/app_data/apple/app_listings/available_filtersn"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"item.rating.value,desc\"]
you should use a comma to separate several sorting rules
example:[\"item.rating.value,desc\",\"item.rating.value,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned apps
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"title": "vpn",
"description": "vpn",
"categories": [
"Utilities"
],
"order_by": [
"item.rating.value,desc"
],
"filters": [
[
"item.rating.value",
">",
4.5
]
],
"limit": 10
}
]
}
]
},
"example": [
{
"title": "vpn",
"description": "vpn",
"categories": [
"Utilities"
],
"order_by": [
"item.rating.value,desc"
],
"filters": [
[
"item.rating.value",
">",
4.5
]
],
"limit": 10
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:a234360cb93fe6ed47311805678a1ef1dba22353db135321e4f3454877304c38"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_listings/search/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:f3bd4e8d4e3c6f78556bc127d4e1e79abf1f445d4b9b4c532108770d233082dd"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_reviews/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
ID of the mobile application on App Store;
you can find the ID in the URL of every app listed on App Store;
example:
in the URL https://apps.apple.com/us/app/id835599320
the id is 835599320"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:enn"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 25, because our system processes 25 reviews in a row;
default value: 25;
maximum value: 500;
Setting depth above 25 may result in additional charges if the search engine returns more than 25 results;
The cost can be calculated on the Pricing page."
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:most_recent — sort by the most recent reviews;most_helpful — sort by the most relevant reviews;
default rule: most_helpful"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:2528969c9ff36c244d8cba18b108fdb605e3b950216991023df213b78127e918"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/apple/app_searches/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/apple/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if language_name is not specified
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/apple/languages
example:enn"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be returned from the App Store SERP;
we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row;
default value: 100
maximum value: 700
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:95570515767dc9bec33d72bed451045e47904bbc7e5f8854d3b509e8e06798d9"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_info/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ab7b8e15b53dd49d36027bb927a8febd742d1f43c7365509eb449828ae4011e4"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_info/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:
in the URL https://play.google.com/store/apps/details?id=org.telegram.messenger
the id is org.telegram.messenger"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if language_name is not specified
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"app_id": "org.telegram.messenger",
"location_code": 2840,
"language_code": "en"
}
]
}
]
},
"example": [
{
"app_id": "org.telegram.messenger",
"location_code": 2840,
"language_code": "en"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:06bdf84c5c297fde5517fe1cb9746f1257b5677e26708a1a87a20489a6c67077"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_info/task_post \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d76b910240fdc1f91444cab18e5d2ad13c85ef20b2a9711695cfef9b33afd5e2"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_list/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:15d181ed25e0e8add47e565bc54d035e544fa0b36da719b61b4dcc0686af2c73"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_list/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
app collection on Google Play from which apps will be collected;
you can specify the following values:featured, topselling_paid, topselling_free, topselling_new_free, topselling_new_paid, topgrossing, movers_shakers
Note: if featured is selected, the app_category parameter cannot be used"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if language_code is not specified
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if language_name is not specified
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of apps to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 100, because our system processes 100 results in a row;
default value: 100;
maximum value: 200;
Your account will be billed per each SERP containing up to 100 results;
Setting depth above 100 may result in additional charges if the search engine returns more than 100 results;
The cost can be calculated on the Pricing page."
},
"app_category": {
"type": [
"string",
"null"
],
"description": "application category on Google Play
optional field
you can filter the results by app category;
example:family;
you can receive the full list of available categories by making a separate request to https://api.dataforseo.com/v3/app_data/google/categories
Note: app_category cannot be used if app_collection parameter is set to featured"
},
"age_rating": {
"type": [
"string",
"null"
],
"description": "filter results by age rating
optional field
you can use this field to filter the results by age rating;
possible types of filtering:ages_up_to_5 — return apps approved for children up to 5 years old;ages_6_8 — return apps approved for children from 6 to 8 years old;ages_9_12 — return apps approved for children from 9 to 12 years old;
by default, the API returns apps for all ages;
Note: this filter works only in conjunction with the \"category\": \"family\" parameter"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"app_collection": "topselling_free",
"location_code": 2840,
"language_code": "en",
"depth": 100
}
]
}
]
},
"example": [
{
"app_collection": "topselling_free",
"location_code": 2840,
"language_code": "en",
"depth": 100
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:965c9df854bed1b6fca5206c08257f43dce4bf94a4d422a811eb77921391e085"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_list/task_post \\\n --header 'Authorization: Bearer
optional field
the categories you specify are used to search for app listings;
you can get the full list of available app listing categories by this link
you can specify up to 10 categories"
},
"description": {
"type": [
"string",
"null"
],
"description": "keyword in the app's description
optional field
keywords that occur in the description of the app;
can contain up to 200 characters"
},
"title": {
"type": [
"string",
"null"
],
"description": "keyword in the app's title
optional field
keywords that occur in the title of the app;
can contain up to 200 characters"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"item.rating.value\",\">\",3]https://api.dataforseo.com/v3/app_data/google/app_listings/available_filters"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"item.installs_count,asc\"]
you should use a comma to separate several sorting rules
example:[\"item.rating.value,desc\",\"item.installs_count,asc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned apps
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned apps
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead."
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"title": "vpn",
"description": "vpn",
"categories": [
"Tools"
],
"order_by": [
"item.installs_count,asc"
],
"filters": [
[
"item.rating.value",
">",
4.5
]
],
"limit": 10
}
]
}
]
},
"example": [
{
"title": "vpn",
"description": "vpn",
"categories": [
"Tools"
],
"order_by": [
"item.installs_count,asc"
],
"filters": [
[
"item.rating.value",
">",
4.5
]
],
"limit": 10
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5f3b5cd2be3e65542758480b95bf4b6dd40d875228cf9b40b3d9b7d4d2a0f059"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_listings/search/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b2504d86674634035ff33861ab1ac8d879fe2cd86be4499cc1b7e4aff85f5ee9"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_reviews/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b42b66a8d0ac81739b2234391ff73adb7dbfda83bd8adbd2647e30ff3965479f"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_reviews/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
ID of the mobile application on Google Play;
you can find the ID in the URL of every app listed on Google Play;
example:https://play.google.com/store/apps/details?id=org.telegram.messenger"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews to be returned in the API response;
we strongly recommend setting the parsing depth in the multiples of 150, because our system processes 150 reviews in a row;
default value: 150;
maximum value: 100000;
Your account will be billed per each SERP containing up to 150 results;
Setting depth above 150 may result in additional charges if the search engine returns more than 150 results;
The cost can be calculated on the Pricing page."
},
"rating": {
"type": [
"integer",
"null"
],
"description": "filter reviews by rating
optional field
you can use this field to filter the results;
possible types of filtering:5 — return reviews with five-star rating only;4 — return reviews with four-star rating only;3 — return reviews with three-star rating only;2 — return reviews with two-star rating only;1 — return reviews with one-star rating only;
by default, the API returns all reviews regardless of the number of stars"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:newest — sort by the most recent reviews;most_relevant — sort by the most relevant reviews;
default rule: most_relevant"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"app_id": "org.telegram.messenger",
"location_code": 2840,
"language_code": "en",
"depth": 150
}
]
}
]
},
"example": [
{
"app_id": "org.telegram.messenger",
"location_code": 2840,
"language_code": "en",
"depth": 150
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:affeac7e680b731e6152912dde33642b56cb020f49f44fedc600226adee15d5e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_reviews/task_post \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:303c5bd0e2b0570a950e70d5bb976d7d7d22e1fee0031c48c54979ead8beed83"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_searches/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:c3dd153afb7029ebb34db7ac5281c9ec6d2fd52019d0fddda28b5be1caf5bcf5"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_searches/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
if you use this field, you don't need to specify location_code
you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:West Los Angeles,California,United States"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
if you use this field, you don't need to specify location_name
you can receive the list of available locations of the search engine with their location_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/locations
example:9061121"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/app_data/google/languages
example:en"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results to be returned to be returned from the Google Play SERP;
we strongly recommend setting the parsing depth in the multiples of 30, because our system processes 30 results in a row;
default value: 30;
maximum value: 200;
Your account will be billed per each SERP containing up to 30 results;
Setting depth above 30 may result in additional charges if the search engine returns more than 30 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23"
},
"postback_data": {
"type": "string",
"description": "postback_url datatype
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23"
}
},
"example": [
{
"keyword": "vpn",
"location_code": 2840,
"language_code": "en",
"depth": 30
}
]
}
]
},
"example": [
{
"keyword": "vpn",
"location_code": 2840,
"language_code": "en",
"depth": 30
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:f84cea40988b5a0ec680bf79ea51fad81097f71e5ed035b54235524e9ae88ed2"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/app_data/google/app_searches/task_post \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned anchors
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned anchors
optional field
default value: 0
if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_links_types.anchors\",\">\",\"1\"][[\"broken_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"limit": 4,
"order_by": [
"backlinks,desc"
],
"filters": [
"anchor",
"like",
"%news%"
]
}
]
}
]
},
"example": [
{
"target": "forbes.com",
"limit": 4,
"order_by": [
"backlinks,desc"
],
"filters": [
"anchor",
"like",
"%news%"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5cc27067a4301d0fea95320dbccd9d6d4080813952c6c6db036375bd8c69c277"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/anchors/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns all backlinksone_per_domain - returns one backlink per domainone_per_anchor - returns one backlink per anchoras_is"
},
"custom_mode": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
},
"description": "detailed results grouping type
optional field
use this object to get a specific number of backlinks per field
if you use custom_mode, then mode will be ignored
example:\"custom_mode\": {\"field\": \"domain\", \"value\": 100}"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, regex, not_regex, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rank\",\">\",\"80\"][[\"page_from_rank\",\">\",\"55\"],
\"and\",
[\"dofollow\",\"=\",true]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"text_pre\",\"like\",\"%seo%\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"domain_from_rank,desc\",\"page_from_rank,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned backlinks
optional field0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks;
Note: the maximum value is 20,000, use the search_after_token if you would like to offset more results"
},
"search_after_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;
by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;
Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned backlinks
optional field100
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"mode": "as_is",
"filters": [
"dofollow",
"=",
true
],
"limit": 5
}
]
}
]
},
"example": [
{
"target": "forbes.com",
"mode": "as_is",
"filters": [
"dofollow",
"=",
true
],
"limit": 5
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:48176286770ddea8edf5db79a87efd9b113d634cb4a4ee8e0e33dd9016b6d45f"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/backlinks/live \\\n --header 'Authorization: Bearer
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
]
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:c36f8c946d194ecd1d7f2cc3baafbdfa4d9d14d9e303f82bc3a7b3540a304615"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_backlinks/live \\\n --header 'Authorization: Bearer
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without `https://` and `www.` the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost backlinks;
the backlinks that appeared in our index after the specified date will be considered as new;
the backlinks that weren't found after the specified date, but were present before, will be considered as lost;
e.g. if today is 2021-10-13, default date_from will be 2021-09-13.
minimum value equals today's date -(minus) one year;
e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13.\"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
],
"date_from": "2026-09-12 05:48:19"
}
]
}
]
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
],
"date_from": "2026-09-12 05:48:19"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:c2e6dd7cc0912eb7bf0ea8fb10edc32529395320a0759a38f480892bfeaa40ff"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_new_lost_backlinks/live \\\n --header 'Authorization: Bearer
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost referring domains;
the referring domains that appeared in our index after the specified date will be considered as new;
the referring domains that weren't found after the specified date, but were present before, will be considered as lost;
e.g. if today is 2021-10-13, default date_from will be 2021-09-13.
minimum value equals today's date -(minus) one year;
e.g. if today is 2021-10-13, minimum date_from will be 2020-10-13.\"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
],
"datetime_from": "2026-48-12"
}
]
}
]
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
],
"datetime_from": "2026-48-12"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5f01e55ffd572b55c413f20b12372bac94e3d9f0607887591d5dad8aca7f0059"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_new_lost_referring_domains/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
you can specify up to 1000 pages, domains, or subdomains in each request.
note that the URLs you set in a single request cannot belong to more than 100 different domains."
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"https://dataforseo.com/solutions",
"https://dataforseo.com/about-us"
]
}
]
}
]
},
"example": [
{
"targets": [
"https://dataforseo.com/solutions",
"https://dataforseo.com/about-us"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:a9c83b9873ac3ad1534d84007692a0a9fe0b95186a9be4fd70d14666b2d8fc84"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_pages_summary/live \\\n --header 'Authorization: Bearer rank for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
]
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:a1eacab8d4936c52e402935a291017b28afd4ebbec4502a8a1b7ef3d0f50ad1b"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_ranks/live \\\n --header 'Authorization: Bearer
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
]
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:4b7fb2c6e5d3c95b83f7df52552043154284679f694cc71c90ced3468d0551b0"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_referring_domains/live \\\n --header 'Authorization: Bearer rank for
required field
you can set up to 1000 domains, subdomains or webpages
the domain or subdomain should be specified without https:// and www.
the page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": [
\"forbes.com\",
\"cnn.com\",
\"bbc.com\",
\"yelp.com\",
\"https://www.apple.com/iphone/\",
\"https://ahrefs.com/blog/\",
\"ibm.com\",
\"https://variety.com/\",
\"https://stackoverflow.com/\",
\"www.trustpilot.com\"
]`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
]
},
"example": [
{
"targets": [
"forbes.com",
"cnn.com",
"bbc.com",
"yelp.com",
"https://www.apple.com/iphone/",
"https://ahrefs.com/blog/",
"ibm.com",
"https://variety.com/",
"https://stackoverflow.com/",
"www.trustpilot.com"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5d9e8cd1402bfc27d3bf3297626eb428123009f06d10b4fb3a294b182ab581a8"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/bulk_spam_score/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rank\",\">\",\"100\"][[\"target\",\"like\",\"%forbes%\"],
\"and\",
[[\"rank\",\">\",\"100\"],\"or\",[\"intersections\",\">\",\"5\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"intersections,desc\",\"rank,asc\"]"
},
"main_domain": {
"type": [
"boolean",
"null"
],
"description": "indicates if only main domain of the target will be included in the search
optional field
if set to true, only the main domain will be included in search;
default value: true"
},
"exclude_large_domains": {
"type": [
"boolean",
"null"
],
"description": "indicates whether large domain will appear in results
optional field
if set to true, the results from the large domain (google.com, amazon.com, etc.) will be omitted;
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"filters": [
"rank",
">",
100
],
"order_by": [
"rank,desc"
],
"limit": 5
}
]
}
]
},
"example": [
{
"target": "dataforseo.com",
"filters": [
"rank",
">",
100
],
"order_by": [
"rank,desc"
],
"limit": 5
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b242aac8837bf0f14a44acea9dc3f58232cb8fa2ed09eed6acb2bf408d827405"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/competitors/live \\\n --header 'Authorization: Bearer
required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": {
\"1\": \"http://planet.postgresql.org/\",
\"2\": \"http://gborg.postgresql.org/\"
}`"
},
"exclude_targets": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages you want to exclude
optional field
you can specify up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring domains that link to targets but don't link to exclude_targets
example:
`\"exclude_targets\": [
\"bbc.com\",
\"https://www.apple.com/iphone/*\",
\"https://dataforseo.com/apis/*\"]`"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"1.internal_links_count\",\">\",\"1\"][[\"2.referring_pages\",\">\",\"2\"],
\"and\",
[\"1.backlinks\",\">\",\"10\"]][[\"1.first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"2.target\",\"like\",\"%dataforseo.com%\"],\"or\",[\"1.referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the array of returned results
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned results
optional field
default value: 100
maximum value: 1000"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be omitted and you won't receive the same domain in the response;
default value: true"
},
"intersection_mode": {
"type": [
"string",
"null"
],
"description": "indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified domains
possible values: all, partialall - results are based on all backlinks;partial - results are based on the intersecting backlinks only;
default value: all"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": {
"1": "moz.com",
"2": "ahrefs.com"
},
"include_subdomains": false,
"exclude_targets": [
"semrush.com"
],
"limit": 5,
"order_by": [
"1.backlinks,desc"
],
"exclude_internal_backlinks": true
}
]
}
]
},
"example": [
{
"targets": {
"1": "moz.com",
"2": "ahrefs.com"
},
"include_subdomains": false,
"exclude_targets": [
"semrush.com"
],
"limit": 5,
"order_by": [
"1.backlinks,desc"
],
"exclude_internal_backlinks": true
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:4c106b3de61893598bf118f7759619ec49a7777a52edffcc6869320a24e0f02e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/domain_intersection/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
example:forbes.com"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned pages
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned pages
optional field
default value: 0
if you specify the 10 value, the first ten pages in the results array will be omitted and the data will be provided for the successive pages"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"meta.internal_links_count\",\">\",\"1\"][[\"meta.external_links_count\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_visited\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"title\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"page_summary.backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"page_summary.backlinks,desc\",\"page_summary.rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [\"dofollow\", \"=\", true]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"limit": 5,
"filters": [
[
"page_summary.backlinks",
">",
5
],
"and",
[
"page",
"like",
"%sites%"
]
]
}
]
}
]
},
"example": [
{
"target": "forbes.com",
"limit": 5,
"filters": [
[
"page_summary.backlinks",
">",
5
],
"and",
[
"page",
"like",
"%sites%"
]
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:9dbe25869b6aced45bda3aad98df766f1d5d374050c4fb4768b250576b42134e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/domain_pages/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned anchors
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned anchors
optional field
default value: 0
if you specify the 10 value, the first ten anchors in the results array will be omitted and the data will be provided for the successive anchors"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_links_types.anchors\",\">\",\"1\"][[\"broken_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"anchor\",\"like\",\"%seo%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target domain will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, backlinks from the subdomains of the target domain will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "forbes.com",
"limit": 4,
"order_by": [
"backlinks,desc"
]
}
]
}
]
},
"example": [
{
"target": "forbes.com",
"limit": 4,
"order_by": [
"backlinks,desc"
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:3f3726040626eb4ada6d5b41f51f44911ac990cb2c1a1c03138a8fc3343be95e"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/domain_pages_summary/live \\\n --header 'Authorization: Bearer
required field
a domain should be specified without https:// and www."
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
minimum value 2019-01-01
if you don't specify this field, the minimum value will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "cnn.com",
"date_from": "2020-01-01",
"date_to": "2021-01-01"
}
]
}
]
},
"example": [
{
"target": "cnn.com",
"date_from": "2020-01-01",
"date_to": "2021-01-01"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b60c64dfab309c1930a89412ea616fb1d619bd1b42f698cbb2f83002a114667c"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/history/live \\\n --header 'Authorization: Bearer
required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example:
`\"targets\": {
\"1\": \"http://planet.postgresql.org/\",
\"2\": \"http://gborg.postgresql.org/\"
}`"
},
"exclude_targets": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "domains, subdomains or webpages you want to exclude
optional field
you can set up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring pages that link to targets but don't link to exclude_targets
example:
`\"exclude_targets\": [
\"bbc.com\",
\"https://www.apple.com/iphone/*\",
\"https://dataforseo.com/apis/*\"]`"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"1.rank\",\">\",\"80\"][[\"2.page_from_rank\",\">\",\"55\"],
\"and\",
[\"1.original\",\"=\",\"true\"]][[\"1.first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"1.acnhor\",\"like\",\"%seo%\"],\"or\",[\"1.text_pre\",\"not_like\",\"%seo%\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"rank,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"domain_from_rank,desc\",\"page_from_rank,asc\"]"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of the returned backlinks
optional field0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned backlinks
optional field100
maximum value: 1000"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:attributesdomain_from_platform_type10
maximum value: 1000"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the targets will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the result
default value: true"
},
"intersection_mode": {
"type": [
"string",
"null"
],
"description": "indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified URLs
possible values: all, partialall - results are based on all backlinks;partial - results are based on the intersecting backlinks only;
default value: all"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"targets": {
"1": "football.com",
"2": "fifa.com"
},
"exclude_targets": [
"skysports.com"
],
"limit": 5,
"order_by": [
"1.rank,desc"
],
"filters": [
[
"2.domain_from_rank",
">",
400
],
"and",
[
"1.dofollow",
"=",
true
]
]
}
]
}
]
},
"example": [
{
"targets": {
"1": "football.com",
"2": "fifa.com"
},
"exclude_targets": [
"skysports.com"
],
"limit": 5,
"order_by": [
"1.rank,desc"
],
"filters": [
[
"2.domain_from_rank",
">",
400
],
"and",
[
"1.dofollow",
"=",
true
]
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:2cd915db726fd34fca36edddbe266753019d65701cd3a7397be0b260be112f00"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/page_intersection/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned domains
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned domains
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_pages\",\">\",\"1\"][[\"referring_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"domain\",\"like\",\"%dataforseo.com%\"],\"or\",[\"referring_domains\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [\"dofollow\", \"=\", true]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "backlinko.com",
"limit": 5,
"order_by": [
"rank,desc"
],
"exclude_internal_backlinks": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"filters": [
"backlinks",
">",
100
]
}
]
}
]
},
"example": [
{
"target": "backlinko.com",
"limit": 5,
"order_by": [
"rank,desc"
],
"exclude_internal_backlinks": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"filters": [
"backlinks",
">",
100
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:e55b64d63b3694ffa7ba81fe9040d625e7f10df65234a5650acd24bf052bcc67"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/referring_domains/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"network_address_type": {
"type": [
"string",
"null"
],
"description": "indicates the type of network to get data for
optional field
possible values: ip, subnet
default value: ip"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned networks
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned networks
optional field
default value: 0
if you specify the 10 value, the first ten domains in the results array will be omitted and the data will be provided for the successive pages"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"referring_pages\",\">\",\"1\"][[\"referring_pages\",\">\",\"2\"],
\"and\",
[\"backlinks\",\">\",\"10\"]][[\"first_seen\",\">\",\"2017-10-23 11:31:45 +00:00\"],
\"and\",
[[\"network_address\",\"like\",\"194.1.%\"],\"or\",[\"referring_ips\",\">\",\"10\"]]]
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting type
example:[\"backlinks,desc\"]
note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"backlinks,desc\",\"rank,asc\"]"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [[\"dofollow\", \"=\", true]]"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be ommited and you won't receive the same domain in the response;
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "backlinko.com",
"network_address_type": "subnet",
"limit": 5,
"order_by": [
"rank,desc"
],
"exclude_internal_backlinks": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"filters": [
"backlinks",
">",
100
]
}
]
}
]
},
"example": [
{
"target": "backlinko.com",
"network_address_type": "subnet",
"limit": 5,
"order_by": [
"rank,desc"
],
"exclude_internal_backlinks": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"filters": [
"backlinks",
">",
100
]
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:21b3f101ccd93e2c0266b9fc40a57119b4f43a8918c1660d582546f79d45a9a4"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/referring_networks/live \\\n --header 'Authorization: Bearer
required field
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"include_indirect_links": {
"type": [
"boolean",
"null"
],
"description": "indicates if indirect links to the target will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to the target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true"
},
"exclude_internal_backlinks": {
"type": [
"boolean",
"null"
],
"description": "indicates if internal backlinks from subdomains to the target will be excluded from the results
optional field
if set to true, the results will not include data on internal backlinks from subdomains of the same domain as target
if set to false, internal links will be included in the results
default value: true"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:referring_links_tldreferring_links_typesreferring_links_attributesreferring_links_platform_typesreferring_links_semantic_locations10
maximum value: 1000"
},
"backlinks_status_type": {
"type": [
"string",
"null"
],
"description": "set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your target;
possible values: all - all backlinks will be returned and counted;live - backlinks found during the last check will be returned and counted;lost - lost backlinks will be returned and counted;live"
},
"backlinks_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example:\"backlinks_filters\": [\"dofollow\", \"=\", true]"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "explodingtopics.com",
"internal_list_limit": 10,
"include_subdomains": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"backlinks_status_type": "all"
}
]
}
]
},
"example": [
{
"target": "explodingtopics.com",
"internal_list_limit": 10,
"include_subdomains": true,
"backlinks_filters": [
"dofollow",
"=",
true
],
"backlinks_status_type": "all"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:5f5cb4a27963fc9f496079cab669f298c5a3493e403a9b21dae683c23371c5e0"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/summary/live \\\n --header 'Authorization: Bearer
required field
a domain should be specified without https:// and www.
example:\"forbes.com\""
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for new and lost backlinks and referring domains;
the backlinks and referring domains that appeared in our index after the specified date will be considered as new;
the backlinks and referring domains that weren't found after the specified date, but were present before, will be considered as lost;2019-01-30
maximum value shouldn't exceed the date specified in the date_to
date format: \"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
minimum value shouldn't preceed the date specified in the date_from
maximum value: today's date
date format: \"yyyy-mm-dd\"
example:\"2021-01-15\""
},
"group_range": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month, yearday, we will return items corresponding to all dates between and including date_from and date_to;
for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year\"group_range\": \"month\",
\"date_from\": \"2022-03-23\",
\"date_to\": \"2022-05-13\"
we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31day/week/month/year, we will return 0"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"date_from": "2021-12-01",
"date_to": "2022-02-01",
"group_range": "month"
}
]
}
]
},
"example": [
{
"target": "dataforseo.com",
"date_from": "2021-12-01",
"date_to": "2022-02-01",
"group_range": "month"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:6f571440baf3d016b1ff7b5cee2e04db7a8c2f02bd8e4f6470943248888785f5"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/timeseries_new_lost_summary/live \\\n --header 'Authorization: Bearer
required field
a domain should be specified without https:// and www.
example:\"forbes.com\""
},
"date_from": {
"type": [
"string",
"null"
],
"description": "starting date of the time range
optional field
this field indicates the date which will be used as a threshold for summary data;2019-01-30
maximum value shouldn't exceed the date specified in the date_to
date format: \"yyyy-mm-dd\"
example:\"2021-01-01\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default
minimum value shouldn't preceed the date specified in the date_from
maximum value: today's date
date format: \"yyyy-mm-dd\"
example:\"2021-01-15\""
},
"group_range": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month, yearday, we will return items corresponding to all dates between and including date_from and date_to;
for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year\"group_range\": \"month\",
\"date_from\": \"2022-03-23\",
\"date_to\": \"2022-05-13\"
we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31day/week/month/year, we will return 0"
},
"include_subdomains": {
"type": [
"boolean",
"null"
],
"description": "indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true"
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank, domain_from_rank, and page_from_rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"target": "dataforseo.com",
"date_from": "2021-12-01",
"date_to": "2022-02-01",
"group_range": "month"
}
]
}
]
},
"example": [
{
"target": "dataforseo.com",
"date_from": "2021-12-01",
"date_to": "2022-02-01",
"group_range": "month"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:100ccdc12c3788e3d2a59f475586f5cd25d5b8b552dc7398e5249f101024362f"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/backlinks/timeseries_summary/live \\\n --header 'Authorization: Bearer
optional field
the categories you specify are used to search for business listings;
if you don't use this field, we will return business listings found in the specified location;
you can specify up to 10 categories"
},
"description": {
"type": [
"string",
"null"
],
"description": "description of the element in SERP
optional field
the description of the business entity for which the results are collected;
can contain up to 200 characters"
},
"title": {
"type": [
"string",
"null"
],
"description": "title of the element in SERP
optional field
the name of the business entity for which the results are collected;
can contain up to 200 characters"
},
"is_claimed": {
"type": [
"boolean",
"null"
],
"description": "indicates whether the business is verified by its owner on Google Maps
optional field"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS coordinates of a location
optional fieldlocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the value of \"radius\" is specified in kilometres (km)
the minimum value for \"radius\": 1
the maximum value for \"radius\": 100000
example:53.476225,-2.243572,200
learn more about how to set location parameters in this API on our Help Center"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"rating.value\",\">\",3]
you can receive the list of available filters_by making a separate request to https://api.dataforseo.com/v3/business_data/business_listings/available_filters
The full list of possible filters is available here.n"
},
"order_by": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:[\"rating.value,desc\"]note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:[\"rating.value,desc\",\"rating.votes_count,desc\"]"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned businesses
optional field
default value: 100
maximum value: 1000"
},
"offset": {
"type": [
"integer",
"null"
],
"description": "offset in the results array of returned businesses
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use the offset_token instead"
},
"offset_token": {
"type": [
"string",
"null"
],
"description": "token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task;offset_token values are unique for each subsequent task
Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"categories": [
"pizza_restaurant"
],
"description": "pizza",
"title": "pizza",
"is_claimed": true,
"location_coordinate": "53.476225,-2.243572,10",
"order_by": [
"rating.value,desc"
],
"filters": [
[
"rating.value",
">",
3
]
],
"limit": 3
}
]
}
]
},
"example": [
{
"categories": [
"pizza_restaurant"
],
"description": "pizza",
"title": "pizza",
"is_claimed": true,
"location_coordinate": "53.476225,-2.243572,10",
"order_by": [
"rating.value,desc"
],
"filters": [
[
"rating.value",
">",
3
]
],
"limit": 3
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:64bd80c9795d8bacf9fddd079e6df2d180bba29fa53a9ea359b92ab2e7567740"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/business_listings/search/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ed768dc13f6fcbe7605e3f53bbce2e5595147c8611e62407dcd07f704b556510"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/extended_reviews/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field if you don't specify cid or place_id
the keyword you specify should indicate the name of the local establishment;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation errorkeyword and keywords fields in DataForSEO APIs in this Help Center article
required field if you don't specify keyword or place_id
example:194604053573767737
learn more about the identifier in this help center article
required field if you don't specify keyword or cid
example:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the identifier in this help center article
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews in SERP
we strongly recommend setting the parsing depth in the multiples of twenty, because our systems processes twenty reviews in a row
default value: 20
maximum value: 1000
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels element of the response), or the Hotel Searches endpoint of Business Data API
example:ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude, longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
the value must not be earlier than today's date
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, two adults will be used by default
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:[13,8]"
},
"load_prices_by_dates": {
"type": [
"boolean",
"null"
],
"description": "load hotel stay prices by dates
optional field
if you specify this parameter with true, the response will include the prices_by_dates array with hotel stay prices divided by dates
if you use this parameter, you will be charged double the base price for a request"
},
"prices_start_date": {
"type": [
"string",
"null"
],
"description": "start date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, the start date is set to check_in date
date format: yyyy-mm-dd
example:2025-05-20"
},
"prices_end_date": {
"type": [
"string",
"null"
],
"description": "end date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, you will get prices by date for the month
date format: yyyy-mm-dd
example:2025-05-21"
},
"prices_date_range": {
"type": [
"string",
"null"
],
"description": "predefined period for retrieving daily price data
optional field
to use this parameter, you must specify load_prices_by_dates with true
if the prices_start_date is not specified, the start date is set to check_in date
possible values: month, three_months, six_months, year
default value: month"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "CgoI-KWyzenM_MV3EAE"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "CgoI-KWyzenM_MV3EAE"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:572495e71e72224576e36da282767b929e6ae8c26d2d779264eb0025a154df84"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_info/live/advanced \\\n --header 'Authorization: Bearer
required field
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels element of the response), or the Hotel Searches endpoint of Business Data API
example:ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, two adults will be used by default
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:[13,8]"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data array of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"hotel_identifier": "ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:4de629b6ee4f83349ed66b9059eef3a7235cfa182000fdfb162a3934ee7a7cf3"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_info/live/html \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d175ab3f3270fcc6f0684923395efb94531bf87424073324e9abd80468d6cb49"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_info/task_get/advanced/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 7 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:aee2a05021cdbc60f5d56211a6548686fd16cd4d15548f1e2ef60ec592b7ef77"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_info/task_get/html/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field if you don't specify keyword
if you use this field, you don't need to specify keyword
unique identifier of a hotel entity in Google search;
you can obtain the value by making a request to Advanced Google SERP API (enclosed in the hotels_pack element of the response), or the Hotel Searches endpoint of Business Data API
example:ChYIq6SB--i6p6cpGgovbS8wN2s5ODZfEAE"
},
"keyword": {
"type": "string",
"description": "keyword
required field if you don't specify hotel_identifier
if you use this field, you don't need to specify hotel_identifier
the keyword you specify should indicate the name of the hotel entity
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
the value must not be earlier than today's date
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, two adults will be used by default
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;[14]
set the following value if you want to include one 13-years-old child and one 8-years-old child:[13,8]"
},
"load_prices_by_dates": {
"type": [
"boolean",
"null"
],
"description": "load hotel stay prices by dates
optional field
if you specify this parameter with true, the response will include the prices_by_dates array with hotel stay prices divided by dates
if you use this parameter, you will be charged double the base price for a request"
},
"prices_start_date": {
"type": [
"string",
"null"
],
"description": "start date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, the start date is set to check_in date
date format: yyyy-mm-dd
example:2025-05-20"
},
"prices_end_date": {
"type": [
"string",
"null"
],
"description": "end date to load prices by dates
optional field
to use this parameter, you must specify load_prices_by_dates with true
if this parameter is not specified, you will get prices by date for the month
date format: yyyy-mm-dd
example:2025-05-21"
},
"prices_date_range": {
"type": [
"string",
"null"
],
"description": "predefined period for retrieving daily price data
optional field
to use this parameter, you must specify load_prices_by_dates with true
if the prices_start_date is not specified, the start date is set to check_in date
possible values: month, three_months, six_months, year
default value: month"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255;
you can use this parameter to identify the task and match it with the result;
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified;
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request;
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field if you specify postback_url
corresponds to the datatype that will be sent to your server
possible values:advanced, html"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "notification URL of a completed task
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified;
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable;
we will set the necessary values before sending the request;
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
the keyword you specify is used to search for the list of hotels;
if you don't use this field, we will return the list of hotels found in a specified location;
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
Note: in order to obtain accurate search results, the location name is appended to the keyword automaticallykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom
Note: in order to obtain accurate search results, the location_name you specify will be automatically appended to the keyword"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement
example:53.476225,-2.243572n"
},
"search_this_area": {
"type": [
"boolean",
"null"
],
"description": "show hotels from the displayed area
optional field
can take the values: true, false
default value: true
if set to false the search_this_area mode will be turned off
Note: if the search_this_area mode is turned off, the location_name won't be appended to the keyword during search
learn more about this parameter on our Help Center"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in Google Hotels
default value: 18 organic results
max value: 140
Note: your account will be billed per each 18 organic results regardless of paid listings in the response;
thus, setting a depth above 18 may result in additional charges if Google Hotels return more than 18 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot precede the today's date"
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, the default value of 2 will be applied;
note that you can specify up to 6 persons including both adults and children
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;
age of child can be from 0 to 17;
note that you can specify up to 6 persons including both adults and children
set the following value if you want to include one 14-year-old child:[14]
set the following value if you want to include one 13-year-old child and one 8-year-old child:[13,8]"
},
"stars": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel stars
optional field
set this field to [5] if you want to get the list of 5-star hotels only
example:[3,4,5]"
},
"min_rating": {
"type": [
"number",
"null"
],
"description": "minimum rating
optional field
you can use this field to specify guest rating higher than a certain value
example:2.5"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:relevance – sort by most relevantlowest_price – sort by the lowest pricehighest_rating – sort by highest ratingmost_reviewed – sort by most reviewed
default value: relevance"
},
"min_price": {
"type": [
"integer",
"null"
],
"description": "minimum price per night
optional field
the currency of this value depends on the currency field
example:100"
},
"max_price": {
"type": [
"integer",
"null"
],
"description": "maximum price per night
optional field
the currency of this value depends on the currency field
example:600"
},
"free_cancellation": {
"type": [
"boolean",
"null"
],
"description": "hotels with a free cancellation
optional field
set this field to true if you want to get the list of hotels with free cancellation of reservations
default value: false"
},
"is_vacation_rentals": {
"type": [
"boolean",
"null"
],
"description": "search for vacation rentals
optional field
set this field to true if you want to get the list of vacation rentals instead of hotels
default value: false"
},
"amenities": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel amenities
optional field
you can use this field to specify different hotel amenities
example: [
\"free_parking\",
\"pets_allowed\"
]
possible values:
`\"air_conditioning\",
\"all_inclusive_available\",
\"bar\",
\"free_breakfast\",
\"fitness_center\",
\"kid_friendly\",
\"free_parking\",
\"pets_allowed\",
\"pool\",
\"restaurant\",
\"room_service\",
\"spa\",
\"free_wifi\",
\"parking\",
\"indoor_pool\",
\"outdoor_pool\",
\"wheelchair_accessible\",
\"beach_access\"`"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "cheap hotel",
"check_in": "2023-06-01",
"check_out": "2023-06-30",
"currency": "USD",
"adults": 2,
"children": [
"14"
],
"sort_by": "highest_rating",
"priority": 2,
"tag": "example"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "cheap hotel",
"check_in": "2023-06-01",
"check_out": "2023-06-30",
"currency": "USD",
"adults": 2,
"children": [
"14"
],
"sort_by": "highest_rating",
"priority": 2,
"tag": "example"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:bc8badf2dba9abfedfe06309bcec5bf69486612283761678a20b245459663791"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_searches/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b8c16249ad5d7b4cab2f7fefe5302feb56d92483a5daf21306e047d67875b169"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/hotel_searches/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
optional field
the keyword you specify is used to search for the list of hotels;
if you don't use this field, we will return the list of hotels found in a specified location;
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
Note: in order to obtain accurate search results, the location name is appended to the keyword automaticallykeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom
Note: in order to obtain accurate search results, the location_name you specify will be automatically appended to the keyword"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
Note: if the coordinates are used to set a location, the search will occur in the nearest settlement;
example:53.476225,-2.243572"
},
"search_this_area": {
"type": [
"boolean",
"null"
],
"description": "show hotels from the displayed area
optional field
can take the values: true, false
default value: true
if set to false the search_this_area mode will be turned off
Note: if the search_this_area mode is turned off, the location_name won't be appended to the keyword during search
learn more about this parameter on our Help Center"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in Google Hotels
default value: 18 organic results
max value: 140
Note: your account will be billed per each 18 organic results regardless of paid listings in the response;
thus, setting a depth above 18 may result in additional charges if Google Hotels return more than 18 results;
if the specified depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance"
},
"check_in": {
"type": [
"string",
"null"
],
"description": "check-in date
optional field
if you don't specify this field, tomorrow's date will be used by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot precede the today's date"
},
"check_out": {
"type": [
"string",
"null"
],
"description": "check-out date
optional field
if you don't specify this field, our system will apply the date of two days from now by default;
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\"
Note: the value cannot be less than or equal to check_in;
the range between check_in and check_out values cannot exceed 30 days"
},
"currency": {
"type": [
"string",
"null"
],
"description": "currency
optional field
example:\"USD\""
},
"adults": {
"type": [
"integer",
"null"
],
"description": "number of adults
optional field
if you don't specify this field, the default value of 2 will be applied;
note that you can specify up to 6 persons including both adults and children
example:1"
},
"children": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "number and age of children
optional field
if you don't specify this field, no children will be included in the search;
age of child can be from 0 to 17;
note that you can specify up to 6 persons including both adults and children
set the following value if you want to include one 14-year-old child:[14]
set the following value if you want to include one 13-year-old child and one 8-year-old child:[13,8]"
},
"stars": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel stars
optional field
set this field to [5] if you want to get the list of 5-star hotels only
example:[3,4,5]"
},
"min_rating": {
"type": [
"number",
"null"
],
"description": "minimum rating
optional field
you can use this field to specify guest rating higher than a certain value
example:2.5"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:relevance – sort by most relevantlowest_price – sort by the lowest pricehighest_rating – sort by highest ratingmost_reviewed – sort by most reviewed
default value: relevance"
},
"min_price": {
"type": [
"integer",
"null"
],
"description": "minimum price per night
optional field
the currency of this value depends on the currency field
example:100"
},
"max_price": {
"type": [
"integer",
"null"
],
"description": "maximum price per night
optional field
the currency of this value depends on the currency field
example:600"
},
"free_cancellation": {
"type": [
"boolean",
"null"
],
"description": "hotels with a free cancellation
optional field
set this field to true if you want to get the list of hotels with free cancellation of reservations
default value: false"
},
"is_vacation_rentals": {
"type": [
"boolean",
"null"
],
"description": "search for vacation rentals
optional field
set this field to true if you want to get the list of vacation rentals instead of hotels
default value: false"
},
"amenities": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "hotel amenities
optional field
you can use this field to specify different hotel amenities
example: [
\"free_parking\",
\"pets_allowed\"
]
possible values:\"air_conditioning\","
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
\"all_inclusive_available\",
\"bar\",
\"free_breakfast\",
\"fitness_center\",
\"kid_friendly\",
\"free_parking\",
\"pets_allowed\",
\"pool\",
\"restaurant\",
\"room_service\",
\"spa\",
\"free_wifi\",
\"parking\",
\"indoor_pool\",
\"outdoor_pool\",
\"wheelchair_accessible\",
\"beach_access\"
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "New York,New York,United States",
"keyword": "RustyBrick, Inc."
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:67b0c00ef51d46a77a6f75bd33909db911ec04feabb5d80539da8c908a718bba"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/my_business_info/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:1e5fceb22c8171be867089e04d45d09b3a640dce8549c58bada13d62bafe21ce"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/my_business_info/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:7b252de220b416db239b2f699522d5a3b8b0f0aa647fa7b0819e4346d67ee4e8"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/my_business_updates/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;this field can also be used to pass cid (unique, google-defined id of the business entity) or place_id (identifier of the business entity in Google Maps) parameters
example:cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of updates in SERP
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten updates in a row
please note that Google returns 4490 updates maximum
default value: 10"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of results in SERP
default value: 20
max value: 100
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"language_code": "en",
"location_name": "Los Angeles,California,United States",
"keyword": "The Last Bookstore"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "Los Angeles,California,United States",
"keyword": "The Last Bookstore"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:ab9a7f2ea8268d2e5dadbb4068df056716de29235f389141d7d7ea355eeec4e1"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/questions_and_answers/live \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:6e122e8ba99300bf395ec7345d571a9658e3b073628eb85d088e23eb5a67b9d6"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/questions_and_answers/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the keyword you specify should indicate the name of the local establishment
you can specify up to 700 characters in the keyword filed
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”; cid - a unique, google-defined id of the business entity;place_id - an identifier of the business entity in Google Maps;cid:194604053573767737place_id:GhIJQWDl0CIeQUARxks3icF8U8Acid and place_id identifiers in this help center articlekeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840n"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9 (mm)
the maximum value for \"radius\": 199999 (mm)
example:53.476225,-2.243572,200n"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to https://api.dataforseo.com/v3/business_data/google/languages
example:enn"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of question rows in the result
default value: 20
max value: 700
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
If the specified depth is higher than the number of questions in the response, the difference will be refunded automatically to your account balance;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
learn more on our Help Center"
}
},
"example": [
{
"language_code": "en",
"location_name": "Los Angeles,California,United States",
"keyword": "The Last Bookstore"
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_name": "Los Angeles,California,United States",
"keyword": "The Last Bookstore"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:f8af6733e7cd66c9ac86584c72dd45d6f8913a1167e85bd65782012b56d6de91"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/questions_and_answers/task_post \\\n --header 'Authorization: Bearer
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:d46ec06ee3aced2ef2de23a10d7adb7a3400a1e51727bb387d75077b31ddaeb7"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/google/reviews/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field if you don't specify cid or place_id
the keyword you specify should indicate the name of the local establishment;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character)
if you need to use the “%” character for your keyword, please specify it as “%25”;
if this field contains such parameters as ‘allinanchor:’, ‘allintext:’, ‘allintitle:’, ‘allinurl:’, ‘define:’, ‘filetype:’, ‘id:’, ‘inanchor:’, ‘info:’, ‘intext:’, ‘intitle:’, ‘inurl:’, ‘link:’, ‘related:’, ‘site:’, the charge per task will be multiplied by 5
Note: queries containing the ‘cache:’ parameter are not supported and will return a validation errorkeyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"cid": {
"type": "string",
"description": "unique, google-defined id of the business entity
required field if you don't specify keyword or place_id
example:194604053573767737
learn more about the identifier in this help center article"
},
"place_id": {
"type": "string",
"description": "identifier of the business entity in Google Maps
required field if you don't specify keyword or cid
example:GhIJQWDl0CIeQUARxks3icF8U8A
learn more about the identifier in this help center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or location_coordinate
if you use this field, you don't need to specify location_code or location_coordinate
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name_or location_coordinate
if you use this field, you don't need to specify location_name or location_coordinate
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/google/locations
example:2840"
},
"location_coordinate": {
"type": "string",
"description": "GPS coordinates of a location
required field if you don't specify location_name_or location_code
if you use this field, you don't need to specify location_name or location_codelocation_coordinate parameter should be specified in the \"latitude,longitude,radius\" format
the maximum number of decimal digits for \"latitude\" and \"longitude\": 7
the minimum value for \"radius\": 199.9
example:53.476225,-2.243572,200"
},
"language_name": {
"type": "string",
"description": "full name of search engine language
required field if you don't specify language_code
if you use this field, you don't need to specify language_code
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:English"
},
"language_code": {
"type": "string",
"description": "search engine language code
required field if you don't specify language_name
if you use this field, you don't need to specify language_name
you can receive the list of available languages with their language_code_by making a separate request to the https://api.dataforseo.com/v3/business_data/google/languages
example:en"
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews in SERP
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row
default value: 10
maximum value: 4490
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results
possible types of sorting:newest – sort by newest firsthighest_rating – sort by highest ratinglowest_rating – sort by lowest ratingrelevant – sort by relevance
default value: relevant"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:1e96cd4895b3599c3620869e5be9345d8f266142b2c668d7e0ec4f2eccafb092"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/tripadvisor/reviews/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field if you do not specify keyword
URL path to the Tripadvisor page of the business entity;
examples:Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.htmlhttps://www.tripadvisor.com/Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html"
},
"keyword": {
"type": "string",
"description": "keyword
required field if you do not specify url_path
the keyword you specify should indicate a name of an existing business or prominent place on Tripadvisor;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code or url_path
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name or url_path
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:1003854"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"language_name": {
"type": [
"string",
"null"
],
"description": "full name of search engine language
optional field
if you use this field, your account will be charged for one extra request
you can receive the list of available languages with language_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/languages
example:English
You will be additionally charged for setting a language parameter in this endpoint.
The cost can be calculated on the Pricing page."
},
"language_code": {
"type": [
"string",
"null"
],
"description": "search engine language code
optional field
if you use this field, your account will be charged for one extra request
you can receive the list of available languages with language_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/languages
example:en
You will be additionally charged for setting a language parameter in this endpoint.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews in SERP;
we strongly recommend setting the parsing depth in the multiples of ten, because our systems processes ten reviews in a row;
default value: 10;
max value: 4490
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"ratings": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Tripadvisor traveler rating for a place of interest
optional field
rating based on the written reviews by a traveler after they visited a place.
possible values: excellent, very_good, average, poor, terrible
you can specify several values at once"
},
"visit_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "filter by type of travelers who left a review
optional field
possible values: families, couples, solo, business, friends
you can specify several values at once"
},
"months": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "filter by months when a traveler made a visit
optional field
possible values: january, february, march, april, may, april, june, july, august, september, october, november, december
you can specify several values at once"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameters
optional field
you can use this field to sort the results;
possible types of sorting:most_recentdetailed_reviews"
},
"translate_reviews": {
"type": [
"boolean",
"null"
],
"description": "translate reviews according to the URL path
optional field
if set to true, returned reviews will be translated to the language matching the specified url_path;
for example, if url_path contains tripadvisor.it and translate_reviews is true, reviews will be translated to the Italian language;
default value: true
you can learn more about how reviews are translated in this Help Center article"
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:055122d7f267d8f7596503f5b27d82f6d10487377289cf4211237b99bcca0c60"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/tripadvisor/search/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the keyword you specify should indicate a business category, company name, or a prominent place;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"location_name": {
"type": "string",
"description": "full name of search engine location
required field if you don't specify location_code
you can receive the list of available locations with location_name by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:London,England,United Kingdom"
},
"location_code": {
"type": "integer",
"description": "search engine location code
required field if you don't specify location_name
you can receive the list of available locations with location_code by making a separate request to the https://api.dataforseo.com/v3/business_data/tripadvisor/locations
example:1003854"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of search results to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of thirty because our systems processes thirty search results in a row;
default value: 30;
maximum value: 210
Setting depth above 30 may result in additional charges if the search engine returns more than 30 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:8fb36d9c26a0bc3c204dd67c5ec5eb782b6c3c383c362b66c3198f02ae6a8311"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/trustpilot/reviews/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
domain of the local establishment on Trustpilot;
you can find the domain in the URL of every business listed on Trustpilot
example:www.thepearlsource.comhttps://www.trustpilot.com/review/www.thepearlsource.com"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "results sorting parameter
optional field
you can use this field to sort the results;
possible sorting parameters:recency — most recent reviews first;relevance — most relevant reviews first;
default value: relevance"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of reviews to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of twenty, because our system processes twenty reviews in a row
default value: 20
maximum value: 200
Your account will be billed per each SERP containing up to 20 results;
Setting depth above 20 may result in additional charges if the search engine returns more than 20 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
unique task identifier in our system in the UUID format
you will be able to use it within 30 days to request the results of the task at any time",
"required": true,
"schema": {
"type": "string"
},
"example": "00000000-0000-0000-0000-000000000000"
}
],
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:203a6bb0e378b6ac004b3d15a15385c47472042ed7417c2d7de3da56f9df0455"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request GET \\\n --url https://api.aisa.one/apis/v1/dataforseo/business_data/trustpilot/search/task_get/00000000-0000-0000-0000-000000000000 \\\n --header 'Authorization: Bearer
required field
the keyword you specify should indicate a business category or company name;
you can specify up to 700 characters in the keyword filed;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"priority": {
"type": [
"integer",
"null"
],
"description": "task priority
optional field
can take the following values:
1 – normal execution priority (set by default)
2 – high execution priorityYou will be additionally charged for the tasks with high execution priority.
The cost can be calculated on the Pricing page."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "parsing depth
optional field
number of search results to be returned from the API response
we strongly recommend setting the parsing depth in the multiples of twenty because our systems processes twenty search results in a row;
default value: 10;
maximum value: 140
Your account will be billed per each SERP containing up to 10 results;
Setting depth above 10 may result in additional charges if the search engine returns more than 10 results;
The cost can be calculated on the Pricing page."
},
"tag": {
"type": [
"string",
"null"
],
"description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL for sending task results
optional field
once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Note: special characters in postback_url will be urlencoded;
i.a., the # character will be encoded into %23
optional field
when a task is completed we will notify you by GET request sent to the URL you have specified
you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request.
example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Note: special characters in pingback_url will be urlencoded;
i.a., the # character will be encoded into %23
required field
to obtain a full list of available categories, refer to the Categories endpoint"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns data on all citations for the target category_codeone_per_domain - returns data on one citation of the category_code per domain
default value: as_is"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"date_from": {
"type": "string",
"description": "starting date of the time range
required field
minimum value: 2022-10-31
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_group": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint;
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"category_code": 10994,
"search_mode": "as_is",
"date_from": "2022-09-01",
"date_group": "month"
}
]
}
]
},
"example": [
{
"category_code": 10994,
"search_mode": "as_is",
"date_from": "2022-09-01",
"date_group": "month"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:b99337f59977e4b9e1af367783894dfe0d16456ed04b3fb42ddf385f3e5b5580"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/content_analysis/category_trends/live \\\n --header 'Authorization: Bearer
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example: \"keyword\": \"\\\"tesla palo alto\\\"\"keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}`"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns data on all citations for the target keywordone_per_domain - returns data on one citation of the keyword per domain
default value: as_is"
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"date_from": {
"type": "string",
"description": "starting date of the time range
required field
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_to": {
"type": [
"string",
"null"
],
"description": "ending date of the time range
optional field
if you don't specify this field, today's date will be used by default
date format: \"yyyy-mm-dd\"
example:\"2019-01-15\""
},
"date_group": {
"type": [
"string",
"null"
],
"description": "time range which will be used to group the results
optional field
default value: month
possible values: day, week, month"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint;
you can add several filters at once (8 filters maximum);
you should set a logical operator and, or between the conditions;
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters;
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "logitech",
"search_mode": "as_is",
"date_from": "2022-09-01",
"date_group": "month"
}
]
}
]
},
"example": [
{
"keyword": "logitech",
"search_mode": "as_is",
"date_from": "2022-09-01",
"date_group": "month"
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:6da878ce8328dd116a91a2bc12f8e87f58784b62eb91e26e6b4654562fbeab01"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/content_analysis/phrase_trends/live \\\n --header 'Authorization: Bearer
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example: \"keyword\": \"\\\"tesla palo alto\\\"\"keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}`"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"internal_list_limit": {
"type": [
"integer",
"null"
],
"description": "maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays:top_domainstext_categoriespage_categoriescountrieslanguages
default value: 1
maximum value: 20"
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns all citations for the target keywordone_per_domain - returns one citation of the keyword per domain
default value: as_is"
},
"positive_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "positive connotation threshold
optional field
specified as the probability index threshold for positive sentiment related to the citation content
if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4"
},
"sentiments_connotation_threshold": {
"type": [
"number",
"null"
],
"description": "sentiment connotation threshold
optional field
specified as the probability index threshold for sentiment connotations related to the citation content
if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value
possible values: from 0 to 1
default value: 0.4"
},
"initial_dataset_filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "initial dataset filtering parameters
optional field
initial filtering parameters that apply to fields in the Search endpoint
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, has, has_not, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"domain\",\"<>\", \"logitech.com\"][[\"domain\",\"<>\",\"logitech.com\"],\"and\",[\"content_info.connotation_types.negative\",\">\",1000]][[\"domain\",\"<>\",\"logitech.com\"]],
\"and\",
[[\"content_info.connotation_types.negative\",\">\",1000],
\"or\",
for more information about filters, please refer to Content Analysis API - Filters
learn more about the initial dataset filters in this help center article."
},
"rank_scale": {
"type": [
"string",
"null"
],
"description": "defines the scale used for calculating and displaying the rank values
optional fieldone_hundred — rank values are displayed on a 0–100 scaleone_thousand — rank values are displayed on a 0–1000 scaleone_thousand
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response"
}
},
"example": [
{
"keyword": "logitech",
"search_mode": "as_is",
"internal_list_limit": 10
}
]
}
]
},
"example": [
{
"keyword": "logitech",
"search_mode": "as_is",
"internal_list_limit": 10
}
]
}
}
}
},
"x-aisa-source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"x-aisa-response-source": {
"kind": "upstream_success_contract",
"source": {
"kind": "provider_openapi",
"url": "https://raw.githubusercontent.com/dataforseo/OpenApiDocumentation/master/openapi_specification.yaml",
"fetched_at": "2026-10-15T14:24:49.272857+00:00",
"content_hash": "sha256:8539f0b2a3a415e5553c9337a97d2f74cc00e24db72cc0505ad5eab1f1e4ffff",
"converter": "scripts/import_upstream.py@3",
"owner": "AIsa-team/docs",
"refresh_policy": "automatic",
"review_period_days": 30,
"refresh_interval_hours": 24,
"policy_revision": "sha256:718bb0ba1ba18fb3b562443eb74e96aa9057b6e584050e7817cda944fe8fea62"
},
"content_hash": "sha256:86d8e9add85771c29a75a7343f7d6e88e023ddb71f36631533ec63ad914448bc"
},
"x-codeSamples": [
{
"lang": "text",
"label": "Reference example",
"source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/dataforseo/content_analysis/rating_distribution/live \\\n --header 'Authorization: Bearer
required field
UTF-8 encoding
the keywords will be converted to a lowercase format;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword\": \"\\\"tesla palo alto\\\"\"`keyword and keywords fields in DataForSEO APIs in this Help Center article"
},
"keyword_fields": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "target keyword fields and target keywords
optional field
use this parameter to filter the dataset by keywords that certain fields should contain;
fields you can specify: title, main_title, previous_title, snippet
you can indicate several fields;
Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
example:
`\"keyword_fields\": {
\"snippet\": \"\\\"logitech mouse\\\"\",
\"main_title\": \"sale\"
}\"`"
},
"page_type": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "target page types
optional field
use this parameter to filter the dataset by page types
possible values: \"ecommerce\", \"news\", \"blogs\", \"message-boards\", \"organization\""
},
"search_mode": {
"type": [
"string",
"null"
],
"description": "results grouping type
optional field
possible grouping types:as_is - returns all citations for the target keywordone_per_domain - returns one citation of the keyword per domain
default value: as_is"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "the maximum number of returned citations
optional field
default value: 100
maximum value: 1000"
},
"filters": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
]
},
"description": "array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported:regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like,not_like, match, not_match
you can use the % operator with like and not_like to match any string of zero or more characters
example:[\"country\",\"=\", \"US\"][[\"domain_rank\",\">\",800],\"and\",[\"content_info.connotation_types.negative\",\">\",0.9]][[\"domain_rank\",\">\",800],