{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "DataForSEO Serp API Schemas", "definitions": { "SerpGoogleOrganicLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "BaseResponseInfo": { "properties": { "version": { "type": "string", "description": "the current version of the API", "nullable": true }, "status_code": { "type": "integer", "description": "general status code\nyou can find the full list of the response codes here", "nullable": true }, "status_message": { "type": "string", "description": "general informational message\nyou can find the full list of general informational messages here", "nullable": true }, "time": { "type": "string", "description": "total execution time, seconds", "nullable": true }, "cost": { "type": "number", "description": "total tasks cost, USD", "format": "double", "nullable": true }, "tasks_count": { "type": "integer", "description": "the number of tasks in the tasks array", "format": "int64", "nullable": true }, "tasks_error": { "type": "integer", "description": "the number of tasks in the tasks array returned with an error", "format": "int64", "nullable": true } } }, "SerpGoogleOrganicLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "BaseResponseTaskInfo": { "properties": { "id": { "type": "string", "description": "task identifier\nunique task identifier in our system in the UUID format", "nullable": true }, "status_code": { "type": "integer", "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", "nullable": true }, "status_message": { "type": "string", "description": "informational message of the task\nyou can find the full list of general informational messages here", "nullable": true }, "time": { "type": "string", "description": "execution time, seconds", "nullable": true }, "cost": { "type": "number", "description": "total tasks cost, USD", "format": "double", "nullable": true }, "result_count": { "type": "integer", "description": "number of elements in the result array", "format": "int64", "nullable": true }, "path": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "URL path", "nullable": true }, "data": { "type": "object", "additionalProperties": { "type": "object", "nullable": true }, "description": "contains the same parameters that you specified in the POST request", "nullable": true } } }, "SerpGoogleOrganicLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "HtmlItemInfo": { "type": "object", "properties": { "page": { "type": "integer", "description": "serial number of the returned HTML page", "nullable": true }, "date": { "type": "string", "description": "date and time when the HTML page was scanned\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "html": { "type": "string", "description": "HTML\u00a0page", "nullable": true } } }, "SerpBingOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpNaverOrganicTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpNaverOrganicTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpNaverOrganicTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleLocalFinderLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocalFinderLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "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", "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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nonly value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "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", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "video_id": "vQXvyV0zIP4" } ] }, "SerpNaverOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpNaverOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpNaverOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nimages, local_pack, map, organic, paid, related_searches, video", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "SpellInfo": { "properties": { "keyword": { "type": "string", "description": "keyword obtained as a result of search engine autocorrection\n the results will be provided for the corrected keyword", "nullable": true }, "type": { "type": "string", "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", "nullable": true } } }, "RefinementChipsInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsElement" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "RefinementChipsElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "domain": { "type": "string", "description": "domain in SERP", "nullable": true }, "options": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonLabelElement" } ], "nullable": true }, "description": "further search refinement options", "nullable": true } } }, "AmazonLabelElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "domain": { "type": "string", "description": "domain in SERP", "nullable": true } } }, "BaseSerpApiElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "page": { "type": "integer", "description": "search results page number\nindicates the number of the SERP page on which the element is located", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "rectangle": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeRectangleInfo" } ], "description": "rectangle parameters\ncontains cartesian coordinates and pixel dimensions of the result\u2019s snippet in SERP\nequals null if calculate_rectangles in the POST request is not set to true", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "paid": "#/components/schemas/PaidSerpElementItem", "organic": "#/components/schemas/OrganicSerpElementItem", "featured_snippet": "#/components/schemas/FeaturedSnippetSerpElementItem", "knowledge_graph": "#/components/schemas/KnowledgeGraphSerpElementItem", "top_stories": "#/components/schemas/TopStoriesSerpElementItem", "people_also_ask": "#/components/schemas/PeopleAlsoAskSerpElementItem", "people_also_search": "#/components/schemas/PeopleAlsoSearchSerpElementItem", "images": "#/components/schemas/ImagesSerpElementItem", "twitter": "#/components/schemas/TwitterSerpElementItem", "google_reviews": "#/components/schemas/GoogleReviewsSerpElementItem", "jobs": "#/components/schemas/JobsSerpElementItem", "map": "#/components/schemas/MapSerpElementItem", "app": "#/components/schemas/AppSerpElementItem", "local_pack": "#/components/schemas/LocalPackSerpElementItem", "carousel": "#/components/schemas/CarouselSerpElementItem", "video": "#/components/schemas/VideoSerpElementItem", "answer_box": "#/components/schemas/AnswerBoxSerpElementItem", "shopping": "#/components/schemas/ShoppingSerpElementItem", "google_flights": "#/components/schemas/GoogleFlightsSerpElementItem", "mention_carousel": "#/components/schemas/MentionCarouselSerpElementItem", "events": "#/components/schemas/EventsSerpElementItem", "related_searches": "#/components/schemas/RelatedSearchesSerpElementItem", "multi_carousel": "#/components/schemas/MultiCarouselSerpElementItem", "recipes": "#/components/schemas/RecipesSerpElementItem", "top_sights": "#/components/schemas/TopSightsSerpElementItem", "scholarly_articles": "#/components/schemas/ScholarlyArticlesSerpElementItem", "popular_products": "#/components/schemas/PopularProductsSerpElementItem", "podcasts": "#/components/schemas/PodcastsSerpElementItem", "stocks_box": "#/components/schemas/StocksBoxSerpElementItem", "find_results_on": "#/components/schemas/FindResultsOnSerpElementItem", "questions_and_answers": "#/components/schemas/QuestionsAndAnswersSerpElementItem", "hotels_pack": "#/components/schemas/HotelsPackSerpElementItem", "visual_stories": "#/components/schemas/VisualStoriesSerpElementItem", "commercial_units": "#/components/schemas/CommercialUnitsSerpElementItem", "local_services": "#/components/schemas/LocalServicesSerpElementItem", "google_hotels": "#/components/schemas/GoogleHotelsSerpElementItem", "math_solver": "#/components/schemas/MathSolverSerpElementItem", "currency_box": "#/components/schemas/CurrencyBoxSerpElementItem", "google_posts": "#/components/schemas/GooglePostsSerpElementItem", "product_considerations": "#/components/schemas/ProductConsiderationsSerpElementItem", "found_on_web": "#/components/schemas/FoundOnWebSerpElementItem", "short_videos": "#/components/schemas/ShortVideosSerpElementItem", "refine_products": "#/components/schemas/RefineProductsSerpElementItem", "explore_brands": "#/components/schemas/ExploreBrandsSerpElementItem", "perspectives": "#/components/schemas/PerspectivesSerpElementItem", "discussions_and_forums": "#/components/schemas/DiscussionsAndForumsSerpElementItem", "compare_sites": "#/components/schemas/CompareSitesSerpElementItem", "courses": "#/components/schemas/CoursesSerpElementItem", "knowledge_graph_carousel_item": "#/components/schemas/KnowledgeGraphCarouselItemSerpElementItem", "knowledge_graph_description_item": "#/components/schemas/KnowledgeGraphDescriptionItemSerpElementItem", "knowledge_graph_images_item": "#/components/schemas/KnowledgeGraphImagesItemSerpElementItem", "knowledge_graph_list_item": "#/components/schemas/KnowledgeGraphListItemSerpElementItem", "knowledge_graph_row_item": "#/components/schemas/KnowledgeGraphRowItemSerpElementItem", "knowledge_graph_hotels_booking_item": "#/components/schemas/KnowledgeGraphHotelsBookingItemSerpElementItem", "knowledge_graph_expanded_item": "#/components/schemas/KnowledgeGraphExpandedItemSerpElementItem", "knowledge_graph_part_item": "#/components/schemas/KnowledgeGraphPartItemSerpElementItem", "knowledge_graph_shopping_item": "#/components/schemas/KnowledgeGraphShoppingItemSerpElementItem", "knowledge_graph_ai_overview_item": "#/components/schemas/KnowledgeGraphAiOverviewItemSerpElementItem", "ai_overview": "#/components/schemas/AiOverviewSerpElementItem", "third_party_reviews": "#/components/schemas/ThirdPartyReviewsSerpElementItem", "dictionary": "#/components/schemas/DictionarySerpElementItem" } } }, "AiModeRectangleInfo": { "type": "object", "properties": { "x": { "type": "number", "description": "x-axis coordinate\nx-axis coordinate of the top-left corner of the result\u2019s snippet, where top-left corner of the screen is the origin", "format": "double", "nullable": true }, "y": { "type": "number", "description": "y-axis coordinate\ny-axis coordinate of the top-left corner of the result\u2019s snippet, where top-left corner of the screen is the origin", "format": "double", "nullable": true }, "width": { "type": "number", "description": "width of the element in pixels", "format": "double", "nullable": true }, "height": { "type": "number", "description": "height of the element in pixels", "format": "double", "nullable": true } } }, "SerpYahooOrganicLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleNewsLiveAdvancedRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;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 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "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;If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automaticallyThe cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldGet the list of available parameters and additional details here.", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate 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 falseNote: if set to true, the charge per task will be multiplied by 2", "nullable": true }, "browser_screen_width": { "type": "integer", "description": "browser screen widthoptional fieldyou can set a custom browser screen width to calculate pixel rankings for a particular device;by default, the parameter is set to 1920;Note: to use this parameter, set calculate_rectangles to true", "format": "int64", "nullable": true }, "browser_screen_height": { "type": "integer", "description": "browser screen heightoptional fieldyou can set a custom browser screen height to calculate pixel rankings for a particular device;by default, the parameter is set to 1080;Note: to use this parameter, set calculate_rectangles to true", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "description": "browser screen resolution ratiooptional fieldyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;by default, the parameter is set to 1;Note: to use this parameter, set calculate_rectangles to true", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "android" } ] }, "SerpGoogleSearchByImageTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleSearchByImageTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleSearchByImageTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: search_by_image", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleOrganicTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;if this field contains such parameters as \u2018allinanchor:\u2019, \u2018allintext:\u2019, \u2018allintitle:\u2019, \u2018allinurl:\u2019, \u2018define:\u2019, \u2018filetype:\u2019, \u2018id:\u2019, \u2018inanchor:\u2019, \u2018info:\u2019, \u2018intext:\u2019, \u2018intitle:\u2019, \u2018inurl:\u2019, \u2018link:\u2019, \u2018site:\u2019, the charge per task will be multiplied by 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 10max value: 700Your 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.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "load_async_ai_overview": { "type": "boolean", "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: falseNote: you will be charged extra $0.0006 for using this parameter;if the element is absent or contains \"asynchronous_ai_overview\": false, all extra charges will be returned to your account balance", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:regular, advanced, html", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match typerequired field if stop_crawl_on_match is specifiedtype of match for the match_valuepossible values:domain \u2013 specific domain or subdomainwith_subdomains \u2013 main domain and subdomainswildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "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-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "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", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "remove_from_url": { "type": "array", "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\"]", "nullable": true }, "expand_ai_overview": { "type": "boolean", "description": "expand ai overviewoptional fieldset to true to expand the ai_overview item;default value: false;Note: this parameter applies only to HTML task results", "nullable": true }, "people_also_ask_click_depth": { "type": "integer", "description": "clicks on the corresponding elementoptional fieldspecify the click depth on the people_also_ask element to get additional people_also_ask_element items;Note your account will be billed $0.00015 extra for each click regardless of task priority;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", "nullable": true }, "group_organic_results": { "type": "boolean", "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", "nullable": true }, "calculate_rectangles": { "type": "boolean", "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 falseNote: you will be charged extra $0.0006 for using this parameter", "nullable": true }, "browser_screen_width": { "type": "integer", "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", "nullable": true }, "browser_screen_height": { "type": "integer", "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", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "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", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "target_search_mode": { "type": "string", "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 \u2013 the crawl stops only when all specified targets are foundany \u2013 the crawl stops when any single target is founddefault value: anylearn more about this parameter on our Help Center", "nullable": true }, "find_targets_in": { "type": "array", "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", "nullable": true }, "ignore_targets_in": { "type": "array", "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", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" }, { "language_name": "English", "location_name": "United States", "keyword": "albert einstein", "priority": 2, "tag": "some_string_123", "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag" }, { "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "postback_data": "html", "postback_url": "https://your-server.com/postbackscript" } ] }, "SerpApiStopCrawlOnMatchInfo": { "type": "object", "properties": { "match_value": { "type": "string", "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", "nullable": true }, "match_type": { "type": "string", "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", "nullable": true } } }, "SerpGoogleAiModeTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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/locationsNote: check Google Search Help for the list of countries where AI Mode is currently available", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired 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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced, html", "nullable": true }, "location_name": { "type": "string", "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/locationsNote: check Google Search Help for the list of countries where AI Mode is currently available", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired 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;", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate 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 falseNote: if set to true, the charge per task will be multiplied by 2", "nullable": true }, "browser_screen_width": { "type": "integer", "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", "nullable": true }, "browser_screen_height": { "type": "integer", "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", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "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", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 9z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 4zthe maximum value for \"zoom\": 18zexample:52.6178549,-155.352142,18z", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "what is google ai mode" } ] }, "SerpGoogleDatasetInfoTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: dataset_info", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleOrganicTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpSeznamOrganicTaskGetRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskGetRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamOrganicTaskGetRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskGetRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamOrganicTaskGetRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\nimages, local_pack, organic, related_searches, top_stories, featured_snippet, video\nnote that this array contains all types of search results found in the returned SERP;\nhowever, this endpoint provides data for the organic type only\nto get all items (inlcuding SERP features and rich snippets) found in the returned SERP, please refer to the Seznam Organi\u0441 Advanced SERP endpoint", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpBaiduLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpBaiduOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceTickerSearchTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: finance_ticker_search", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceMarketsTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nin this case, equals null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nads_muti_account_advertiser, ads_advertiser, ads_domain", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiAdsAdvertiserElementItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "BaseSerpApiAdsAdvertiserElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "ads_multi_account_advertiser": "#/components/schemas/SerpApiAdsMultiAccountAdvertiserElementItem", "ads_advertiser": "#/components/schemas/SerpApiAdsAdvertiserElementItem", "ads_domain": "#/components/schemas/SerpApiAdsDomainElementItem" } } }, "SerpGoogleImagesLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleImagesLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleFinanceExploreTaskPostRequestInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:: advanced, html", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "news_type": { "type": "string", "description": "financial news filtersoptional fieldpossible values: top_stories, local_market, world_marketsdefault value: top_storiesNote: if you specify local_market or world_markets, the charge per task will be multiplied by 2", "nullable": true } }, "example": [ { "location_code": 2840, "language_name": "English" } ] }, "SerpBingOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpSeznamOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceQuoteLiveHtmlRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "ticker or stock symbolrequired fieldin 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 keyword field;all %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "window": { "type": "string", "description": "time window for google_finance_quote graphoptional fieldpossible values: 1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAXdefault value: 1D", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "NASDAQ-100" } ] }, "SerpYahooOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nfeatured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "SerpBingOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nanswer_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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseBingSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "BaseBingSerpApiElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "page": { "type": "integer", "description": "search results page number\nindicates the number of the SERP page on which the element is located", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "rectangle": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeRectangleInfo" } ], "description": "rectangle parameters\ncontains cartesian coordinates and pixel dimensions of the result\u2019s snippet in SERP\nequals null if calculate_rectangles in the POST request is not set to true", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "organic": "#/components/schemas/BingOrganicSerpElementItem", "paid": "#/components/schemas/BingPaidSerpElementItem", "featured_snippet": "#/components/schemas/BingFeaturedSnippetSerpElementItem", "related_searches": "#/components/schemas/BingRelatedSearchesSerpElementItem", "ai_overview": "#/components/schemas/BingAiOverviewSerpElementItem", "images": "#/components/schemas/BingImagesSerpElementItem", "video": "#/components/schemas/BingVideoSerpElementItem", "shopping": "#/components/schemas/BingShoppingSerpElementItem", "answer_box": "#/components/schemas/BingAnswerBoxSerpElementItem", "local_pack": "#/components/schemas/BingLocalPackSerpElementItem", "questions_and_answers": "#/components/schemas/BingQuestionsAndAnswersSerpElementItem", "hotels_pack": "#/components/schemas/BingHotelsPackSerpElementItem", "jobs": "#/components/schemas/BingJobsSerpElementItem", "top_stories": "#/components/schemas/BingTopStoriesSerpElementItem", "carousel": "#/components/schemas/BingCarouselSerpElementItem", "map": "#/components/schemas/BingMapSerpElementItem", "events": "#/components/schemas/BingEventsSerpElementItem", "recipes": "#/components/schemas/BingRecipesSerpElementItem", "people_also_ask": "#/components/schemas/BingPeopleAlsoAskSerpElementItem", "people_also_search": "#/components/schemas/BingPeopleAlsoSearchSerpElementItem" } } }, "SerpYoutubeLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpGoogleAiModeTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleAiModeLiveHtmlRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;" }, "location_name": { "type": "string", "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", "nullable": true }, "location_code": { "type": "integer", "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:2840n", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200n", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired 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;", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired 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", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpBaiduOrganicTaskPostRequestInfo": { "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 \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10\nmax value: 700\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t 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/baidu/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 mandatory\nexample:\nChinese (Simplified)", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/baidu/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 mandatory\nexample:\nzh_CN", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don\u2019t specify location_code or location_coordinate\nif you use this field, you don\u2019t need to specify location_code or location_coordinate\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/baidu/locations\nexample:\nNew York,New York,United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\u00a0or location_coordinate\nif you use this field, you don\u2019t need to specify location_name or location_coordinate\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/baidu/locations\nexample:\n2156", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or location_code\nif you use this field, you don\u2019t need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \u201clatitude,longitude,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9 (mm)\nthe maximum value for \u201cradius\u201d: 199999 (mm)if you use this field, the returned results will be based on the closest city found for your coordinates. Thus, we don\u2019t recommend using this field as the results might not be relevant to the specified coordinates\nexample:\n53.476225,-2.243572,200", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values: desktop, mobile, tablet\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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\nif you specify tablet in the device field, choose from the following values: android, ios\ndefault value: android", "nullable": true }, "get_website_url": { "type": "boolean", "description": "include direct URL for each ranked result\noptional field\nif set to true, the returned results will contain direct URLs of the ranked websites\nby default, the URLs in Baidu results are encoded by the search engine,\nfor example:\nhttp://www.baidu.com/link?url=KQt6LSwU5OHnPtB8210R8flBP40grY6lTPxH_0UO7S2kgiZMTmw3ztV0hCo5c1kLdefault value: false\nNote: 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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "postback_url": { "type": "string", "description": "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible values:\nregular, html", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true } }, "example": [ { "location_code": 2156, "keyword": "best iphone ever", "tag": "some_string_123", "priority": 2 } ] }, "SerpGoogleFinanceExploreLiveAdvancedRequestInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "news_type": { "type": "string", "description": "financial news filtersoptional fieldpossible values: top_stories, local_market, world_marketsdefault value: top_storiesNote: if you specify local_market or world_markets, the charge per task will be multiplied by 2", "nullable": true } }, "example": [ { "location_code": 2840, "language_name": "English" } ] }, "SerpBingOrganicLiveRegularRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0or location_coordinate\nif you use this field, you don't need to specify location_name or location_coordinate\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/bing/locations\nexample:\n2840", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/bing/languages\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10\nmax value: 200\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don't specify location_code or location_coordinate\nif you use this field, you don't need to specify location_code or location_coordinate\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/bing/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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/bing/languages\nexample:\nEnglish", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "target": { "type": "string", "description": "target domain, subdomain, or webpage to get results for\noptional field\na domain or a subdomain should be specified without https:// and www.\nnote that the results of target-specific tasks will only include SERP elements that contain a url string;\nyou can also use a wildcard (\u2018*\u2019) character to specify the search pattern in SERP and narrow down the results;\nexamples:\nexample.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/;\nexample.com* - returns results for the domain, including all its pages;\n*example.com* - returns results for the entire domain, including all its pages and subdomains;\n*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;\nexample.com/example-page - returns results for the exact URL;\nexample.com/example-page* - returns results for all domain's URLs that start with the specified string", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don't specify location_name\u00a0or location_code\nif you use this field, you don't need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \"latitude,longitude\" format\nthe maximum number of decimal digits for \"latitude\" and \"longitude\": 7\nexample:\n53.476225,-2.243572", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleLocalFinderTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value for desktop: 20max value for desktop: 500default value for mobile: 10max value for mobile: 350Your account will be billed per each SERP containing up to 20 results for desktop or up to 10 results for a mobile device;Setting depth above 20 for desktop or above 10 for mobile may result in additional charges if the search engine returns more than 20 or 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 automaticallyThe cost can be calculated on the Pricing page.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced, html", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 9z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 4zthe maximum value for \"zoom\": 18zexample:52.6178549,-155.352142,18z", "nullable": true }, "min_rating": { "type": "number", "description": "filter results by minimum ratingoptional fieldpossible values for desktop: 3.5, 4, 4.5;possible values for mobile: 2, 2.5, 3, 3.5, 4, 4.5", "format": "double", "nullable": true }, "time_filter": { "type": "string", "description": "filter results by open hoursoptional fieldusing this field, you can filter places in the results by the time a place is open for visitorsnote that Google may also provide results that do not match this filterpossible values: \"open_now\", \"24_hours\", \"$day_value\", \"$day_value;$time_value\";instead of $day_value use one of these values: \"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\", \"saturday\", \"sunday\";instead of $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\"example: \"tuesday;18\"", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "local nail services", "min_rating": 4.5, "time_filter": "monday" } ] }, "SerpYahooLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpGoogleNewsTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleNewsTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: news", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYoutubeVideoCommentsTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: video_comments", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpBaiduOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nimages, local_pack, map, organic, paid, related_searches, video, stocks_box, dictionary, shopping", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "SerpSeznamLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nonly City location_type is supported for all countries except China (where Country is also supported);\ndon\u2019t 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", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } }, "SerpYahooOrganicTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpYoutubeLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpNaverOrganicTaskPostRequestInfo": { "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 \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou can specify a direct URL and we will sort it out to the necessary fields\nin most cases, we wouldn\u2019t recommend using this method;\nexample:\nhttps://search.naver.com/search.naver?where=nexearch&sm=top_hty&fbm=1&ie=utf8&query=iphone", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 15\nmax value: 700\nYour account will be billed per each SERP containing up to 15 results;\nSetting depth above 15 may result in additional charges if the search engine returns more than 15 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically\nhowever, you can set a custom search engine domain in this field\nexample:\nsearch.naver.com", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "postback_url": { "type": "string", "description": "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the function you used for setting a task\npossible values:\nregular, advanced, html", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true } }, "example": [ { "keyword": "albert einstein", "device": "desktop", "tag": "some_string_123", "postback_url": "https://your-server.com/postbackscript.php", "postback_data": "regular" } ] }, "SerpAiSummaryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpAiSummaryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpAiSummaryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpAiSummaryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpAiSummaryResultInfo": { "type": "object", "properties": { "items_count": { "type": "integer", "description": "number of items in the results array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpAiSummaryItem" } ], "nullable": true }, "description": "items array", "nullable": true } } }, "SerpAiSummaryItem": { "type": "object", "properties": { "summary": { "type": "string", "description": "generated summary\nsummary generated by the AI model according to the parameters specified in the request", "nullable": true } } }, "SerpGoogleOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleImagesTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleImagesTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: images", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpBingOrganicLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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\nequals null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nanswer_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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseBingSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "SerpGoogleFinanceMarketsLiveAdvancedRequestInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "market_type": { "type": "string", "description": "type of google finance marketoptional fieldpossible values: most-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currenciesdefault value: most-active", "nullable": true } }, "example": [ { "location_code": 2840, "language_name": "English" } ] }, "SerpGoogleFinanceMarketsTaskPostRequestInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:: advanced, html", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "market_type": { "type": "string", "description": "type of google finance marketoptional fieldpossible values: most-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currenciesdefault value: most-active", "nullable": true } }, "example": [ { "location_code": 2840, "language_name": "English" } ] }, "SerpYoutubeOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_fixed": { "type": "string", "description": "date when the task was fixed (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleImagesLiveAdvancedRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;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 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 100max value: 700Your 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;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.", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldGet the list of available parameters and additional details here.", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domainoptional fieldWe 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 fieldexample:google.co.uk, google.com.au, google.de, etc.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpYoutubeVideoCommentsTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTaskGetAdvancedResultInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_comment", "nullable": true }, "title": { "type": "string", "description": "title of the video", "nullable": true }, "comments_count": { "type": "integer", "description": "number of comments on the video", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/YoutubeComment" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "YoutubeComment": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP for the target domain\nabsolute position among all the elements in SERP", "nullable": true }, "author_name": { "type": "string", "description": "name of the author of the comment", "nullable": true }, "author_thumbnail": { "type": "string", "description": "the URL of the page where the author\u2019s channel logo is hosted", "nullable": true }, "author_url": { "type": "string", "description": "URL of the author\u2019s channel", "nullable": true }, "text": { "type": "string", "description": "text of the comment", "nullable": true }, "publication_date": { "type": "string", "description": "displayed publication date", "nullable": true }, "timestamp": { "type": "string", "description": "date and time when the result was published\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2022-11-15 12:57:46 +00:00", "nullable": true }, "likes_count": { "type": "integer", "description": "number of likes on the comment", "format": "int64", "nullable": true }, "reply_count": { "type": "integer", "description": "number of replies on the comment", "format": "int64", "nullable": true } } }, "SerpGoogleDatasetInfoLiveAdvancedRequestInfo": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "ID of the datasetrequired fieldyou can find dataset ID in the dataset URL or dataset item of Google Dataset Search resultexample:L2cvMTFqbl85ZHN6MQ==" }, "language_code": { "type": "string", "description": "search engine language codeoptional fieldif you use this field, you don't need to specify language_namepossible value:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languageoptional fieldif you use this field, you don't need to specify language_codepossible value:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "dataset_id": "L2cvMTFqbl85ZHN6MQ==" } ] }, "SerpYahooOrganicTaskGetRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskGetRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicTaskGetRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskGetRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicTaskGetRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\nfeatured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview;\nnote that this array contains all types of search results found in the returned SERP;\nhowever, this endpoint provides data for organic, paid, and featured_snippet types only;\nto get all items (including SERP features and rich snippets) found in the returned SERP, please refer to the Yahoo Organi\u0441 Advanced SERP endpoint", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpErrorsRequestInfo": { "type": "object", "properties": { "limit": { "type": "integer", "description": "the maximum number of returned tasks that responded with an error\noptional field\ndefault value: 1000\nmaximum value: 1000\nminimum value: 1", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned tasks\noptional field\nif you specify the 10 value, the first ten tasks in the results array will be omitted and the data will be provided for the successive tasks\ndefault and minimum value: 0\nmaximum value: 100M (100 million)", "nullable": true }, "filtered_function": { "type": "string", "description": "return tasks with a certain function\nuse this field to obtain a list of tasks that returned an error filtered by the certain endpoint\u2019s URL, as well as pingback_url or postback_url specified in the API request;\nyou can filter the results by the values you receive in the function fields of the API response;\ni.e., once you receive unfiltered results, you can call this API again to filter them by function;\nexample: serp/task_get/advanced", "nullable": true }, "datetime_from": { "type": "string", "description": "start time for filtering results\noptional field\nallows filtering results by the datetime parameter within the range of the last 7 days;\nmust be specified in the UTC format: \"yyyy-mm-dd hh-mm-ss +00:00\";\nminimum value: 7 days from the current datetime\nmaximum value: current datetime\nexample:\n2021-11-15 12:57:46 +00:00", "nullable": true }, "datetime_to": { "type": "string", "description": "finish time for filtering results\noptional field\nallows filtering results by the datetime parameter within the range of the last 7 days;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nminimum value: 7 days from the current datetime\nmaximum value: current datetime\nNote datetime_to must be greater than datetime_from if both parameters are used;\nexample:\n2021-11-15 13:57:46 +00:00", "nullable": true } }, "example": [ { "limit": 10, "offset": 0, "filtered_function": "pingback_url" } ] }, "SerpGoogleNewsLiveHtmlRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;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 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 locations of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "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;If the specified depth is higher than the number of results in the response, the difference will be refunded to your account balance automaticallyThe cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 locations of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpYoutubeVideoSubtitlesTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: video_subtitles", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleEventsTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleEventsTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpGoogleLocalFinderLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value for desktop: 20max value for desktop: 100default value for mobile: 10max value for mobile: 100Your account will be billed per each SERP containing up to 20 results for desktop or up to 10 results for a mobile device;Setting depth above 20 for desktop or above 10 for mobile may result in additional charges if the search engine returns more than 20 or 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 automaticallyThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 9z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 4zthe maximum value for \"zoom\": 18zexample:52.6178549,-155.352142,20z", "nullable": true }, "min_rating": { "type": "number", "description": "filter results by minimum ratingoptional fieldpossible values for desktop: 3.5, 4, 4.5;possible values for mobile: 2, 2.5, 3, 3.5, 4, 4.5", "format": "double", "nullable": true }, "time_filter": { "type": "string", "description": "filter results by open hoursoptional fieldusing this field, you can filter places in the results by the time a place is open for visitorsnote that Google may also provide results that do not match this filterpossible values: \"open_now\", \"24_hours\", \"$day_value\", \"$day_value;$time_value\";instead of $day_value use one of these values: \"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\", \"saturday\", \"sunday\";instead of $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\"example: \"tuesday;18\"", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "local nail services", "min_rating": 4.5, "time_filter": "monday" } ] }, "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", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0\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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nonly value: desktop", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "video_id": "vQXvyV0zIP4" } ] }, "SerpSeznamOrganicTaskPostRequestInfo": { "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 \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn 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\nrequired field if you don\u2019t specify location_code\nif you use this field, you don\u2019t 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/seznam/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\nif you use this field, you don\u2019t 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/seznam/locations\nexample:\n2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t 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/seznam/languages\nexample:\nCzech", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/seznam/languages\nexample:\ncs", "nullable": true }, "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou can specify a direct URL and we will sort it out to the necessary fields;\nnote 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;\nin most cases, we wouldn\u2019t recommend using this method.", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10;\nmaximum value: 500;\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 10\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically\nhowever, you can set a custom search engine domain in this field\nexample:\nsearch.seznam.cz", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate pixel rankings for SERP elements in advanced results\noptional field\npixel ranking refers to the distance between the result snippet and top left corner of the screen;\nVisit Help Center to learn more>>\nby default, the parameter is set to false\nNote: if set to true, the charge per task will be multiplied by 2", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "postback_url": { "type": "string", "description": "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the function you used for setting a task\npossible values:\nregular, advanced, html", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true } }, "example": [ { "language_code": "cs", "location_code": 2203, "keyword": "albert einstein" } ] }, "SerpGoogleNewsTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;if this field contains such parameters as \u2018allinanchor:\u2019, \u2018allintext:\u2019, \u2018allintitle:\u2019, \u2018allinurl:\u2019, \u2018define:\u2019, \u2018filetype:\u2019, \u2018id:\u2019, \u2018inanchor:\u2019, \u2018info:\u2019, \u2018intext:\u2019, \u2018intitle:\u2019, \u2018inurl:\u2019, \u2018link:\u2019, \u2018related:\u2019, \u2018site:\u2019, the charge per task will be multiplied by 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 10max value: 700Your 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;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.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced, html", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate 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 falseNote: if set to true, the charge per task will be multiplied by 2", "nullable": true }, "browser_screen_width": { "type": "integer", "description": "browser screen widthoptional fieldyou can set a custom browser screen width to calculate pixel rankings for a particular device;by default, the parameter is set to 1920;Note: to use this parameter, set calculate_rectangles to true", "format": "int64", "nullable": true }, "browser_screen_height": { "type": "integer", "description": "browser screen heightoptional fieldyou can set a custom browser screen height to calculate pixel rankings for a particular device;by default, the parameter is set to 1080;Note: to use this parameter, set calculate_rectangles to true", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "description": "browser screen resolution ratiooptional fieldyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;by default, the parameter is set to 1;Note: to use this parameter, set calculate_rectangles to true", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method;example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleAiModeTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: ai_mode", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleAdsAdvertisersTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location codeoptional fieldif 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/ads_advertisers/locationsexample:2840Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine locationoptional fieldif 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/ads_advertisers/locationsexample:London,England,United KingdomNote: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationoptional fieldif you use this field, you don't need to specify location_name or location_codeexample:52.6178549,-155.352142Note: if you don't specify location_name, location_code, or location_coordinate, advertisers will be searched across all the available locations", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "location_code": 2840, "keyword": "apple" } ] }, "SerpGoogleLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpGoogleMapsTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleMapsTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleMapsTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: maps", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleSearchByImageTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleSearchByImageTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleSearchByImageTaskGetAdvancedResultInfo": { "type": "object", "properties": { "image_url": { "type": "string", "description": "URL specified in a POST array", "nullable": true }, "keyword": { "type": "string", "description": "keyword Google associated with the specified image", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\norganic,\nimages", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleSearchByImagesElementItem" } ], "nullable": true }, "description": "items featured in the faq_box", "nullable": true } } }, "BaseSerpApiGoogleSearchByImagesElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "page": { "type": "integer", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "rectangle": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeRectangleInfo" } ], "description": "rectangle parameters\ncontains cartesian coordinates and pixel dimensions of the result\u2019s snippet in SERP\nequals null if calculate_rectangles in the POST request is not set to true", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "organic": "#/components/schemas/SerpApiGoogleSearchByImagesOrganicElementItem", "images": "#/components/schemas/SerpApiGoogleSearchByImagesImagesElementItem" } } }, "SerpGoogleLocalFinderLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocalFinderLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nlocal_pack", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LocalPackSerpElementItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "LocalPackSerpElementItem": { "type": "object", "allOf": [ { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, { "type": "object", "properties": { "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP\nalways equals 0 for desktop", "nullable": true }, "title": { "type": "string", "description": "title of a given link element", "nullable": true }, "description": { "type": "string", "description": "link description", "nullable": true }, "domain": { "type": "string", "description": "domain name of the reference", "nullable": true }, "phone": { "type": "string", "description": "phone number", "nullable": true }, "booking_url": { "type": "string", "description": "URL of the booking page", "nullable": true }, "url": { "type": "string", "description": "URL", "nullable": true }, "is_paid": { "type": "boolean", "description": "indicates whether the element is an ad", "nullable": true }, "rating": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RatingInfo" } ], "description": "the item\u2019s rating \nthe popularity rate based on reviews and displayed in SERP;\nif there is none, equals null", "nullable": true }, "cid": { "type": "string", "description": "google-defined client id", "nullable": true } } } ] }, "RatingInfo": { "properties": { "rating_type": { "type": "string", "description": "the type of rating\nhere you can find the following elements: Max5, Percents, CustomMax", "nullable": true }, "value": { "type": "number", "description": "the value of the rating", "format": "double", "nullable": true }, "votes_count": { "type": "integer", "description": "the amount of feedback", "format": "int64", "nullable": true }, "rating_max": { "type": "integer", "description": "the maximum value for a rating_type", "nullable": true } } }, "SerpGoogleFinanceTickerSearchTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: finance_explore", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleLocalFinderLiveHtmlRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value for desktop: 20max value for desktop: 100default value for mobile: 10max value for mobile: 100Your account will be billed per each SERP containing up to 20 results for desktop or up to 10 results for a mobile device;Setting depth above 20 for desktop or above 10 for mobile may result in additional charges if the search engine returns more than 20 or 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 automaticallyThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 9z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 4zthe maximum value for \"zoom\": 18zexample:52.6178549,-155.352142,20z", "nullable": true }, "min_rating": { "type": "string", "description": "filter results by minimum ratingoptional fieldpossible values for desktop: 3.5, 4, 4.5;possible values for mobile: 2, 2.5, 3, 3.5, 4, 4.5", "nullable": true }, "time_filter": { "type": "string", "description": "filter results by open hoursoptional fieldusing this field, you can filter places in the results by the time a place is open for visitorsnote that Google may also provide results that do not match this filterpossible values: \"open_now\", \"24_hours\", \"$day_value\", \"$day_value;$time_value\";instead of $day_value use one of these values: \"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\", \"saturday\", \"sunday\";instead of $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\"example: \"tuesday;18\"", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleAdsSearchTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsSearchTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAdsSearchTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nin this case, equals null", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nin this case, equals null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nads_search", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AdsSearch" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "AdsSearch": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "advertiser_id": { "type": "string", "description": "unique identifier of the advertiser account", "nullable": true }, "creative_id": { "type": "string", "description": "unique identifier of the advertisement", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "verified": { "type": "boolean", "description": "verified advertiser account\nequals true if advertiser account is verified by Google Ads", "nullable": true }, "format": { "type": "string", "description": "format of the advertisement\npossible values: text, image, video", "nullable": true }, "preview_image": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PreviewImage" } ], "description": "preview image of the advertisement", "nullable": true }, "preview_url": { "type": "string", "description": "url pointing to the ad preview", "nullable": true }, "first_shown": { "type": "string", "description": "date and time when the ad was shown for the first time\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d", "nullable": true }, "last_shown": { "type": "string", "description": "date and time when the ad was shown the last time\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d", "nullable": true } } }, "PreviewImage": { "type": "object", "properties": { "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "height": { "type": "integer", "description": "height of the preview image", "nullable": true }, "width": { "type": "integer", "description": "width of the preview image", "format": "int64", "nullable": true } } }, "SerpYoutubeVideoInfoTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: video_info", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleOrganicTaskGetRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskGetRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicTaskGetRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskGetRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicTaskGetRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nif there is none, the value is null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nif there are none, the value is null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\nanswer_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\nnote that this array contains all types of search results found in the returned SERP;\nhowever, this endpoint provides data for featured_snippet, organic and paid types only;\nto get all items (including SERP features and rich snippets) found in the returned SERP, please refer to the Google Organi\u0441 Advanced SERP endpoint", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total search results pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpGoogleDatasetInfoLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetInfoLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetInfoLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item type: dataset", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Dataset" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "Dataset": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "dataset_id": { "type": "string", "description": "ID of the dataset", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "image_url": { "type": "string", "description": "URL of the image\nthe URL leading to the image on the original resource or DataForSEO storage (in case the original source is not available)", "nullable": true }, "scholarly_citations_count": { "type": "integer", "description": "count of articles that refer to the dataset", "format": "int64", "nullable": true }, "scholarly_articles_url": { "type": "string", "description": "url of scholarly articles\nlink to the list of scholarly articles on Google Scholar\nexample: https://scholar.google.com/scholar?q=%2210.6084%20m9%20figshare%207427933%20v1%22", "nullable": true }, "unique_identifier": { "type": "string", "description": "digital identifier of an object\nunique digital identifier of the dataset\nexample: https://doi.org/10.5061/dryad.hmgqnk9m3", "nullable": true }, "related_article": { "type": "string", "description": "link to related article\nlink to the published article that is related to the dataset", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LinkElement" } ], "nullable": true }, "description": "sitelinks\nthe links shown below some of Google Dataset\u2019s search results\nif there are none, equals null", "nullable": true }, "dataset_providers": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonLabelElement" } ], "nullable": true }, "description": "the list of institutions that provided the dataset", "nullable": true }, "formats": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/FormatsElement" } ], "nullable": true }, "description": "the list of file formats of the dataset", "nullable": true }, "authors": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AuthorsElement" } ], "nullable": true }, "description": "the list of authors of the dataset", "nullable": true }, "licenses": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AmazonLabelElement" } ], "nullable": true }, "description": "the list of licenses issued to the dataset", "nullable": true }, "updated_date": { "type": "string", "description": "date and time when the result was last updated\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2022-11-27 02:00:00 +00:00", "nullable": true }, "area_covered": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "the list of areas covered in the dataset\nfor example: Africa, Global", "nullable": true }, "period_covered": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PeriodCovered" } ], "description": "period covered in the dataset", "nullable": true }, "dataset_description": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DatasetDescription" } ], "description": "description of the dataset", "nullable": true } } }, "PeriodCovered": { "type": "object", "properties": { "start_date": { "type": "string", "description": "date and time when the period starts\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2020-03-02 02:00:00 +00:00", "nullable": true }, "end_date": { "type": "string", "description": "date and time when the period ends\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2022-12-09 02:00:00 +00:00", "nullable": true }, "displayed_date": { "type": "string", "description": "period displayed in SERP\nexample:\nMar 2, 2020 - Dec 9, 2022", "nullable": true } } }, "FormatsElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "format": { "type": "string", "description": "type of file format of the dataset\nfor example: zip, html, csv", "nullable": true }, "size": { "type": "integer", "description": "file size in bytes", "format": "int64", "nullable": true } } }, "AuthorsElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "name": { "type": "string", "description": "name of the dataset author", "nullable": true }, "url": { "type": "string", "description": "author\u2019s link URL", "nullable": true }, "domain": { "type": "string", "description": "author\u2019s link domain", "nullable": true } } }, "DatasetDescription": { "type": "object", "properties": { "text": { "type": "string", "description": "text of the description", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LinkElement" } ], "nullable": true }, "description": "links featured in the \u2018dataset_description\u2019", "nullable": true } } }, "LinkElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "title": { "type": "string", "description": "title of a given link element", "nullable": true }, "snippet": { "type": "string", "description": "text alongside the link title", "nullable": true }, "description": { "type": "string", "description": "description of the results element", "nullable": true }, "url": { "type": "string", "description": "URL", "nullable": true }, "domain": { "type": "string", "description": "domain where a link points", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true } } }, "SerpGoogleAdsAdvertisersTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpNaverOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpNaverOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpSeznamOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleAutocompleteTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAutocompleteTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAutocompleteTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nin this case, will equal null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nautocomplete", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Autocomplete" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "Autocomplete": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "relevance": { "type": "integer", "description": "relevance of suggested keyword\nrepresents the relevant of the autocomplete suggestion to the target keyword\ncan take values from 500 to 2000\nthe higher the value, the more relevant is the suggestion\nNote: only available for the following client:\nchrome/chrome-omni", "nullable": true }, "suggestion": { "type": "string", "description": "google autocomplete keyword suggestion", "nullable": true }, "suggestion_type": { "type": "string", "description": "google autocomplete suggestion type\nNote: only available for the following client:\nchrome/chrome-omni", "nullable": true }, "search_query_url": { "type": "string", "description": "url to search results\nurl to search results relevant to the google autocomplete suggestion", "nullable": true }, "thumbnail_url": { "type": "string", "description": "url of the thumbnail image\nurl of the thumbnail image of the google autocomplete suggestion\nNote: only available for the following client:\ngws-wiz\ngws-wiz-serp", "nullable": true }, "highlighted": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "keywords highlighted in autocomplete\ncontains a list of google autocomplete suggestions that are highlighted in the search bar;\nNote: array is only available for the following client:\ngws-wiz\npsy-ab\ngws-wiz-local", "nullable": true } } }, "SerpYoutubeOrganicLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeOrganicLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeOrganicLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nyoutube_channel, youtube_video, youtube_video_paid, youtube_playlist", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiYoutubeOrganicElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "BaseSerpApiYoutubeOrganicElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP for the target domain\nabsolute position among all the elements in SERP", "nullable": true }, "block_rank": { "type": "integer", "description": "block rank in SERP\nposition among all the blocks in SERP", "nullable": true }, "block_name": { "type": "string", "description": "name of the block in SERP\nexample:\n\"People also watched\"", "nullable": true }, "channel_id": { "type": "string", "description": "ID of the channel", "nullable": true }, "url": { "type": "string", "description": "URL of the channel", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "youtube_channel": "#/components/schemas/SerpApiYoutubeChannelElementItem", "youtube_video": "#/components/schemas/SerpApiYoutubeVideoElementItem", "youtube_video_paid": "#/components/schemas/SerpApiYoutubeVideoPaidElementItem", "youtube_playlist": "#/components/schemas/SerpApiYoutubePlaylistElementItem" } } }, "SerpGoogleJobsTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleJobsTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpBingOrganicTaskGetRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskGetRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicTaskGetRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskGetRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicTaskGetRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types: organic, paid", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseBingSerpApiElementItem" } ], "nullable": true }, "description": "items inside the element\narray of 8 search queries related to the keyword", "nullable": true } } }, "SerpGoogleFinanceTickerSearchTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible item types: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceTickerSearchElementItem" } ], "nullable": true }, "description": "items of search results found in SERP\narray of items containing market indexes data;\npossible type of items: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument", "nullable": true } } }, "BaseSerpApiGoogleFinanceTickerSearchElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "identifier": { "type": "string", "description": "identifier of the element\nfull identifier of the element that consists from ticker and market_identifier\nexample: PX1:INDEXDB", "nullable": true }, "displayed_name": { "type": "string", "description": "name of the market index as displayed on Google Finance\nexample: CAC 40", "nullable": true }, "url": { "type": "string", "description": "URL to the page of the market index on Google Finance", "nullable": true }, "location": { "type": "string", "description": "location of the market index\nexample: Europe/Paris", "nullable": true }, "trend": { "type": "string", "description": "growth trend of the market index\npossible values: up, down, stable", "nullable": true }, "timestamp": { "type": "string", "description": "date and time of the value readout\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2025-02-10 09:40:00 +00:00", "nullable": true }, "percentage_delta": { "type": "number", "description": "percentage of change in value of the market index", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "google_finance_asset_pair": "#/components/schemas/SerpApiGoogleFinanceAssetPairElementItem", "google_finance_market_instrument": "#/components/schemas/SerpApiGoogleFinanceMarketInstrumentElementItem", "google_finance_market_index": "#/components/schemas/SerpApiGoogleFinanceMarketIndexElementItem" } } }, "SerpBingLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "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 \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "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", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D", "nullable": true }, "block_depth": { "type": "integer", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "audi" } ] }, "SerpGoogleImagesLiveHtmlRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;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 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 100max value: 700Your 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;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.", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleJobsTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleJobsTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleJobsTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nin this case, equals null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\ngoogle_jobs_item", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GoogleJobsItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "GoogleJobsItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "job_id": { "type": "string", "description": "ID of the job on Google Jobs", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "employer_name": { "type": "string", "description": "name of the employer", "nullable": true }, "employer_url": { "type": "string", "description": "URL to the employer\u2019s website", "nullable": true }, "employer_image_url": { "type": "string", "description": "URL to the image used in the job posting", "nullable": true }, "location": { "type": "string", "description": "location for which the job vacancy is posted", "nullable": true }, "source_name": { "type": "string", "description": "original source of the job vacancy", "nullable": true }, "source_url": { "type": "string", "description": "URL to the original source of the job vacancy", "nullable": true }, "salary": { "type": "string", "description": "the salary indicated in the job vacancy\nif the salary isn\u2019t indicated, this field will equal null", "nullable": true }, "contract_type": { "type": "string", "description": "employment contract type", "nullable": true }, "timestamp": { "type": "string", "description": "date and time when the result was published\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "time_ago": { "type": "string", "description": "indicates how long ago the job vacancy was posted", "nullable": true }, "rectangle": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeRectangleInfo" } ], "description": "rectangle parameters\ncontains cartesian coordinates and pixel dimensions of the result\u2019s snippet in SERP;\nin this case, will equal null", "nullable": true } } }, "SerpGoogleNewsLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleNewsLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleAiModeLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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/locationsNote: check Google Search Help for the list of countries where AI Mode is currently available", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired 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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/ai_mode/languages", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "location_name": { "type": "string", "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/locationsNote: check Google Search Help for the list of countries where AI Mode is currently available", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired 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;", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate 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 falseNote: if set to true, the charge per task will be multiplied by 2", "nullable": true }, "browser_screen_width": { "type": "integer", "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", "nullable": true }, "browser_screen_height": { "type": "integer", "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", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "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", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 9z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 4zthe maximum value for \"zoom\": 18zexample:52.6178549,-155.352142,18z", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "what is google ai mode" } ] }, "SerpGoogleEventsLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleEventsLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleEventsLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code\nin this case, the value will be null", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\npossible item types:\nevent_item", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP\nin this case, the value will be 0\nthis search engine does not indicate the total number of results", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/EventItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "EventItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "description": { "type": "string", "description": "description of the results element in SERP", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "image_url": { "type": "string", "description": "URL of the image featured in the element", "nullable": true }, "event_dates": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/EventDates" } ], "description": "dates when the event takes place\nif there are none, equals null", "nullable": true }, "location_info": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LocationInfo" } ], "description": "information about the event\u2019s venue", "nullable": true }, "information_and_tickets": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeLinkElementInfo" } ], "nullable": true }, "description": "additional information and ticket purchase options", "nullable": true } } }, "LocationInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "name of the event\u2019s venue", "nullable": true }, "address": { "type": "string", "description": "address of the event\u2019s venue", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "cid": { "type": "string", "description": "google-defined client id\ncan be used with Google Reviews API to get a full list of reviews", "nullable": true }, "feature_id": { "type": "string", "description": "the unique identifier of the element in SERP", "nullable": true } } }, "EventDates": { "type": "object", "properties": { "start_datetime": { "type": "string", "description": "date and time when the event starts\nif time zone is specified in the event, value will be returned in the UTC format:\n\u201cyyyy-mm-ddThh-mm-ss+00:00\u201d\nexample:\n2019-11-15T12:57:46+00:00\nif time zone is not specified in the event, unspecified local time will be returned in the following format:\n\u201cyyyy-mm-ddThh-mm-ss\u201d\nexample:\n2019-11-15T12:57:46", "nullable": true }, "end_datetime": { "type": "string", "description": "date and time when the event ends\nif time zone is specified in the event, value will be returned in the UTC format:\n\u201cyyyy-mm-ddThh-mm-ss+00:00\u201d\nexample:\n2019-11-15T12:57:46+00:00\nif time zone is not specified in the event, unspecified local time will be returned in the following format:\n\u201cyyyy-mm-ddThh-mm-ss\u201d\nexample:\n2019-11-15T12:57:46", "nullable": true }, "displayed_dates": { "type": "string", "description": "date or date range as it is displayed in SERP", "nullable": true } } }, "AiModeLinkElementInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "description": { "type": "string", "description": "link description", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "domain": { "type": "string", "description": "domain in SERP", "nullable": true } } }, "SerpGoogleFinanceTickerSearchLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceTickerSearchLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceTickerSearchLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible item types: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceTickerSearchElementItem" } ], "nullable": true }, "description": "items of search results found in SERP\narray of items containing market indexes data;\npossible type of items: google_finance_market_index, google_finance_asset_pair, google_finance_market_instrument", "nullable": true } } }, "SerpYoutubeVideoCommentsLiveAdvancedRequestInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video\nrequired field\nyou can find video ID in the URL or \u2018youtube_video\u2019 item of YouTube Organic result\nexample:\nvQXvyV0zIP4" }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don\u2019t specify location_code\nif you use this field, you don\u2019t 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", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\u00a0\nif you use this field, you don\u2019t 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", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t 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", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nonly value: desktop", "nullable": true }, "os": { "type": "string", "description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows", "nullable": true }, "depth": { "type": "integer", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "video_id": "vQXvyV0zIP4" } ] }, "SerpYoutubeVideoCommentsLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsLiveAdvancedResultInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_comment", "nullable": true }, "title": { "type": "string", "description": "title of the video", "nullable": true }, "comments_count": { "type": "integer", "description": "number of comments on the video", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/YoutubeComment" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleMapsLiveAdvancedRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;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 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 100max value: 700Your 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.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktopnote: for mobile device, only 20 results are returned for every SERP", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://google.com/maps/search/pizza/@37.09024,-95.712891,4z", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 17z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 3zthe maximum value for \"zoom\": 21zexample:52.6178549,-155.352142,20z", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true }, "search_this_area": { "type": "boolean", "description": "show results from the displayed areaoptional fieldcan take the values:true, falsedefault value: trueif set to false, the search_this_area mode will be turned offNote: if the search_this_area mode is turned off, Google Maps listings might contain results beyond the displayed area", "nullable": true }, "search_places": { "type": "boolean", "description": "search places modeoptional fieldthe 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 false;default value: trueNote: if the search_places mode is turned off and no results were found in the search area, the results array will be empty", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpYoutubeVideoSubtitlesTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: video_subtitles", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "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 \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;if this field contains such parameters as \u2018allinanchor:\u2019, \u2018allintext:\u2019, \u2018allintitle:\u2019, \u2018allinurl:\u2019, \u2018define:\u2019, \u2018definition:\u2019, \u2018filetype:\u2019, \u2018id:\u2019, \u2018inanchor:\u2019, \u2018info:\u2019, \u2018intext:\u2019, \u2018intitle:\u2019, \u2018inurl:\u2019, \u2018link:\u2019, \u2018site:\u2019, the charge per task will be multiplied by 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "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.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "load_async_ai_overview": { "type": "boolean", "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: falseNote: you will be charged extra $0.002 for using this parameter;if the element is absent or contains \"asynchronous_ai_overview\": false, all extra charges will be returned to your account balance", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match typerequired field if stop_crawl_on_match is specifiedtype of match for the match_valuepossible values:domain \u2013 specific domain or subdomainwith_subdomains \u2013 main domain and subdomainswildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "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-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "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", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "remove_from_url": { "type": "array", "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", "nullable": true }, "people_also_ask_click_depth": { "type": "integer", "description": "clicks on the corresponding elementoptional fieldspecify the click depth on the people_also_ask element to get additional people_also_ask_element items;Note your account will be billed $0.00015 extra for each click;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", "nullable": true }, "group_organic_results": { "type": "boolean", "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", "nullable": true }, "calculate_rectangles": { "type": "boolean", "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;Note: you will be charged extra $0.002 for using this parameter", "nullable": true }, "browser_screen_width": { "type": "integer", "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", "nullable": true }, "browser_screen_height": { "type": "integer", "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", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "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", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationoptional field if you specify location_name\u00a0or 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", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true }, "target": { "type": "string", "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 (\u2018*\u2019) 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", "nullable": true }, "target_search_mode": { "type": "string", "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 \u2013 the crawl stops only when all specified targets are foundany \u2013 the crawl stops when any single target is founddefault value: anylearn more about this parameter on our Help Center", "nullable": true }, "find_targets_in": { "type": "array", "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", "nullable": true }, "ignore_targets_in": { "type": "array", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein", "calculate_rectangles": true } ] }, "SerpGoogleEventsTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleEventsTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleEventsTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: events", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleSearchByImageTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleSearchByImageTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleAutocompleteTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAutocompleteTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleAiModeTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: ai_mode", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYahooOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYoutubeVideoSubtitlesTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTaskGetAdvancedResultInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_subtitles", "nullable": true }, "unsupported_language": { "type": "boolean", "description": "indicates whether the language is unsupported by the system", "nullable": true }, "translate_language": { "type": "string", "description": "language code of translated text", "nullable": true }, "origin_language": { "type": "string", "description": "language code of original text", "nullable": true }, "category": { "type": "string", "description": "the category the video belongs to\nNote: this field is deprecated and always returns null", "nullable": true }, "subtitles_count": { "type": "integer", "description": "number of subtitles in the video", "format": "int64", "nullable": true }, "title": { "type": "string", "description": "title of the video", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/YoutubeSubtitles" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "YoutubeSubtitles": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP for the target domain\nabsolute position among all the elements in SERP", "nullable": true }, "text": { "type": "string", "description": "text translated in subtitles", "nullable": true }, "start_time": { "type": "number", "description": "the second subtitled text starts", "nullable": true }, "end_time": { "type": "number", "description": "the second subtitled text ends", "nullable": true }, "duration_time": { "type": "number", "description": "duration of subtitles in seconds", "nullable": true } } }, "SerpSeznamOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nimages, local_pack, organic, related_searches, top_stories, featured_snippet, video, shopping", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "SerpGoogleFinanceMarketsTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleDatasetInfoTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item type: dataset", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Dataset" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpYoutubeVideoInfoTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: video_info", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYoutubeVideoCommentsTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: video_comments", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYahooLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpAiSummaryRequestInfo": { "type": "object", "properties": { "task_id": { "type": "string", "description": "task identifier\nrequired field\nunique identifier of the associated task in the UUID format\nyou will be able to use it within 30 days to request the results of the task at any time" }, "prompt": { "type": "string", "description": "AI prompt\noptional field\nadditional task for AI summariser;\nany form of text, question or information that communicates to AI what response you\u2019re looking for;\nmax number of symbols or characters you can specify: 2000;\nnote: your prompt has to be relevant to the keyword specified in the POST request to SERP API", "nullable": true }, "support_extra": { "type": "boolean", "description": "support extra SERP features\noptional field\nif set to true, the AI model will consider the following extra SERP features, in addition to organic results: answer_box, knowledge_graph, featured_snippet;\ndefault value: true", "nullable": true }, "fetch_content": { "type": "boolean", "description": "fetch content from pages in SERPs\noptional field\nif 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;\ndefault value: false", "nullable": true }, "include_links": { "type": "boolean", "description": "include source links in the summary\noptional field\nif set to true, the summary field in the API response will contain links to sources of the generated summary;\ndefault value: false", "nullable": true } }, "example": [ { "task_id": "07031739-1535-0139-0000-9d1e639a5b7d", "prompt": "explain what DataForSEO is", "include_links": true, "fetch_content": true } ] }, "SerpYahooOrganicTaskPostRequestInfo": { "type": "object", "properties": { "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8", "nullable": true }, "keyword": { "type": "string", "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don\u2019t specify location_code or location_coordinate\nif you use this field, you don\u2019t need to specify location_code or location_coordinate\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/yahoo/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\u00a0or location_coordinate\nif you use this field, you don\u2019t need to specify location_name or location_coordinate\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/yahoo/locations\nexample:\n2840", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or location_code\nif you use this field, you don\u2019t need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \u201clatitude,longitude,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9 (mm)\nthe maximum value for \u201cradius\u201d: 199999 (mm)\nexample:\n53.476225,-2.243572,200", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t 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/yahoo/languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/yahoo/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically according to the location and language you specify\nhowever, you can set a custom search engine domain in this field\nexample:\nau.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 6\nmax value: 700\nYour account will be billed per each SERP;\nEach Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "postback_url": { "type": "string", "description": "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible values:\nregular, html", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleFinanceMarketsLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleDatasetSearchLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetSearchLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetSearchLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item type: dataset", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Dataset" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "SerpGoogleAiModeLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine resultsyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;in this case, the value will be null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chipsin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERPcontains types of search results (items) found in SERP.possible item types:ai_overview", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeAiOverviewInfo" } ], "nullable": true }, "description": "items present in the element", "nullable": true } } }, "AiModeAiOverviewInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "description": "group rank in SERPposition within a group of elements with identical type valuespositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERPabsolute position among all the elements in SERP", "nullable": true }, "page": { "type": "integer", "description": "SERP pageSERP page on which the element ranks", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERPcan take the following values:left, right", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatthe text of the ai_overview formatted in the markdown markup language", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiAiModeAiOverviewElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true }, "references": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeAiOverviewReferenceInfo" } ], "nullable": true }, "description": "additional references relevant to the itemincludes references to webpages that may have been used to generate the ai_overview", "nullable": true }, "rectangle": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeRectangleInfo" } ], "description": "rectangle parameterscontains cartesian coordinates and pixel dimensions of the result's snippet in SERPequals null if calculate_rectangles in the POST request is not set to true", "nullable": true } } }, "AiModeAiOverviewReferenceInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERP\ncan take the following values:\nleft, right", "nullable": true }, "source": { "type": "string", "description": "reference source name or title", "nullable": true }, "domain": { "type": "string", "description": "domain in SERP", "nullable": true }, "url": { "type": "string", "description": "image source URL", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "text": { "type": "string", "description": "text of the component", "nullable": true } } }, "BaseSerpApiAiModeAiOverviewElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "position": { "type": "string", "description": "the alignment of the element in SERPcan take the following values:left, right", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "ai_overview_element": "#/components/schemas/SerpApiAiModeAiOverviewElementItem", "ai_overview_expanded_element": "#/components/schemas/SerpApiAiModeAiOverviewExpandedElementItem", "ai_overview_video_element": "#/components/schemas/SerpApiAiModeAiOverviewVideoElementItem", "ai_overview_table_element": "#/components/schemas/SerpApiAiModeAiOverviewTableElementItem", "ai_overview_shopping": "#/components/schemas/SerpApiAiModeAiOverviewShoppingItem" } } }, "SerpGoogleImagesTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleImagesTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: images", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceExploreTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible 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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceElementItem" } ], "nullable": true }, "description": "market indexes related to the market trends element\npossible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element", "nullable": true } } }, "BaseSerpApiGoogleFinanceElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "google_finance_asset_pair_element": "#/components/schemas/SerpApiGoogleFinanceAssetPairElementElementItem", "google_finance_market_index_element": "#/components/schemas/SerpApiGoogleFinanceMarketIndexElementElementItem", "google_finance_market_instrument_element": "#/components/schemas/SerpApiGoogleFinanceMarketInstrumentElementElementItem", "google_finance_hero_groups": "#/components/schemas/SerpApiGoogleFinanceHeroGroupsElementItem", "google_finance_interested": "#/components/schemas/SerpApiGoogleFinanceInterestedElementItem", "google_finance_news": "#/components/schemas/SerpApiGoogleFinanceNewsElementItem", "google_finance_earnings_calendar": "#/components/schemas/SerpApiGoogleFinanceEarningsCalendarElementItem", "google_finance_most_followed": "#/components/schemas/SerpApiGoogleFinanceMostFollowedElementItem", "google_finance_market_trends": "#/components/schemas/SerpApiGoogleFinanceMarketTrendsElementItem", "google_finance_people_also_search": "#/components/schemas/SerpApiGoogleFinancePeopleAlsoSearchElementItem", "google_finance_explore_market_trends": "#/components/schemas/SerpApiGoogleFinanceExploreMarketTrendsElementItem", "google_finance_quote": "#/components/schemas/SerpApiGoogleFinanceQuoteElementItem", "google_finance_compare_to": "#/components/schemas/SerpApiGoogleFinanceCompareToElementItem", "google_finance_financial": "#/components/schemas/SerpApiGoogleFinanceFinancialElementItem", "google_finance_futures_chain": "#/components/schemas/SerpApiGoogleFinanceFuturesChainElementItem", "google_finance_details": "#/components/schemas/SerpApiGoogleFinanceDetailsElementItem", "google_finance_about": "#/components/schemas/SerpApiGoogleFinanceAboutElementItem" } } }, "SerpGoogleFinanceExploreLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceExploreLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceExploreLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleJobsTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleJobsTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleJobsTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: jobs", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleMapsTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;if this field contains such parameters as \u2018allinanchor:\u2019, \u2018allintext:\u2019, \u2018allintitle:\u2019, \u2018allinurl:\u2019, \u2018define:\u2019, \u2018filetype:\u2019, \u2018id:\u2019, \u2018inanchor:\u2019, \u2018info:\u2019, \u2018intext:\u2019, \u2018intitle:\u2019, \u2018inurl:\u2019, \u2018link:\u2019, \u2018related:\u2019, \u2018site:\u2019, the charge per task will be multiplied by 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 100max value: 700Your 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.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktopnote: for mobile device, only 20 results are returned for every SERP", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://google.com/maps/search/pizza/@37.09024,-95.712891,4z", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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,zoom\" formatif \"zoom\" is not specified, 17z will be applied as a default valuethe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"zoom\": 3zthe maximum value for \"zoom\": 21zexample:52.6178549,-155.352142,20z", "nullable": true }, "se_domain": { "type": "string", "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", "nullable": true }, "search_this_area": { "type": "boolean", "description": "show results from the displayed areaoptional fieldcan take the values:true, falsedefault value: trueif set to false, the search_this_area mode will be turned offNote: if the search_this_area mode is turned off, Google Maps listings might contain results beyond the displayed area", "nullable": true }, "search_places": { "type": "boolean", "description": "search places modeoptional fieldthe 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 false;default value: trueNote: if the search_places mode is turned off and no results were found in the search area, the results array will be empty", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleMapsLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleMapsLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleMapsLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided exact results\nNote: to check location-specific results, follow the provided check url, scroll up and down, then click the \u201cSearch this area\u201d button", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nmaps_search, maps_paid_item", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleMapsElementItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "BaseSerpApiGoogleMapsElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "domain": { "type": "string", "description": "domain in SERP", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "url": { "type": "string", "description": "search URL with refinement parameters", "nullable": true }, "rating": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RatingInfo" } ], "description": "the element\u2019s rating \nthe popularity rate based on reviews and displayed in SERP", "nullable": true }, "rating_distribution": { "type": "object", "additionalProperties": { "type": "integer", "format": "Int64", "nullable": true }, "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", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "maps_search": "#/components/schemas/SerpApiMapsSearchElementItem", "maps_paid_item": "#/components/schemas/SerpApiMapsPaidItemElementItem" } } }, "SerpIdListRequestInfo": { "type": "object", "properties": { "datetime_from": { "type": "string", "description": "start time for filtering results\nrequired field\nif include_metadata is set to true, minimum start value: a month from current datetime;\nif include_metadata is set to false, minimum start value: six months from current datetime;\nmaximum start value: current datetime;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d;\nexample:\n2023-01-15 12:57:46 +00:00" }, "datetime_to": { "type": "string", "description": "finish time for filtering results\nrequired field\nif include_metadata is set to true, minimum finish value: a month from current datetime;\nif include_metadata is set to false, minimum finish value: six months from current datetime;\nmaximum finish value: current datetime;\nNote: datetime_to must be greater than datetime_from;\nmust be specified in the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d;\nexample:\n2023-01-31 13:57:46 +00:00" }, "limit": { "type": "integer", "description": "the maximum number of returned task IDs\noptional field\ndefault value: 1000\nmaximum value: 1000\nminimum value: 1", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of returned task IDs\noptional field\nif you specify the 10 value, the first ten tasks in the results array will be omitted;\nminimum and default value: 0;\nmaximum value: 100M (100 million)", "nullable": true }, "sort": { "type": "string", "description": "sorting by task execution time\noptional field\npossible values: \"asc\", \"desc\"\ndefault value: \"asc\"", "nullable": true }, "include_metadata": { "type": "boolean", "description": "include task metadata in the response\noptional field\nif set to true, the metadata object containing parameters specified in the POST request will be provided in the response;\ndefault value: false", "nullable": true } }, "example": [ { "datetime_from": "2026-04-12 04:39:39 +00:00", "datetime_to": "2026-04-14 04:39:39 +00:00", "limit": 100, "offset": 0, "sort": "desc", "include_metadata": true } ] }, "SerpGoogleFinanceQuoteTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible 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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceElementItem" } ], "nullable": true }, "description": "market indexes related to the market trends element", "nullable": true } } }, "SerpGoogleFinanceQuoteTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "ticker or stock symbolrequired fieldin 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 keyword field;all %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:: advanced, html", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "window": { "type": "string", "description": "time window for google_finance_quote graphoptional fieldpossible values: 1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAXdefault value: 1DNote: if you specify a value that is different from 1D, the charge per task will be multiplied by 2", "nullable": true } }, "example": [ { "keyword": ".DJI:INDEXDJX", "location_code": 2840, "language_name": "English" } ] }, "SerpGoogleFinanceTickerSearchTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "company or financial instrument namerequired fieldin 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 keyword field;all %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:: advanced, html", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "category": { "type": "string", "description": "category of financial instruments to search foroptional fieldpossible values: all, stock, index, mutual_fund, currency, futuresdefault value: all", "nullable": true } }, "example": [ { "language_name": "English", "location_code": 2840, "category": "all", "keyword": "DJ", "priority": 2 } ] }, "SerpScreenshotResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpScreenshotTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpScreenshotTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpScreenshotResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpScreenshotResultInfo": { "type": "object", "properties": { "items_count": { "type": "integer", "description": "number of items in the results array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ScreenshotItem" } ], "nullable": true }, "description": "items array", "nullable": true } } }, "ScreenshotItem": { "type": "object", "properties": { "image": { "type": "string", "description": "screenshot of the requested page\nURL of the page screenshot on the DataForSEO storage\nnote: the page screenshot saved on the DataForSEO storage only remains accessible for one day after making the request", "nullable": true } } }, "SerpGoogleAutocompleteTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAutocompleteTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAutocompleteTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: autocomplete", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleEventsTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleEventsTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleEventsTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: events", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpBingLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpGoogleLocalFinderTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocalFinderTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpBaiduOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleNewsTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpYahooOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpSeznamLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpBingOrganicLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleFinanceQuoteLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible 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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceElementItem" } ], "nullable": true }, "description": "market indexes related to the market trends element", "nullable": true } } }, "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", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0\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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nonly value: desktop", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "subtitles_language": { "type": "string", "description": "language code of original text\nyou can get the language code from YouTube Video Info result", "nullable": true }, "subtitles_translate_language": { "type": "string", "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\"", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "video_id": "Y8Wu4rSNJms" } ] }, "SerpGoogleMapsTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleMapsTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleMapsTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: maps", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYahooLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpYoutubeLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpYahooOrganicLiveRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicLiveRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicLiveRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicLiveRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicLiveRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nYou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\nfeatured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview;\nnote that this array contains all types of search results found in the returned SERP;\nhowever, this endpoint provides data for organic, paid, and featured_snippet types only;\nto get all items (including SERP features and rich snippets) found in the returned SERP, please refer to the Yahoo Organi\u0441 Advanced SERP endpoint", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpYahooOrganicLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYahooOrganicLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nfeatured_snippet, images, local_pack, hotels_pack, organic, paid, people_also_ask, related_searches, shopping, recipes, top_stories, video, ai_overview", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "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", "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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nonly value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "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", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "subtitles_language": { "type": "string", "description": "language code of original text\nyou can get the language code from YouTube Video Info result", "nullable": true }, "subtitles_translate_language": { "type": "string", "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\"", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "video_id": "Y8Wu4rSNJms" } ] }, "SerpGoogleNewsTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleNewsTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: news", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpBingOrganicLiveAdvancedRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0or location_coordinate\nif you use this field, you don't need to specify location_name or location_coordinate\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/bing/locations\nexample:\n2840", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/bing/languages\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10\nmax value: 200\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don't specify location_code or location_coordinate\nif you use this field, you don't need to specify location_code or location_coordinate\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/bing/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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/bing/languages\nexample:\nEnglish", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "target": { "type": "string", "description": "target domain, subdomain, or webpage to get results for\noptional field\na domain or a subdomain should be specified without https:// and www.\nnote that the results of target-specific tasks will only include SERP elements that contain a url string;\nyou can also use a wildcard (\u2018*\u2019) character to specify the search pattern in SERP and narrow down the results;\nexamples:\nexample.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/;\nexample.com* - returns results for the domain, including all its pages;\n*example.com* - returns results for the entire domain, including all its pages and subdomains;\n*example.com - returns results for the home page regardless of the subdomain, such as https://en.example.com;\nexample.com/example-page - returns results for the exact URL;\nexample.com/example-page* - returns results for all domain's URLs that start with the specified string", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate pixel rankings for SERP elements in advanced results\noptional field\npixel ranking refers to the distance between the result snippet and top left corner of the screen;\nVisit Help Center to learn more>>\nby default, the parameter is set to false\nNote: you will be charged extra $0.002 for using this parameter", "nullable": true }, "browser_screen_width": { "type": "integer", "description": "browser screen width\noptional field\nyou can set a custom browser screen width to calculate pixel rankings for a particular device;\ncan be specified within the following range: 240-9999;\nby default, the parameter is set to:\n1920 for desktop;\n360 for mobile on android;\n375 for mobile on iOS;\nNote: to use this parameter, set calculate_rectangles to true", "format": "int64", "nullable": true }, "browser_screen_height": { "type": "integer", "description": "browser screen height\noptional field\nyou can set a custom browser screen height to calculate pixel rankings for a particular device;\ncan be specified within the following range: 240-9999;\nby default, the parameter is set to:\n1080 for desktop;\n640 for mobile on android;\n812 for mobile on iOS;\nNote: to use this parameter, set calculate_rectangles to true", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "description": "browser screen resolution ratio\noptional field\nyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;\ncan be specified within the following range: 0.5-3;\nby default, the parameter is set to:\n1 for desktop;\n3 for mobile on android;\n3 for mobile on iOS;\nNote: to use this parameter, set calculate_rectangles to true", "nullable": true }, "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don't specify location_name\u00a0or location_code\nif you use this field, you don't need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \"latitude,longitude\" format\nthe maximum number of decimal digits for \"latitude\" and \"longitude\": 7\nexample:\n53.476225,-2.243572", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "flight ticket new york san francisco" } ] }, "SerpIdListResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpIdListTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpIdListTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpIdListResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpIdListResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "id of the task", "nullable": true }, "url": { "type": "string", "description": "URL of the task\nURL you used for making an API call", "nullable": true }, "datetime_posted": { "type": "string", "description": "date and time when the task was made\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-15 12:57:46 +00:00", "nullable": true }, "datetime_done": { "type": "string", "description": "date and time when the task was completed\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2023-01-15 12:57:46 +00:00", "nullable": true }, "status": { "type": "string", "description": "informational message of the task\nyou can find the full list of general informational messages here", "nullable": true }, "cost": { "type": "number", "description": "cost of the task, USD", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "object", "nullable": true }, "description": "contains parameters you specified in the POST request", "nullable": true } } }, "SerpGoogleOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleMapsTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleMapsTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpBingOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpNaverOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpNaverOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpNaverOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceMarketsLiveHtmlRequestInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldpossible value: desktop", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "market_type": { "type": "string", "description": "type of google finance marketoptional fieldpossible values: most-active, indexes, indexes/americas, indexes/europe-middle-east-africa, indexes/asia-pacific, gainers, losers, climate-leaders, cryptocurrencies, currenciesdefault value: most-active", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840 } ] }, "SerpGoogleOrganicTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: organic", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleImagesTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpYahooOrganicLiveAdvancedRequestInfo": { "type": "object", "properties": { "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8", "nullable": true }, "keyword": { "type": "string", "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn 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\nrequired field if you don\u2019t specify location_code or location_coordinate\nif you use this field, you don\u2019t need to specify location_code or location_coordinate\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/yahoo/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\u00a0or location_coordinate\nif you use this field, you don\u2019t need to specify location_name or location_coordinate\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/yahoo/locations\nexample:\n2840", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or location_code\nif you use this field, you don\u2019t need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \u201clatitude,longitude,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9 (mm)\nthe maximum value for \u201cradius\u201d: 199999 (mm)\nexample:\n53.476225,-2.243572,200", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t 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/yahoo/languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/yahoo/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically according to the location and language you specify\nhowever, you can set a custom search engine domain in this field\nexample:\nau.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 6\nmax value: 700\nYour account will be billed per each SERP;\nEach Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "target": { "type": "string", "description": "target domain, subdomain, or webpage to get results for\noptional field\na domain or a subdomain should be specified without https:// and www.\nnote that the results of target-specific tasks will only include SERP elements that contain a url string;\nyou can also use a wildcard (\u2018*\u2019) character to specify the search pattern in SERP and narrow down the results;\nexamples:\nexample.com \u2013 returns results for the website\u2019s home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;\nexample.com* \u2013 returns results for the domain, including all its pages;\n*example.com* \u2013 returns results for the entire domain, including all its pages and subdomains;\n*example.com \u2013 returns results for the home page regardless of the subdomain, such as https://en.example.com;\nexample.com/example-page \u2013 returns results for the exact URL;\nexample.com/example-page* \u2013 returns results for all domain\u2019s URLs that start with the specified string", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleJobsTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleJobsTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleJobsTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleNewsTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleNewsTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleAiModeLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "SerpGoogleDatasetSearchTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: dataset_search", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceTickerSearchLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "company or financial instrument namerequired fieldin 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 keyword field;all %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "category": { "type": "string", "description": "category of financial instruments to search foroptional fieldpossible values: all, stock, index, mutual_fund, currency, futuresdefault value: all", "nullable": true } }, "example": [ { "language_name": "English", "location_code": 2840, "category": "all", "keyword": "DJ" } ] }, "SerpGoogleEventsTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleEventsTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleEventsTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleEventsTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code\nin this case, the value will be null", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\npossible item types:\nevent_item", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP\nin this case, the value will be 0\nthis search engine does not indicate the total number of results", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/EventItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "SerpYoutubeVideoSubtitlesLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesLiveAdvancedResultInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_subtitles", "nullable": true }, "unsupported_language": { "type": "boolean", "description": "indicates whether the language is unsupported by the system", "nullable": true }, "translate_language": { "type": "string", "description": "language code of translated text", "nullable": true }, "origin_language": { "type": "string", "description": "language code of original text", "nullable": true }, "category": { "type": "string", "description": "the category the video belongs to\nNote: this field is deprecated and always returns null", "nullable": true }, "subtitles_count": { "type": "integer", "description": "number of subtitles in the video", "format": "int64", "nullable": true }, "title": { "type": "string", "description": "title of the video", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/YoutubeSubtitles" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleImagesTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleImagesTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleImagesTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;if this field contains such parameters as \u2018allinanchor:\u2019, \u2018allintext:\u2019, \u2018allintitle:\u2019, \u2018allinurl:\u2019, \u2018define:\u2019, \u2018filetype:\u2019, \u2018id:\u2019, \u2018inanchor:\u2019, \u2018info:\u2019, \u2018intext:\u2019, \u2018intitle:\u2019, \u2018inurl:\u2019, \u2018link:\u2019, \u2018related:\u2019, \u2018site:\u2019, the charge per task will be multiplied by 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation errorlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 100max value: 700Your 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;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.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced, html", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpYahooOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYahooOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYahooOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleAdsSearchTaskPostRequestInfo": { "type": "object", "properties": { "advertiser_ids": { "type": "array", "items": { "type": "string" }, "description": "advertiser identifiersrequired field if target is not specifiedyou can specify the maximum of 25 values in this array;advertiser_ids values for this parameter can be found in the Google Ads Advertisers endpoint;", "nullable": true }, "target": { "type": "string", "description": "domain namerequired field if advertiser_ids is not specifieddomain name associated with an advertiser account", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location codeoptional fieldif 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/ads_search/locationsexample:2840Note: if you don't specify location_name, location_code, or location_coordinate, the ads will be searched across all the available locations", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 40max value: 700Your 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.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine locationoptional fieldif 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/ads_search/locationsexample:London,England,United KingdomNote: if you don't specify location_name, location_code, or location_coordinate, the ads will be searched across all the available locations", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationoptional fieldif you use this field, you don't need to specify location_name or location_codeexample:52.6178549,-155.352142Note: if you don't specify location_name, location_code, or location_coordinate, the ads will be searched across all the available locations", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "platform": { "type": "string", "description": "advertising platformoptional fieldpossible values: all, google_play, google_maps, google_search, google_shopping, youtubedefault value: all", "nullable": true }, "format": { "type": "string", "description": "ad formatoptional fieldpossible values: all, text, image, video", "nullable": true }, "date_from": { "type": "string", "description": "starting date of the time rangeoptional fieldrequired field if date_to is specified; date format: \"yyyy-mm-dd\"minimum value: 2018-05-31maximum value: today's dateexample:\"2020-01-01\"", "nullable": true }, "date_to": { "type": "string", "description": "ending date of the time rangeoptional fieldrequired field if date_from is specified; date format: \"yyyy-mm-dd\"minimum value: 2018-05-31maximum value: today's dateexample:\"2020-01-01\"", "nullable": true } }, "example": [ { "location_code": 2840, "platform": "google_search", "advertiser_ids": [ "AR13752565271262920705", "AR02439908557932462081" ] } ] }, "SerpGoogleEventsTaskPostRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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/events/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "description": "search engine language codeoptional fieldif you use this field, you don't need to specify language_nameby default, language settings correspond to one of the local official languages of the specified locationyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 10max value: 700Your 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;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.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced", "nullable": true }, "location_name": { "type": "string", "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/events/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languageoptional fieldif you use this field, you don't need to specify language_codeby default, language settings correspond to one of the local official languages of the specified locationyou 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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\" formatdata will be provided for the country the specified coordinates belong tothe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"radius\": 199.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "date_range": { "type": "string", "description": "date range to get events foroptional fieldif you do not use this field, we will return all eventspossible values: today, tomorrow, week, weekend, next_week, month, next_month", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domainoptional fieldwe choose the relevant search engine domain automatically according to the location you specifyhowever, you can set a custom search engine domain in this fieldexample:google.co.uk, google.com.au, google.de, etc.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nanswer_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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total search results pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "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 \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0\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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile", "nullable": true }, "block_depth": { "type": "integer", "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 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", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "audi" } ] }, "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", "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", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "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", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nonly value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "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", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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", "nullable": true }, "os": { "type": "string", "description": "device operating system\noptional field\nchoose from the following values: windows, macos\ndefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "video_id": "vQXvyV0zIP4" } ] }, "SerpBaiduLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nonly City location_type is supported for all countries except China (where Country is also supported);\ndon\u2019t 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", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nonly City is supported for all countries except China (where Country is also supported)", "nullable": true } } }, "SerpGoogleAdsAdvertisersLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } }, "SerpGoogleJobsTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleJobsTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleJobsTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleJobsTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: jobs", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleDatasetInfoTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleAutocompleteTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't 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/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_nameif 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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "cursor_pointer": { "type": "integer", "description": "search bar cursor pointeroptional fieldthe 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: 0default value: the number of the last character of the specified keywordexample:|which query are s - \"cursor_pointer\": 0which query is s| - \"cursor_pointer\": 16which que|ry is s - \"cursor_pointer\": 9", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special characters in postback_url will be url-encoded;i.e., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced", "nullable": true }, "client": { "type": "string", "description": "search client for autocompleteoptional fieldautocomplete results may differ depending on the search client;possible values:chrome \u2014 used when google search is opened in google chrome;chrome-omni \u2014 used in the address bar in chrome;gws-wiz \u2014 used in google search home page;gws-wiz-serp \u2014 used in google search engine results page;safari \u2014 used when google search is opened in safari browser;firefox \u2014 used when google search is opened in firefox browser;psy-ab \u2014 may be used when google search is opened in google chrome browser;toolbar \u2014 returns XML;youtube \u2014 returns JSONP;gws-wiz-local \u2014 used in google local;img \u2014 used in google's image search;products-cc \u2014 used in google shopping search", "nullable": true }, "location_name": { "type": "string", "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_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/serp/google/autocomplete/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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_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/serp/google/languagesexample:English", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein", "cursor_pointer": 6 } ] }, "SerpGoogleAiModeTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine resultsyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;in this case, the value will be null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chipsin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERPcontains types of search results (items) found in SERP.possible item types:ai_overview", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeAiOverviewInfo" } ], "nullable": true }, "description": "items present in the element", "nullable": true } } }, "SerpSeznamOrganicTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamOrganicTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamOrganicTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleSearchByImageTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleSearchByImageTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleSearchByImageTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleSearchByImageTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: search_by_image", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleAdsSearchLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsSearchLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAdsSearchLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } }, "SerpGoogleFinanceMarketsTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: finance_markets", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: finance_ticker_search", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceQuoteTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpBingOrganicLiveRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicLiveRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicLiveRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicLiveRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicLiveRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types: organic, paid", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseBingSerpApiElementItem" } ], "nullable": true }, "description": "items inside the element\narray of 8 search queries related to the keyword", "nullable": true } } }, "SerpYoutubeVideoSubtitlesTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoSubtitlesTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoSubtitlesTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpNaverOrganicTaskGetRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskGetRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpNaverOrganicTaskGetRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTaskGetRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpNaverOrganicTaskGetRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\nimages, local_pack, map, organic, paid, related_searches, video\nnote that this array contains all types of search results found in the returned SERP;\nhowever, this endpoint provides data for organic and paid types only\nto get all items (inlcuding SERP features and rich snippets) found in the returned SERP, please refer to the Naver Organi\u0441 Advanced SERP endpoint", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpBingOrganicLiveHtmlRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0or location_coordinate\nif you use this field, you don't need to specify location_name or location_coordinate\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/bing/locations\nexample:\n2840", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/bing/languages\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10\nmax value: 200\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don't specify location_code or location_coordinate\nif you use this field, you don't need to specify location_code or location_coordinate\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/bing/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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/bing/languages\nexample:\nEnglish", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don't specify location_name\u00a0or location_code\nif you use this field, you don't need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \"latitude,longitude\" format\nthe maximum number of decimal digits for \"latitude\" and \"longitude\": 7\nexample:\n53.476225,-2.243572", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpSeznamOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleImagesLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleImagesLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\ncarousel, images_search, related_searches", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleImagesElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "BaseSerpApiGoogleImagesElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP for the target domain\nabsolute position among all the elements in SERP", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "carousel": "#/components/schemas/SerpApiGoogleImagesCarouselElementItem", "images_search": "#/components/schemas/SerpApiGoogleImagesImagesSearchElementItem", "related_searches": "#/components/schemas/SerpApiGoogleImagesRelatedSearchesElementItem" } } }, "SerpGoogleAutocompleteLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't 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/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_nameif 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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "cursor_pointer": { "type": "integer", "description": "search bar cursor pointeroptional fieldthe 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: 0default value: the number of the last character of the specified keywordexample:|which query are s - \"cursor_pointer\": 0which query is s| - \"cursor_pointer\": 16which que|ry is s - \"cursor_pointer\": 9", "nullable": true }, "location_name": { "type": "string", "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_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/serp/google/autocomplete/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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_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/serp/google/languagesexample:English", "nullable": true }, "client": { "type": "string", "description": "search client for autocompleteoptional fieldautocomplete results may differ depending on the search client;possible values:chrome \u2014 used when google search is opened in google chrome;chrome-omni \u2014 used in the address bar in chrome;gws-wiz \u2014 used in google search home page;gws-wiz-serp \u2014 used in google search engine results page;safari \u2014 used when google search is opened in safari browser;firefox \u2014 used when google search is opened in firefox browser;psy-ab \u2014 may be used when google search is opened in google chrome browser;toolbar \u2014 returns XML;youtube \u2014 returns JSONP;gws-wiz-local \u2014 used in google local;img \u2014 used in google's image search;products-cc \u2014 used in google shopping search", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein", "client": "gws-wiz-serp" } ] }, "SerpGoogleDatasetSearchTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item type: dataset", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Dataset" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "SerpGoogleOrganicLiveRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicLiveRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicLiveRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicLiveRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicLiveRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\nanswer_box, app, carousel, multi_carousel, featured_snippet, google_flights, google_reviews, images, jobs, knowledge_graph, local_pack, map, organic, paid, people_also_ask, related_searches, people_also_search, shopping, top_stories, twitter, video, events, mention_carousel, ai_overview\nnote that this array contains all types of search results found in the returned SERP;\nhowever, this endpoint provides data for featured_snippet, organic and paid types only\nto get all items (inlcuding SERP features and rich snippets) found in the returned SERP, please refer to the Google Organi\u0441 Advanced SERP endpoint", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total search results pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpGoogleFinanceMarketsTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible item types: google_finance_hero_groups, google_finance_explore_market_trends, google_finance_news, google_finance_interested, google_finance_people_also_search", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceElementItem" } ], "nullable": true }, "description": "market indexes related to the market trends element\npossible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element", "nullable": true } } }, "SerpGoogleMapsTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleMapsTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleMapsTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleMapsTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided exact results\nNote: to check location-specific results, follow the provided check url, scroll up and down, then click the \u201cSearch this area\u201d button", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nmaps_search, maps_paid_item", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleMapsElementItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "SerpYoutubeVideoInfoLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoInfoLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoInfoLiveAdvancedResultInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_video_info", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/YoutubeVideoInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "YoutubeVideoInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP for the target domain\nabsolute position among all the elements in SERP", "nullable": true }, "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "title": { "type": "string", "description": "title of the video", "nullable": true }, "url": { "type": "string", "description": "URL of the video", "nullable": true }, "thumbnail_url": { "type": "string", "description": "the URL of the page where the thumbnail is hosted", "nullable": true }, "channel_id": { "type": "string", "description": "the ID of the channel where the video is published", "nullable": true }, "channel_name": { "type": "string", "description": "the name of the channel where the video is published", "nullable": true }, "channel_url": { "type": "string", "description": "the URL of the channel where the video is published", "nullable": true }, "channel_logo": { "type": "string", "description": "the URL of the page where the logo image of the channel is hosted", "nullable": true }, "description": { "type": "string", "description": "description of the video", "nullable": true }, "views_count": { "type": "integer", "description": "number of views of the video", "format": "int64", "nullable": true }, "likes_count": { "type": "integer", "description": "number of likes on the video", "format": "int64", "nullable": true }, "comments_count": { "type": "integer", "description": "number of comments on the video", "format": "int64", "nullable": true }, "channel_subscribers_count": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ChannelSubscribersCount" } ], "description": "number of subscribers of the channel", "nullable": true }, "publication_date": { "type": "string", "description": "the date when the video is published", "nullable": true }, "timestamp": { "type": "string", "description": "date and time when the result is published\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2022-11-15 12:57:46 +00:00", "nullable": true }, "keywords": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "keywords relevant to the video", "nullable": true }, "category": { "type": "string", "description": "the category the video belongs to", "nullable": true }, "is_live": { "type": "boolean", "description": "indicates whether the video is on live", "nullable": true }, "is_embeddable": { "type": "boolean", "description": "indicates whether the video is embeddable", "nullable": true }, "duration_time": { "type": "string", "description": "duration of the video", "nullable": true }, "duration_time_seconds": { "type": "integer", "description": "duration of the video in seconds", "nullable": true }, "subtitles": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Subtitles" } ], "nullable": true }, "description": "array of elements describing properties of subtitles in the video", "nullable": true }, "streaming_quality": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/StreamingQualityElement" } ], "nullable": true }, "description": "array of elements that contain information about all possible streaming qualities of the video", "nullable": true } } }, "StreamingQualityElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "label": { "type": "string", "description": "label of the quality element", "nullable": true }, "width": { "type": "integer", "description": "video width in pixels", "format": "int64", "nullable": true }, "height": { "type": "integer", "description": "video height in pixels", "nullable": true }, "bitrate": { "type": "integer", "description": "bit rate of the video", "nullable": true }, "mime_type": { "type": "string", "description": "media type of the video", "nullable": true }, "fps": { "type": "integer", "description": "frame rate of the video", "nullable": true } } }, "ChannelSubscribersCount": { "type": "object", "properties": { "displayed_count": { "type": "string", "description": "displayed subscriber count\nsubscriber count as displayed on YouTube", "nullable": true }, "count": { "type": "integer", "description": "subscriber count", "format": "int64", "nullable": true } } }, "Subtitles": { "type": "object", "properties": { "language": { "type": "string", "description": "language of subtitles", "nullable": true }, "is_translatable": { "type": "boolean", "description": "defines if subtitles are translatable", "nullable": true }, "is_auto_generated": { "type": "boolean", "description": "defines if subtitles are auto generated", "nullable": true } } }, "SerpGoogleNewsTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleNewsTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "includes_non_news_search_results": { "type": "boolean", "description": "indicates whether the response contains non-news search results in addition to news content", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\ntop_stories, news_search", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleNewsElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "BaseSerpApiGoogleNewsElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "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", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERP\nabsolute position among all the elements in SERP", "nullable": true }, "xpath": { "type": "string", "description": "the XPath of the element", "nullable": true }, "title": { "type": "string", "description": "title of the element", "nullable": true }, "rectangle": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiModeRectangleInfo" } ], "description": "rectangle parameters\ncontains cartesian coordinates and pixel dimensions of the result\u2019s snippet in SERP\nequals null if calculate_rectangles in the POST request is not set to true", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "news_search": "#/components/schemas/SerpApiGoogleNewsNewsSearchElementItem", "top_stories": "#/components/schemas/SerpApiGoogleNewsTopStoriesElementItem" } } }, "SerpBaiduOrganicTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduOrganicTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduOrganicTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpGoogleLocalFinderTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocalFinderTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: local_finder", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYoutubeVideoCommentsTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoCommentsTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoCommentsTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpBaiduLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nonly City location_type is supported for all countries except China (where Country is also supported);\ndon\u2019t 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", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nonly City is supported for all countries except China (where Country is also supported)", "nullable": true } } }, "SerpGoogleLocalFinderTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleSearchByImageTaskPostRequestInfo": { "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of the imagerequired fieldthe results will be based on the image you specified in this fieldexample:https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:advanced, html", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calculate 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 falseNote: if set to true, the charge per task will be multiplied by 2", "nullable": true }, "browser_screen_width": { "type": "integer", "description": "browser screen widthoptional fieldyou can set a custom browser screen width to calculate pixel rankings for a particular device;by default, the parameter is set to 1920;Note: to use this parameter, set calculate_rectangles to true", "format": "int64", "nullable": true }, "browser_screen_height": { "type": "integer", "description": "browser screen heightoptional fieldyou can set a custom browser screen height to calculate pixel rankings for a particular device;by default, the parameter is set to 1080;Note: to use this parameter, set calculate_rectangles to true", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "description": "browser screen resolution ratiooptional fieldyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;by default, the parameter is set to 1;Note: to use this parameter, set calculate_rectangles to true", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "image_url": "https://dataforseo.com/wp-content/uploads/2016/11/data_for_seo_light_429.png" } ] }, "SerpGoogleDatasetSearchTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpNaverOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpNaverOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpNaverOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpNaverOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleLocalFinderTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocalFinderTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nlocal_pack", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LocalPackSerpElementItem" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "SerpGoogleLocalFinderTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleLocalFinderTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleLocalFinderTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleLocalFinderTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: local_finder", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleDatasetSearchTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d.learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "language_code": { "type": "string", "description": "search engine language codeoptional fieldpossible value:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 20max value: 700Your 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 results in the response, the difference will be refunded to your account balance automatically;", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serveronly value: advanced", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languageoptional fieldif you use this field, you don't need to specify language_codepossible value:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "last_updated": { "type": "string", "description": "last time the dataset was updatedoptional fieldpossible values: 1m, 1y, 3y", "nullable": true }, "file_formats": { "type": "array", "items": { "type": "string" }, "description": "file formats of the datasetoptional fieldpossible values: other, archive, text, image, document, tabular", "nullable": true }, "usage_rights": { "type": "string", "description": "usage rights of the datasetoptional fieldpossible values: commercial, noncommercial", "nullable": true }, "is_free": { "type": "boolean", "description": "indicates whether displayed datasets are freeoptional fieldpossible values: true, false", "nullable": true }, "topics": { "type": "array", "items": { "type": "string" }, "description": "dataset topicsoptional fieldpossible values: humanities, social_sciences, life_sciences, agriculture, natural_sciences, geo, computer, architecture_and_urban_planning, engineering", "nullable": true } }, "example": [ { "keyword": "water quality", "last_updated": "1m", "file_formats": [ "archive", "image" ], "usage_rights": "noncommercial", "is_free": true, "topics": [ "natural_sciences", "geo" ] } ] }, "SerpBaiduOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceExploreTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpScreenshotRequestInfo": { "type": "object", "properties": { "task_id": { "type": "string", "description": "task identifier\nrequired field\nunique identifier of the associated task in the UUID format\nyou will be able to use it within 7 days to request the results of the task at any time" }, "browser_preset": { "type": "string", "description": "browser resolution preset\noptional field\nbrowser preset associated with a certain device type\ncan take the following values: desktop, tablet, mobile\nNote: by default, browser preset corresponds to the device type specified in the POST request", "nullable": true }, "browser_screen_width": { "type": "integer", "description": "width of the browser resolution\noptional field\ncan be specified in the following range: 240-9999\ndefault value for desktop: 1920\ndefault value for mobile: 390\ndefault value for table: 1024", "format": "int64", "nullable": true }, "browser_screen_height": { "type": "integer", "description": "height of the browser resolution\noptional field\ncan be specified in the following range: 240-9999\ndefault value for desktop: 1080\ndefault value for mobile: 844\ndefault value for table: 1366", "nullable": true }, "browser_screen_scale_factor": { "type": "number", "description": "browser scale factor\noptional field\ncan be specified in the following range: 0.5-3\ndefault value for desktop: 1\ndefault value for mobile: 3\ndefault value for table: 2", "nullable": true }, "page": { "type": "integer", "description": "number of SERP pages\noptional field\nif depth in the corresponding Task POST request exceeds 10 results (or 1 SERP page), specify the number of SERP pages to screenshot;\ndefault value: 1", "nullable": true } }, "example": [ { "task_id": "06211235-0696-0139-1000-36727fbd3c90", "browser_screen_scale_factor": 0.5 } ] }, "SerpGoogleNewsLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleNewsLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleNewsLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleNewsLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "includes_non_news_search_results": { "type": "boolean", "description": "indicates whether the response contains non-news search results in addition to news content", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\ntop_stories, news_search", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleNewsElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpYoutubeOrganicTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeOrganicTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpGoogleFinanceExploreLiveHtmlRequestInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldpossible value: desktop", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "news_type": { "type": "string", "description": "financial news filtersoptional fieldpossible values: top_stories, local_market, world_marketsdefault value: top_stories", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840 } ] }, "SerpBingLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nexample:\n\"location_code\": 9041134,\n\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\n\"location_code_parent\": 20044\nwhere location_code_parent corresponds to:\n\"location_code\": 20044,\n\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type\nindicates the geographic classification of the location\nexample:\n\"location_type\": \"Country\", or \"location_type\": \"State\"", "nullable": true } } }, "SerpGoogleAiModeTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpYahooOrganicLiveHtmlRequestInfo": { "type": "object", "properties": { "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8", "nullable": true }, "keyword": { "type": "string", "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn 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\nrequired field if you don\u2019t specify location_code or location_coordinate\nif you use this field, you don\u2019t need to specify location_code or location_coordinate\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/yahoo/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\u00a0or location_coordinate\nif you use this field, you don\u2019t need to specify location_name or location_coordinate\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/yahoo/locations\nexample:\n2840", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or location_code\nif you use this field, you don\u2019t need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \u201clatitude,longitude,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9 (mm)\nthe maximum value for \u201cradius\u201d: 199999 (mm)\nexample:\n53.476225,-2.243572,200", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t 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/yahoo/languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/yahoo/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically according to the location and language you specify\nhowever, you can set a custom search engine domain in this field\nexample:\nau.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10\nmax value: 200\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleAutocompleteTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAutocompleteTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAutocompleteTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: autocomplete", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleImagesTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleImagesTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleImagesTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleImagesTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\ncarousel, images_search, related_searches", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleImagesElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleAutocompleteLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAutocompleteLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAutocompleteLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAutocompleteLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nin this case, will equal null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nautocomplete", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Autocomplete" } ], "nullable": true }, "description": "items of the element", "nullable": true } } }, "SerpGoogleDatasetInfoTaskPostRequestInfo": { "type": "object", "properties": { "dataset_id": { "type": "string", "description": "ID of the datasetrequired fieldyou can find dataset ID in the dataset URL or dataset item of Google Dataset Search resultexample:L2cvMTFqbl85ZHN6MQ==" }, "language_code": { "type": "string", "description": "search engine language codeoptional fieldif you use this field, you don't need to specify language_namepossible value:en", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible value: advanced", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languageoptional fieldif you use this field, you don't need to specify language_codepossible value:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldchoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "dataset_id": "L2cvMTFqbl85ZHN6MQ==" } ] }, "SerpGoogleAdsSearchTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsSearchTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "SerpYoutubeOrganicTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeOrganicTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeOrganicTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nyoutube_channel, youtube_video, youtube_video_paid", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiYoutubeOrganicElementItem" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleFinanceExploreLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceExploreLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceExploreLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceExploreLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible 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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceElementItem" } ], "nullable": true }, "description": "market indexes related to the market trends element\npossible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element", "nullable": true } } }, "SerpGoogleFinanceQuoteTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: finance_quote", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleAdsAdvertisersTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsAdvertisersTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAdsAdvertisersTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: ads_advertisers", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYoutubeOrganicTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeOrganicTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeOrganicTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeOrganicTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: organic", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpYoutubeVideoInfoTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpYoutubeVideoInfoTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpYoutubeVideoInfoTaskGetAdvancedResultInfo": { "type": "object", "properties": { "video_id": { "type": "string", "description": "ID of the video received in a POST array", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item:\nyoutube_video_info", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/YoutubeVideoInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleFinanceQuoteLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceQuoteLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceQuoteLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpBingOrganicTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBingOrganicTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBingOrganicTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBingOrganicTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpBingOrganicTaskPostRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don't specify location_name\u00a0or location_coordinate\nif you use this field, you don't need to specify location_name or location_coordinate\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/bing/locations\nexample:\n2840", "nullable": true }, "language_code": { "type": "string", "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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/bing/languages\nexample:\nen", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 10\nmax value: 700\nYour account will be billed per each SERP containing up to 10 results;\nSetting depth above 10 may result in additional charges if the search engine returns more than 10 results;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "priority": { "type": "integer", "description": "task priority\noptional field\ncan take the following values:\n1 \u2013 normal execution priority (set by default)\n2 \u2013 high execution priority\nYou will be additionally charged for the tasks with high execution priority.\nThe cost can be calculated on the Pricing page.", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\nreturn results for a specific device type\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "description": "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatype\nrequired field if you specify postback_url\ncorresponds to the datatype that will be sent to your server\npossible values:\nregular, advanced, html", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine location\nrequired field if you don't specify location_code or location_coordinate\nif you use this field, you don't need to specify location_code or location_coordinate\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/bing/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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/bing/languages\nexample:\nEnglish", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "calculate_rectangles": { "type": "boolean", "description": "calcualte pixel rankings for SERP elements in advanced results\noptional field\npixel ranking refers to the distance between the result snippet and top left corner of the screen;\nVisit Help Center to learn more>>\nby default, the parameter is set to false\nNote: you will be charged extra $0.0006 for using this parameter", "nullable": true }, "browser_screen_width": { "type": "integer", "description": "browser screen width\noptional field\nyou can set a custom browser screen width to calculate pixel rankings for a particular device;\ncan be specified within the following range: 240-9999;\nby default, the parameter is set to:\n1920 for desktop;\n360 for mobile on android;\n375 for mobile on iOS;\nNote: to use this parameter, set calculate_rectangles to true", "format": "int64", "nullable": true }, "browser_screen_height": { "type": "integer", "description": "browser screen height\noptional field\nyou can set a custom browser screen height to calculate pixel rankings for a particular device;\ncan be specified within the following range: 240-9999;\nby default, the parameter is set to:\n1080 for desktop;\n640 for mobile on android;\n812 for mobile on iOS;\nNote: to use this parameter, set calculate_rectangles to true", "nullable": true }, "browser_screen_resolution_ratio": { "type": "integer", "description": "browser screen resolution ratio\noptional field\nyou can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;\ncan be specified within the following range: 0.5-3;\nby default, the parameter is set to:\n1 for desktop;\n3 for mobile on android;\n3 for mobile on iOS;\nNote: to use this parameter, set calculate_rectangles to true", "nullable": true }, "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don't specify location_name\u00a0or location_code\nif you use this field, you don't need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \"latitude,longitude\" format\nthe maximum number of decimal digits for \"latitude\" and \"longitude\": 7\nexample:\n53.476225,-2.243572", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleDatasetInfoTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetInfoTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetInfoTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: dataset_info", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleOrganicLiveHtmlRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;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 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation error" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "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.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "load_async_ai_overview": { "type": "boolean", "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: falseNote your account will be billed $0.002 extra for each request;if the element is absent or contains \"asynchronous_ai_overview\": false, all extra charges will be returned to your account balance", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match typerequired field if stop_crawl_on_match is specifiedtype of match for the match_valuepossible values:domain \u2013 specific domain or subdomainwith_subdomains \u2013 main domain and subdomainswildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "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-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "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", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "expand_ai_overview": { "type": "boolean", "description": "expand ai overviewoptional fieldset to true to expand the ai_overview item;default value: false", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true }, "target_search_mode": { "type": "string", "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 \u2013 the crawl stops only when all specified targets are foundany \u2013 the crawl stops when any single target is founddefault value: anylearn more about this parameter on our Help Center", "nullable": true }, "find_targets_in": { "type": "array", "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", "nullable": true }, "ignore_targets_in": { "type": "array", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleDatasetSearchTasksFixedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTasksFixedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTasksFixedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleDatasetSearchTasksFixedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleDatasetSearchTasksFixedResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\ncan take the following values: dataset_search", "nullable": true }, "date_posted": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleAiModeLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAiModeLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAiModeLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAiModeLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraykeyword is returned with decoded %## (plus character '+' will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found in SERP", "nullable": true } } }, "SerpGoogleDatasetSearchLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "language_code": { "type": "string", "description": "search engine language codeoptional field if you don't specify language_nameif you use this field, you don't need to specify language_namepossible value:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 20max value: 700Your 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 results in the response, the difference will be refunded to your account balance automatically.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languageoptional fieldif you use this field, you don't need to specify language_codepossible value:English", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldchoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "last_updated": { "type": "string", "description": "last time the dataset was updatedoptional fieldpossible values: 1m, 1y, 3y", "nullable": true }, "file_formats": { "type": "array", "items": { "type": "string" }, "description": "file formats of the datasetoptional fieldpossible values: other, archive, text, image, document, tabular", "nullable": true }, "usage_rights": { "type": "string", "description": "usage rights of the datasetoptional fieldpossible values: commercial, noncommercial", "nullable": true }, "is_free": { "type": "boolean", "description": "indicates whether displayed datasets are freeoptional fieldpossible values: true, false", "nullable": true }, "topics": { "type": "array", "items": { "type": "string" }, "description": "dataset topicsoptional fieldpossible values: humanities, social_sciences, life_sciences, agriculture, natural_sciences, geo, computer, architecture_and_urban_planning, engineering", "nullable": true } }, "example": [ { "keyword": "water quality", "last_updated": "1m", "file_formats": [ "archive", "image" ], "usage_rights": "noncommercial", "is_free": true, "topics": [ "natural_sciences", "geo" ] } ] }, "SerpBaiduOrganicTaskGetRegularResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskGetRegularTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpBaiduOrganicTaskGetRegularTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpBaiduOrganicTaskGetRegularResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpBaiduOrganicTaskGetRegularResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nkeyword is returned with decoded %## (plus symbol \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nequals null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results found in SERP\ncontains types of all search results (items) found in the returned SERP\npossible item types:\norganic, paid", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "items in SERP", "nullable": true } } }, "SerpGoogleOrganicLiveRegularRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;if this field contains such parameters as 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'site:', the charge per task will be multiplied by 5Note: queries containing the \u2018cache:\u2019 parameter are not supported and will return a validation error" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "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.", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typecan take the values:desktop, mobiledefault value: desktop", "nullable": true }, "location_name": { "type": "string", "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", "nullable": true }, "language_name": { "type": "string", "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 of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:English", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_type": { "type": "string", "description": "target match typerequired field if stop_crawl_on_match is specifiedtype of match for the match_valuepossible values:domain \u2013 specific domain or subdomainwith_subdomains \u2013 main domain and subdomainswildcard \u2013 wildcard pattern", "nullable": true }, "match_value": { "type": "string", "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-*\"", "nullable": true }, "max_crawl_pages": { "type": "integer", "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", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search queryoptional fieldget the list of available parameters and additional details here", "nullable": true }, "group_organic_results": { "type": "boolean", "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", "nullable": true }, "url": { "type": "string", "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\u2019t recommend using this method.example:https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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", "nullable": true }, "se_domain": { "type": "string", "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.", "nullable": true }, "target": { "type": "string", "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 (\u2018*\u2019) 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", "nullable": true }, "target_search_mode": { "type": "string", "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 \u2013 the crawl stops only when all specified targets are foundany \u2013 the crawl stops when any single target is founddefault value: anylearn more about this parameter on our Help Center", "nullable": true }, "find_targets_in": { "type": "array", "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", "nullable": true }, "ignore_targets_in": { "type": "array", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpYahooOrganicLiveRegularRequestInfo": { "type": "object", "properties": { "url": { "type": "string", "description": "direct URL of the search query\noptional field\nyou 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\u2019t recommend using this method.\nexample:\nhttps://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8", "nullable": true }, "keyword": { "type": "string", "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)\nif you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;\nif you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d\nlearn 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\nrequired field if you don\u2019t specify location_code or location_coordinate\nif you use this field, you don\u2019t need to specify location_code or location_coordinate\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/yahoo/locations\nexample:\nLondon,England,United Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location code\nrequired field if you don\u2019t specify location_name\u00a0or location_coordinate\nif you use this field, you don\u2019t need to specify location_name or location_coordinate\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/yahoo/locations\nexample:\n2840", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a location\nrequired field if you don\u2019t specify location_name\u00a0or location_code\nif you use this field, you don\u2019t need to specify location_name or location_code\nlocation_coordinate parameter should be specified in the \u201clatitude,longitude,radius\u201d format\nthe maximum number of decimal digits for \u201clatitude\u201d and \u201clongitude\u201d: 7\nthe minimum value for \u201cradius\u201d: 199.9 (mm)\nthe maximum value for \u201cradius\u201d: 199999 (mm)\nexample:\n53.476225,-2.243572,200", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine language\nrequired field if you don\u2019t specify language_code\nif you use this field, you don\u2019t 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/yahoo/languages\nexample:\nEnglish", "nullable": true }, "language_code": { "type": "string", "description": "search engine language code\nrequired field if you don\u2019t specify language_name\nif you use this field, you don\u2019t need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/yahoo/languages\nexample:\nen", "nullable": true }, "device": { "type": "string", "description": "device type\noptional field\ncan take the values:desktop, mobile\ndefault value: desktop", "nullable": true }, "os": { "type": "string", "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", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain\noptional field\nwe choose the relevant search engine domain automatically according to the location and language you specify\nhowever, you can set a custom search engine domain in this field\nexample:\nau.search.yahoo.com, uk.search.yahoo.com, ca.search.yahoo.com, etc.", "nullable": true }, "depth": { "type": "integer", "description": "parsing depth\noptional field\nnumber of results in SERP\ndefault value: 6\nmax value: 700\nYour account will be billed per each SERP;\nEach Yahoo SERP can contain fewer than 10 results, so setting depth above the default value may result in additional charges ;\nThe cost can be calculated on the Pricing page.", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limit\noptional field\nnumber of search results pages to crawl\ndefault value: 1\nmax value: 100\nNote: the max_crawl_pages and depth parameters complement each other;\nlearn more at our help center", "nullable": true }, "target": { "type": "string", "description": "target domain, subdomain, or webpage to get results for\noptional field\na domain or a subdomain should be specified without https:// and www.\nnote that the results of target-specific tasks will only include SERP elements that contain a url string;\nyou can also use a wildcard (\u2018*\u2019) character to specify the search pattern in SERP and narrow down the results;\nexamples:\nexample.com \u2013 returns results for the website\u2019s home page with URLs, such as https://example.com, or https://www.example.com/, or https://example.com/;\nexample.com* \u2013 returns results for the domain, including all its pages;\n*example.com* \u2013 returns results for the entire domain, including all its pages and subdomains;\n*example.com \u2013 returns results for the home page regardless of the subdomain, such as https://en.example.com;\nexample.com/example-page \u2013 returns results for the exact URL;\nexample.com/example-page* \u2013 returns results for all domain\u2019s URLs that start with the specified string", "nullable": true }, "search_param": { "type": "string", "description": "additional parameters of the search query\noptional field\nget the list of available parameters and additional details here", "nullable": true }, "stop_crawl_on_match": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpApiStopCrawlOnMatchInfo" } ], "nullable": true }, "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", "nullable": true }, "match_value": { "type": "string", "description": "target domain, subdomain, or wildcard value\nrequired field if stop_crawl_on_match is specified;\nrequired field if stop_crawl_on_match is specified\nspecify a target domain, subdomain, or wildcard value;\nNote: domain or subdomain must be specified without a request protocol;\nexample: \"match_value\": \"dataforseo.com\",\n\"match_value\": \"/blog/post-*\"", "nullable": true }, "match_type": { "type": "string", "description": "target match type\nrequired field if stop_crawl_on_match is specified\ntype of match for the match_value\npossible values:\ndomain \u2013 specific domain or subdomain\nwith_subdomains \u2013 main domain and subdomains\nwildcard \u2013 wildcard pattern", "nullable": true }, "tag": { "type": "string", "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", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "SerpGoogleFinanceQuoteLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "ticker or stock symbolrequired fieldin 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 keyword field;all %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "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 engines with their location_code by making a separate request to https://api.dataforseo.com/v3/serp/google/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "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 of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "device": { "type": "string", "description": "device typeoptional fieldreturn results for a specific device typepossible value: desktop", "nullable": true }, "location_name": { "type": "string", "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/serp/google/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code if 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldpossible values: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "window": { "type": "string", "description": "time window for google_finance_quote graphoptional fieldpossible values: 1D, 5D, 1M, 6M, YTD, 1Y, 5Y, MAXdefault value: 1DNote: if you specify a value that is different from 1D, the charge per task will be multiplied by 2", "nullable": true } }, "example": [ { "keyword": "CLW00:NYMEX", "location_code": 2840, "language_name": "English" } ] }, "SerpGoogleEventsLiveAdvancedRequestInfo": { "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 \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_name\u00a0or 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/events/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "description": "search engine language codeoptional fieldif you use this field, you don't need to specify language_nameby default, language settings correspond to one of the local official languages of the specified locationyou can receive the list of available languages of the search engine with their language_code\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERPdefault value: 10max value: 700Your 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;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.", "nullable": true }, "location_name": { "type": "string", "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/events/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languageoptional fieldif you use this field, you don't need to specify language_codeby default, language settings correspond to one of the local official languages of the specified locationyou 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", "nullable": true }, "os": { "type": "string", "description": "device operating systemoptional fieldnote that this API provides results for desktop onlychoose from the following values: windows, macosdefault value: windows", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "max_crawl_pages": { "type": "integer", "description": "page crawl limitoptional fieldnumber of search results pages to crawlmax value: 100Note: the max_crawl_pages and depth parameters complement each other;learn more at our help center", "nullable": true }, "location_coordinate": { "type": "string", "description": "GPS coordinates of a locationrequired field if you don't specify location_name\u00a0or 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\" formatdata will be provided for the country the specified coordinates belong tothe maximum number of decimal digits for \"latitude\" and \"longitude\": 7the minimum value for \"radius\": 199.9 (mm)the maximum value for \"radius\": 199999 (mm)example:53.476225,-2.243572,200", "nullable": true }, "date_range": { "type": "string", "description": "date range to get events foroptional fieldif you do not use this field, we will return all eventspossible values: today, tomorrow, week, weekend, next_week, month, next_month", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domainoptional fieldwe choose the relevant search engine domain automatically according to the location you specifyhowever, you can set a custom search engine domain in this fieldexample:google.co.uk, google.com.au, google.de, etc.", "nullable": true } }, "example": [ { "keyword": "concerts", "location_name": "Los Angeles,California,United States", "date_range": "today" } ] }, "SerpErrorsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpErrorsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpErrorsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpErrorsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpErrorsResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "id of the task", "nullable": true }, "datetime": { "type": "string", "description": "date and time when an error occurred\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "function": { "type": "string", "description": "corresponding API function", "nullable": true }, "error_code": { "type": "integer", "description": "error code of the task\nerror code of the task generated by DataForSEO\nsee full list of error codes", "nullable": true }, "error_message": { "type": "string", "description": "error message or error URL\nerror message generated by DataForSEO, or URL that caused an error\nsee full list of error messages", "nullable": true }, "http_url": { "type": "string", "description": "URL that caused an error\nURL you used for making an API call or pingback/postback URL", "nullable": true }, "http_method": { "type": "string", "description": "HTTP method that caused an error", "nullable": true }, "http_code": { "type": "integer", "description": "HTTP status code", "nullable": true }, "http_time": { "type": "number", "description": "time taken by HTTP request\nfor tasks set with a pingback/postback, this field will show the time it took your server to respond", "nullable": true }, "http_response": { "type": "string", "description": "HTTP response\nserver response", "nullable": true } } }, "SerpGoogleAdsSearchTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleAdsSearchTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleAdsSearchTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleAdsSearchTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed task\nunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engine\nexample: ads_search", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the SERP Regular task\nif SERP Regular is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the SERP Advanced task\nif SERP Advanced is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the SERP HTML task\nif SERP HTML is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "SerpGoogleFinanceMarketsLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleFinanceMarketsLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleFinanceMarketsLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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;\nin this case, the value will be null", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips\nin this case, the value will be null", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP;\npossible item types: google_finance_hero_groups, google_finance_explore_market_trends, google_finance_news, google_finance_interested, google_finance_people_also_search", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiGoogleFinanceElementItem" } ], "nullable": true }, "description": "market indexes related to the market trends element\npossible type of items: google_finance_asset_pair_element, google_finance_market_instrument_element, google_finance_market_index_element", "nullable": true } } }, "SerpGoogleOrganicLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpGoogleOrganicLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpGoogleOrganicLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpGoogleOrganicLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST array\nthe keyword is returned with decoded %## (plus character \u2018+\u2019 will be decoded to a space character)", "nullable": true }, "type": { "type": "string", "description": "type of element", "nullable": true }, "se_domain": { "type": "string", "description": "search engine domain in a POST array", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine results\nyou can use it to make sure that we provided accurate results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was received\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "spell": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/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", "nullable": true }, "refinement_chips": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RefinementChipsInfo" } ], "description": "search refinement chips", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search results in SERP\ncontains types of search results (items) found in SERP.\npossible item types:\nanswer_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", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results in SERP", "format": "int64", "nullable": true }, "pages_count": { "type": "integer", "description": "total search results pages retrieved\ntotal number of retrieved SERPs in the result", "format": "int64", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseSerpApiElementItem" } ], "nullable": true }, "description": "additional items present in the element\nif there are none, equals null", "nullable": true } } }, "SerpGoogleJobsTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 700 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201d;Note: the keyword you specify must indicate the job title;example: .net developerlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't 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/serp/google/jobs/locationsexample:2840", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_nameif 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\u00a0by making a separate request to the https://api.dataforseo.com/v3/serp/google/languagesexample:en", "nullable": true }, "depth": { "type": "integer", "description": "parsing depthoptional fieldnumber of results in SERP;default 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;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.", "nullable": true }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default);2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority;The cost can be calculated on the Pricing page", "nullable": true }, "pingback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 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", "nullable": true }, "postback_url": { "type": "string", "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 \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample: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", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the datatype that will be sent to your serverpossible values:regular, advanced, html", "nullable": true }, "location_name": { "type": "string", "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_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/serp/google/jobs/locationsexample:London,England,United Kingdom", "nullable": true }, "language_name": { "type": "string", "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_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/serp/google/languagesexample:English", "nullable": true }, "tag": { "type": "string", "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", "nullable": true }, "location_radius": { "type": "string", "description": "location search radiusoptional fieldlocation 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 1.609;if value is not specified, search is executed anywhere within the specified location;maximal value: 300minimal value: > 0", "nullable": true }, "employment_type": { "type": "array", "items": { "type": "string" }, "description": "employment contract typeoptional fieldtype of employment contract for which the search results will be returned;possible values:fulltime, partime, contractor, intern", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": ".net developer" }, { "language_name": "English", "location_name": "United States", "keyword": ".net developer", "tag": "some_string_123", "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag" } ] }, "SerpSeznamLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "SerpSeznamLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SerpSeznamLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "SerpSeznamLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate location\nonly City location_type is supported for all countries except China (where Country is also supported);\ndon\u2019t 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", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } } } }