Site icon DataForSEO

DataForSEO Version 3 Release: Doubling Down on Developer Experience

v3 release 2

Important note for current users regarding the v3 update!
We will continue to support the v2 of the DataForSEO API. None of the DataForSEO v2 features and endpoints will be removed or deprecated in the foreseeable future. However, all the new features and updates will be released in DataForSEO v3 and thus will not be supported in v2.

DataForSEO has made a long journey, and it is time for taking a brave course to further improvements. We are announcing version three release of our API. But before diving into details, we have a story to share with you.

Six years ago, developing SEO software took us a lot of time and money, as it usually happens. We realized that many companies out there stumble over data retrieval issues during the development process. As we’ve experienced that ourselves, a deep understanding of the problem instilled the company to take chances with the new BaaS project. This is how our first API came into existence.

DataForSEO was created around four years ago. Before letting it fly with its own wings, we estimated the required capabilities for maintaining the anticipated number of calls and data volumes. We started off with a more sophisticated system that is well known to you – DataForSEO v2.

Having only a few clients at the very beginning, we could not imagine that now we would be proud to help more than 750 projects get a stable and reliable data supply. As our client base was increasing, we had an important decision to make.

Striving to help our customers grow their businesses further, as well as perform more operations at scale, we are launching version three of DataForSEO API. Behind this statement is a whole of 2019, full of hard work for the DataForSEO team. We tweaked and refined the operations of our system so that you could move your project forward with the new and enhanced capabilities.

This is a complete introduction to the main modifications, improvements, and differences of DataForSEO API in version 3 and version 2

Contents

1 General Changes Outlined

2 SERP API v3

3 Keywords Data API v3

4 Migration Roadmap

General Changes Outlined

Version three is designed for improving, speeding up and simplifying the general experience of working with our APIs. We have incorporated a number of quality enhancements that allow scaling up your operations, while the cost for API requests has decreased.

Before you start planning the migration, we recommend that you take some time to understand the difference between the versions. The highlights are:

Rank tracking in v3

You must have noticed that the Rank Tracker API has been deprecated in version three. This is a substantial change, however, it does not mean that v3 does not provide a way for checking website positions.

All the capabilities of Rank Tracker API have been incorporated into SERP API v3. It is now a holistic solution for both retrieving various types of data from the results pages and getting the positions of a particular domain or webpage. You can check rankings with the help of our script.

Learn more about rank tracking in v3

New URL structure

We have introduced a new structure for URL requests. It is a part of the general harmonization of the system in v3. This rearrangement establishes a standardized order of parts that constitute a URL for sending POST and GET API calls.

For SERP API, the search engine parameters are now passed as a part of the URL, so there is no need to specify them in the body of the POST request. That is why se_id and se_name fields were deprecated. Also, this rearrangement allowed us to develop a universal POST request structure for SERP API endpoints and set up an easier approach to indicating the type of SERP you need to retrieve (regular, advanced, HTML).

At the same time, restructuring the Keywords Data API URLs did not entail any changes to the API operation.

Learn more about the URL structure of SERP API calls
Learn more about the URL structure of Keywords Data API calls

Universal list of errors

In version three, we have generalized the errors and response codes that you may receive as the status of your task execution.

The HTTP response codes you could find explained for each separate API in v2 are now gathered in a single table on the Errors page. They reflect the common meaning of the issue that occurred on our or the customer’s side.

Besides HTTP response codes, the DataForSEO API v3 server returns internal error codes. You can find them in the status_code and status_message fields of the API response. These codes are generated by our system within the 10000-60000 range, and they provide the exact details of the issue and the actual root cause.

We have introduced the internal error codes to make it easier to track down the status of the task at each stage of processing.

Check the list of possible errors

Facilitated pricing model

When using version three, you will be charged according to a new billing model. We decided to eliminate the credit-based billing to make the pricing more simple and straightforward. Now the cost does not depend on or vary according to the payment amount.

The pricing page has been adjusted for the version three billing model. All v3 prices are stated per one API request in US dollars.

As a result of the transition to the new billing model, we managed to achieve a substantial price decrease. On average, the prices for SERP API dropped by 25% for normal and high priority and by 40% for the Live method. Moreover, in v3 you will pay only once for setting a SERP task, and then you can make three different GET requests for free to obtain Advanced, HTML and Regular SERPs.

As for the Keywords Data API prices, the value of the decrease is truly remarkable – the cost was reduced by 50%.

To get more details on the pricing changes and to understand the difference between v2 and v3 API cost, refer to the SERP API and Keywords Data API sections.

Note: the new pricing model does not apply to DataForSEO v2.

Pricing page
Learn more about new SERP API pricing
Learn more about new Keywords Data API pricing

SERP API v3

As you start working with the v3 of the SERP API, you will notice quite a lot of changes. In many aspects, SERP API v3 was largely written from the ground up, based on our experience with v2 and the valuable feedback we’ve been gathering for the last several years. Our main focus was to ensure the scalability and consistency of the API as well as enhance the developer experience.

Many new features have been added, but at the same time, several familiar features have been heavily modified or even deprecated. Some of the key changes include:

Refined approach to rank tracking

You won’t find the Rank Tracker API in the new version – it has been deprecated with its functionality being fully incorporated into SERP API v3. So far, this is one of the most profound changes in DataForSEO v3, so let’s go through it in more detail.

Get website rankings in v3
You can get rankings for a particular domain or webpage using the Standard method of data retrieval and our script. Along with indicating the search engine, location, language, and targeted keyword in your POST request to SERP API v3, you need to specify the necessary domain in the “tag” field and use “pingback_url” to provide the path to our script on your server.

The results can even be narrowed down to a specific type of SERP element.

Learn more about using the script for retrieving ranking data

Streamlined URL structure of API calls

First of all, we’ve restructured the URLs of POST/GET calls to SERP API. While sending the request to the v2, you were supposed to use standardized endpoints and pass search engine parameters to se_id or se_name fields. In the SERP API v3, these parameters are passed as a part of the call’s URL.

Learn more about search engines in SERP API v3

Let’s compare the URL structure of v2 and v3 endpoints.

Feature

SERP API v2

SERP API v3

Parent API https://api.dataforseo.com/v2/
srp_tasks_post
https://api.dataforseo.com/v3/
serp/google/organic/task_post
Search Engine Name se_id / se_name fields https://api.dataforseo.com/v3/
serp/google/organic/task_post
Search Engine Type https://api.dataforseo.com/v2/
srp_extra_tasks_post
https://api.dataforseo.com/v3/
serp/google/organic/task_post
SERP Type https://api.dataforseo.com/v2/
srp_html_tasks_post
https://api.dataforseo.com/v3/
serp/google/organic/task_get/html/$id
Completed tasks https://api.dataforseo.com/v2/
srp_tasks_get
https://api.dataforseo.com/v3/
serp/google/organic/tasks_ready


Harmonized SERP functions

You could’ve noticed that v3 requires that you specify the desired SERP type (i.e., in v3: advanced, html, regular) in the GET request URL. This precludes the logic of v2, which required indicating the SERP type (i.e., in v2: Extra, html, serp) in the POST request.

Let’s say, for example, you want to get SERP results for the “answer box” keyword.

1You send a POST request without indicating the type of SERP results.

Request Sample

https://api.dataforseo.com/v3/serp/google/organic/task_post

[
    {		
		"language_code": "en",
		"location_code": 2840,
		"keyword": "answer box"
    }
]

Response Sample 

{
    "version": "0.1.20200210",
    "status_code": 20000,
    "status_message": "Ok.",
    "time": "0.0675 sec.",
    "cost": 0.00075,
    "tasks_count": 1,
    "tasks_error": 0,
    "tasks": {
        {
            "id": "02101813-1535-0066-0000-e6516373c55f",
            "status_code": 20100,
            "status_message": "Task Created.",
            "time": "0.0042 sec.",
            "cost": 0.00075,
            "result_count": 0,
            "path": [
                "v3",
                "serp",
                "google",
                "organic",
                "task_post"
            ],
            "data": {
                "api": "serp",
                "function": "task_post",
                "se": "google",
                "se_type": "organic",
                "language_code": "en",
                "location_code": 2840,
                "keyword": "answer box",
                "device": "desktop",
                "os": "windows"
            },
            "result": null
        }
    }
}

2Now that the task is completed, you can get any of the available SERP types (regular, advanced, html) by sending a GET request to the corresponding endpoint.

Request Sample for regular SERP

https://api.dataforseo.com/v3/serp/google/organic/task_get/regular/$id

Response Sample
 
{
    "version": "0.1.20200210",
    "status_code": 20000,
    "status_message": "Ok.",
    "time": "0.0962 sec.",
    "cost": 0,
    "tasks_count": 1,
    "tasks_error": 0,
    "tasks": {
        {
            "id": "02101813-1535-0066-0000-e6516373c55f",
            "status_code": 20000,
            "status_message": "Ok.",
            "time": "0.0543 sec.",
            "cost": 0,
            "result_count": 1,
            "path": [
                "v3",
                "serp",
                "google",
                "organic",
                "task_get",
                "regular",
                "02101813-1535-0066-0000-e6516373c55f"
            ],
            "data": {
                "api": "serp",
                "function": "task_get",
                "se": "google",
                "se_type": "organic",
                "language_code": "en",
                "location_code": 2840,
                "keyword": "answer box",
                "device": "desktop",
                "os": "windows"
            },
            "result": [
                {
                    "keyword": "answer box",
                    "type": "organic",
                    "se_domain": "google.com",
                    "location_code": 2840,
                    "language_code": "en",
                    "check_url": "https://www.google.com/search?q=answer%20box&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
                    "datetime": "2020-02-10 16:13:44 +00:00",
                    "spell": null,
                    "item_types": [
                        "organic",
                        "people_also_ask",
                        "images",
                        "video",
                        "related_searches"
                    ],
                    "se_results_count": 1730000000,
                    "items_count": 98,
                    "items": [
                        {
                            "type": "organic",
                            "rank_group": 1,
                            "rank_absolute": 1,
                            "domain": "www.seoclarity.net",
                            "title": "Google Answer Box Research - Instant Answers in the SERPs",
                            "description": "Google Answers Your Queries: Research. ... Google’s answer box is a one unique SERP result that is powered by the knowledge graph or scraped from a site that provides an adequate answer. ... This is Google’s attempt to directly answer a searcher's query without the need for clicking a ...",
                            "url": "https://www.seoclarity.net/google-answers-queries-15134/",
                            "breadcrumb": "www.seoclarity.net › google-answers-queries-15134"
                        },
                        {
                            "type": "organic",
                            "rank_group": 2,
                            "rank_absolute": 3,
                            "domain": "moz.com",
                            "title": "How to Appear in GOOGLE'S ANSWER BOXES - Moz",
                            "description": "Sep 23, 2016 - Often eclipsing organic results at the top of the SERPs, \"ranking zero\" or capturing an answer box in Google can mean increased clicks and ...",
                            "url": "https://moz.com/blog/how-to-appear-in-googles-answer-boxes-whiteboard-friday",
                            "breadcrumb": "moz.com › how-to-appear-in-googles-answer-boxes-whiteboard-friday"
                        },
                        ...
Request Sample for advanced SERP

https://api.dataforseo.com/v3/serp/google/organic/task_get/advanced/$id

Response Sample 

{
    "version": "0.1.20200210",
    "status_code": 20000,
    "status_message": "Ok.",
    "time": "0.1037 sec.",
    "cost": 0,
    "tasks_count": 1,
    "tasks_error": 0,
    "tasks": {
        {
            "id": "02101813-1535-0066-0000-e6516373c55f",
            "status_code": 20000,
            "status_message": "Ok.",
            "time": "0.0558 sec.",
            "cost": 0,
            "result_count": 1,
            "path": [
                "v3",
                "serp",
                "google",
                "organic",
                "task_get",
                "advanced",
                "02101813-1535-0066-0000-e6516373c55f"
            ],
            "data": {
                "api": "serp",
                "function": "task_get",
                "se": "google",
                "se_type": "organic",
                "language_code": "en",
                "location_code": 2840,
                "keyword": "answer box",
                "device": "desktop",
                "os": "windows"
            },
            "result": [
                {
                    "keyword": "answer box",
                    "type": "organic",
                    "se_domain": "google.com",
                    "location_code": 2840,
                    "language_code": "en",
                    "check_url": "https://www.google.com/search?q=answer%20box&num=100&hl=en&gl=US&gws_rd=cr&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
                    "datetime": "2020-02-10 16:13:44 +00:00",
                    "spell": null,
                    "item_types": [
                        "organic",
                        "people_also_ask",
                        "images",
                        "video",
                        "related_searches"
                    ],
                    "se_results_count": 1730000000,
                    "items_count": 102,
                    "items": [
                        {
                            "type": "organic",
                            "rank_group": 1,
                            "rank_absolute": 1,
                            "position": "left",
                            "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[1]/div[1]/div[1]",
                            "domain": "www.seoclarity.net",
                            "title": "Google Answer Box Research - Instant Answers in the SERPs",
                            "url": "https://www.seoclarity.net/google-answers-queries-15134/",
                            "cache_url": "https://webcache.googleusercontent.com/search?q=cache:aTNKFY7ugO4J:https://www.seoclarity.net/google-answers-queries-15134/+&cd=1&hl=en&ct=clnk&gl=us",
                            "breadcrumb": "www.seoclarity.net › google-answers-queries-15134",
                            "is_image": false,
                            "is_video": false,
                            "is_featured_snippet": false,
                            "is_malicious": false,
                            "description": "Google Answers Your Queries: Research. ... Google’s answer box is a one unique SERP result that is powered by the knowledge graph or scraped from a site that provides an adequate answer. ... This is Google’s attempt to directly answer a searcher's query without the need for clicking a ...",
                            "pre_snippet": null,
                            "extended_snippet": null,
                            "amp_version": false,
                            "rating": null,
                            "highlighted": [
                                "Answers",
                                "answer box",
                                "answer"
                            ],
                            "links": null
                        },
                        {
                            "type": "people_also_ask",
                            "rank_group": 1,
                            "rank_absolute": 2,
                            "position": "left",
                            "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[2]/div[1]/div[1]",
                            "items": [
                                {
                                    "type": "people_also_ask_element",
                                    "title": "What is the answer box?",
                                    "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[2]/div[1]/div[1]/div[1]/div[1]/div[1]/div[1]/g-accordion-expander[1]",
                                    "expanded_element": [
                                        {
                                            "type": "people_also_ask_expanded_element",
                                            "featured_title": null,
                                            "url": "https://moz.com/blog/101-google-answer-boxes-a-journey-into-the-knowledge-graph",
                                            "domain": "moz.com",
                                            "title": "101 Google Answer Boxes: A Journey into the Knowledge Graph ...",
                                            "description": "An \" answer box \" is a SERP feature, usually displayed in a light-gray box, that occurs above the organic results (left column) and tries to directly answer a question. Aug 8, 2013",
                                            "table": null
                                        }
                                    ]
                                },
                                {
                                    "type": "people_also_ask_element",
                                    "title": "What is the Google answer box?",
                                    "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[2]/div[1]/div[1]/div[1]/div[1]/div[1]/div[2]/g-accordion-expander[1]",
                                    "expanded_element": [
                                        {
                                            "type": "people_also_ask_expanded_element",
                                            "featured_title": null,
                                            "url": "https://www.seoclarity.net/google-answers-queries-15134/",
                                            "domain": "www.seoclarity.net",
                                            "title": "Google Answer Box Research - Instant Answers in the SERPs",
                                            "description": "Google's answer box is a unique SERP result that is powered by the knowledge graph or scraped from a site that provides an adequate answer. It is typically displayed at the top of the results page, but below ads. Typically, instant answers are a box with a brief text answer and a source URL.",
                                            "table": null
                                        }
                                    ]
                                },
                                {
                                    "type": "people_also_ask_element",
                                    "title": "How do I get rid of answer box?",
                                    "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[2]/div[1]/div[1]/div[1]/div[1]/div[1]/div[3]/g-accordion-expander[1]",
                                    "expanded_element": [
                                        {
                                            "type": "people_also_ask_expanded_element",
                                            "featured_title": null,
                                            "url": "https://getanswerbox.com/uninstall",
                                            "domain": "getanswerbox.com",
                                            "title": "Uninstall - AnswerBox",
                                            "description": "Uninstall Information\nOpen the Start menu.\nClick Settings.\nClick System on the Settings menu.\nSelect Apps & features from the left pane. A list of installed apps appears in the right pane.\nSelect AnswerBox.\nClick the Uninstall button that appears.\nClick the Uninstall pop-up button to confirm.",
                                            "table": null
                                        }
                                    ]
                                },
                                {
                                    "type": "people_also_ask_element",
                                    "title": "How do I get Google Box?",
                                    "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[2]/div[1]/div[1]/div[1]/div[1]/div[1]/div[4]/g-accordion-expander[1]",
                                    "expanded_element": [
                                        {
                                            "type": "people_also_ask_expanded_element",
                                            "featured_title": null,
                                            "url": "https://yoast.com/featured-snippet-answer-box/",
                                            "domain": "yoast.com",
                                            "title": "How to get a Google answer box • Yoast",
                                            "description": "How to write content for Google answer boxes\nDo your keyword research.\nFind out what people ask about your keywords/brand/product/service.\nLook at the 'People also ask' boxes for ideas.\nUse Answer the Public to find questions to answer.\nCheck several current answers to see how it works.\nFind out where you could improve.\nMore items... • Jun 20, 2019",
                                            "table": null
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "type": "organic",
                            "rank_group": 2,
                            "rank_absolute": 3,
                            "position": "left",
                            "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[3]/div[1]/div[1]",
                            "domain": "moz.com",
                            "title": "How to Appear in GOOGLE'S ANSWER BOXES - Moz",
                            "url": "https://moz.com/blog/how-to-appear-in-googles-answer-boxes-whiteboard-friday",
                            "cache_url": "https://webcache.googleusercontent.com/search?q=cache:dp7KuM4roQ4J:https://moz.com/blog/how-to-appear-in-googles-answer-boxes-whiteboard-friday+&cd=10&hl=en&ct=clnk&gl=us",
                            "breadcrumb": "moz.com › how-to-appear-in-googles-answer-boxes-whiteboard-friday",
                            "is_image": false,
                            "is_video": false,
                            "is_featured_snippet": false,
                            "is_malicious": false,
                            "description": "Sep 23, 2016 - Often eclipsing organic results at the top of the SERPs, \"ranking zero\" or capturing an answer box in Google can mean increased clicks and ...",
                            "pre_snippet": "09/23/2016 00:00:00",
                            "extended_snippet": null,
                            "amp_version": false,
                            "rating": null,
                            "highlighted": [
                                "answer box"
                            ],
                            "links": null
                        },
                        {
                            "type": "images",
                            "rank_group": 1,
                            "rank_absolute": 4,
                            "position": "left",
                            "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[4]/div[1]",
                            "title": "Images for answer box",
                            "url": "https://www.google.com/search?num=100&q=answer+box&tbm=isch&source=univ&gl=US&hl=en&sa=X&ved=2ahUKEwig7c6usMfnAhUGA2MBHTxEClcQsAR6BAgLEAE",
                            "items": [
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://contentmarketinginstitute.com/2019/03/google-answer-box/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.poweredbysearch.com/blog/rank-for-the-google-answer-box/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.searchenginewatch.com/2015/06/24/google-answer-boxes-the-what-why-and-how/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.searchenginejournal.com/how-to-optimize-your-site-for-googles-answer-box/166084/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.searchenginejournal.com/how-to-optimize-your-site-for-googles-answer-box/166084/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://cognitiveseo.com/blog/17398/google-answer-box/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://searchengineland.com/3-tactics-using-answer-boxes-274398"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://memberpress.com/how-to-get-your-content-to-appear-in-google-answer-boxes/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.hdmz.com/blog-resources/google-answer-boxes-great-way-boost-organic-traffic"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.wpbeginner.com/beginners-guide/how-to-appear-in-google-answer-boxes-with-your-wordpress-site/"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://blog.imageworksllc.com/blog/how-to-optimize-your-site-for-googles-rich-answer-box"
                                },
                                {
                                    "type": "images_element",
                                    "alt": "Image result for answer box",
                                    "url": "https://www.practicalecommerce.com/6-tips-to-win-googles-answer-box"
                                }
                            ]
                        },
                        {
                            "type": "organic",
                            "rank_group": 3,
                            "rank_absolute": 5,
                            "position": "left",
                            "xpath": "/html[1]/body[1]/div[8]/div[3]/div[9]/div[1]/div[2]/div[1]/div[2]/div[2]/div[1]/div[1]/div[5]/div[1]/div[1]/div[1]",
                            "domain": "moz.com",
                            "title": "101 Google Answer Boxes: A Journey into the Knowledge ...",
                            "url": "https://moz.com/blog/101-google-answer-boxes-a-journey-into-the-knowledge-graph",
                            "cache_url": "https://webcache.googleusercontent.com/search?q=cache:ScM9jC5fj1gJ:https://moz.com/blog/101-google-answer-boxes-a-journey-into-the-knowledge-graph+&cd=23&hl=en&ct=clnk&gl=us",
                            "breadcrumb": "moz.com › blog › 101-google-answer-boxes-a-journey-into-the-kno...",
                            "is_image": false,
                            "is_video": false,
                            "is_featured_snippet": false,
                            "is_malicious": false,
                            "description": "Aug 8, 2013 - An \"answer box\" is a SERP feature, usually displayed in a light-gray box, that occurs above the organic results (left column) and tries to directly ...",
                            "pre_snippet": "08/08/2013 00:00:00",
                            "extended_snippet": null,
                            "amp_version": false,
                            "rating": null,
                            "highlighted": [
                                "answer box"
                            ],
                            "links": null
                        },
                       ...

Request Sample for HTML SERP

https://api.dataforseo.com/v3/serp/google/organic/task_get/html/$id

Response Sample 

{
    "version": "0.1.20200210",
    "status_code": 20000,
    "status_message": "Ok.",
    "time": "0.1051 sec.",
    "cost": 0,
    "tasks_count": 1,
    "tasks_error": 0,
    "tasks": {
        {
            "id": "02101813-1535-0066-0000-e6516373c55f",
            "status_code": 20000,
            "status_message": "Ok.",
            "time": "0.0141 sec.",
            "cost": 0,
            "result_count": 1,
            "path": [
                "v3",
                "serp",
                "google",
                "organic",
                "task_get",
                "html",
                "02101813-1535-0066-0000-e6516373c55f"
            ],
            "data": {
                "api": "serp",
                "function": "task_get",
                "se": "google",
                "se_type": "organic",
                "language_code": "en",
                "location_code": 2840,
                "keyword": "answer box",
                "device": "desktop",
                "os": "windows"
            },
            "result": [
                {
                    "keyword": "answer box",
                    "type": "organic",
                    "se_domain": "google.com",
                    "location_code": 2840,
                    "language_code": "en",
                    "datetime": "2020-02-10 16:13:44 +0000",
                    "items_count": 1,
                    "items": [
                        {
                            "page": 1,
                            "date": "2020-02-10 14:08:52 +0000",
                            "html": ""<!doctype html><html><head></head></body></html>"
{window.setTimeout(Kj,c)})}})();\n\n}catch(e){_._DumpException(e)}\n})(this.gbar_);\n// Google Inc.\n   "
                        }
                    ]
                }
            ]
        }
    }
}

Renewed search engine types

The new version of SERP API incorporates a large number of search engines including:


By contrast, v2 had only four search engine types:

  1. SERP endpoints providing stripped-down SERP results. Its v3 substitute is the Regular function of SERP API which now also fetches data on featured snippets.
  2. Extra SERP endpoints providing enhanced SERP results. SERP API v3 provides the same results through the Advanced function.
  3. Google Reviews can be found under the same name in version three as a part of the Business Data Reviews API.
  4. Google Images is fully supported in v3.

Deprecated endpoints and parallels

‌The SERP API v3 has parallels for most of the v2 functionality. There are, however, some endpoints that have been deprecated. As a part of your migration, you should remove them from your code.

The following endpoints have no parallel in v3:

Note: as we discussed in the previous chapter, SERP HTML and Extra SERP endpoints became meaningless – SERP API v3 will return the data in the format you specify in the GET request.

SERP HTML
https://api.dataforseo.com/v2/srp_html_tasks_post
https://api.dataforseo.com/v2/srp_html_tasks_get
https://api.dataforseo.com/v2/srp_html_tasks_get/$task_id
https://api.dataforseo.com/v2/srp_html_tasks_get/$task_id/$param

SERP Extra
https://api.dataforseo.com/v2/live/srp_extra_tasks_post
https://api.dataforseo.com/v2/srp_extra_tasks_post
https://api.dataforseo.com/v2/srp_extra_tasks_get
https://api.dataforseo.com/v2/srp_extra_tasks_get/$task_id

Note: SERP API v3 determines the search engine domain automatically according to the location and language parameters you set in the POST request.

Common Search Engines
https://api.dataforseo.com/v2/cmn_se
https://api.dataforseo.com/v2/cmn_se/$country_iso_code

The following table demonstrates parallels between endpoints of v2 and v3.

  • SERP API v2

      • https://api.dataforseo.com/v2/
        live/srp_tasks_post
      • https://api.dataforseo.com/v2/
        srp_tasks_post
      • https://api.dataforseo.com/v2/
        srp_tasks_get
      • https://api.dataforseo.com/v2/
        srp_tasks_get/$task_id
      • https://api.dataforseo.com/v2/
        srp_google_images_tasks_post
      • https://api.dataforseo.com/v2/
        srp_google_images_tasks_get
      • https://api.dataforseo.com/v2/
        srp_google_images_tasks_get/$task_id
      • https://api.dataforseo.com/v2/
        cmn_locations
      • https://api.dataforseo.com/v2/
        cmn_locations/$country_iso_code
  • SERP API v3

      • https://api.dataforseo.com/v3/serp/
        google/organic/live/regular
      • https://api.dataforseo.com/v3/serp/
        google/organic/task_post
      • https://api.dataforseo.com/v3/serp/
        google/organic/tasks_ready
      • https://api.dataforseo.com/v3/serp/
        google/organic/task_get/regular/$id
      • https://api.dataforseo.com/v3/serp/
        google/images/task_post
      • https://api.dataforseo.com/v3/serp/
        google/images/tasks_ready
      • https://api.dataforseo.com/v3/serp/
        google/images/task_get/advanced/$id
      • https://api.dataforseo.com/v3/serp/
        google/locations
      • https://api.dataforseo.com/v3/serp/
        google/locations/$country

New endpoints

‌Version three adds multiple endpoints, the majority of which are intended to add new opportunities for our customers by enhancing the capacity and harmonizing the system of the SERP API.

Google Organic
Google Organic in v3 encompasses the functionality of Extra SERP as well as SERP and SERP HTML of v2. Here, we’ve added endpoints that allow you to get regular, advanced or HTML results using both the standard POST/GET and Live functions.

Find out more about Google Organic endpoints in our docs

Google Maps
Google Maps was introduced in v3, but the structure of its endpoints is similar to that of Google Organic. The only notable difference is that this search engine type supports only the advanced format of data retrieval.

Find out more about Google Maps endpoints in our docs

Google News
Google News will help you get results from the News tab in Google vertical search. Just like in Google Maps, it supports advanced and HTML only.

Find out more about Google News endpoints in our docs

Google Images
Similarly to Google News/Google Maps/Google Organic, Google Images provides top 100 results from the corresponding Google vertical search tab and incorporates advanced and HTML results.

Find out more about Google Images endpoints in our docs

Facilitated pricing model

The new pricing model is probably the most significant change we introduced in v3. In a nutshell, with v3 you will be spending less, and your expenses will be tied to US dollars instead of credits.

Note: the new pricing model does not apply to DataForSEO v2.

Dollar-pegged prices
We’ve discarded the credit-based billing system and moved on to US dollars. The information in the pricing table and account dashboard has been aligned with the new pricing model.

Check new pricing

Pricing changes
The cost of making a call to SERP API v3 is on average 25% lower for requests with both high and normal priority. By the same token, the cost of the Live method has decreased by 40%.

What’s more, the prices of Advanced, HTML and Regular SERPs are now identical. In addition to that, you can get these three types of SERPs being charged only once.

This means that after you have made one POST request to the v3 API server, you can make three different GET requests for free to obtain Advanced, HTML and Regular SERPs, while your account is charged only once for the POST request.

The tables below illustrate the difference in prices for 1,000 SERP pages between v2 and v3.

High priority

API version Advanced HTML Regular
v2 $2 $4 $2
v3 $1.5 $1.5 $1.5

 

Normal priority

API version Advanced HTML Regular
v2 $1 $2 $1
v3 $0.75 $0.75 $0.75

 

Live

API version Advanced HTML Regular
v2 $5  — $5
v3 $3 $3 $3

 

Keywords Data API v3

Once you begin your work with Google Ads Keywords Data API in version three, you will see a number of changes. First of all, you must have noticed that there are no Clickstream data endpoints yet. However, this is one of the priority things we are working on now. It will be added in the nearest time.

Compared to SERP API, there are not so many key modifications in the Keywords Data API. Still, we have managed to implement considerable performance improvements and increase system load capabilities. One essential achievement we’ve made by virtue of changing the billing model is a significant API price decrease by 50%.

Before starting your work with Keywords Data API v3, we recommend reviewing the following points:

Streamlined URL structure of API calls

When using version two, you were making API calls with URL requests that were individual for each endpoint.

For example:

Setting Live task: POST https://api.dataforseo.com/v2/kwrd_sv
Setting Standard task: POST https://api.dataforseo.com/v2/kwrd_sv_tasks_post
Getting completed tasks: GET https://api.dataforseo.com/v2/kwrd_sv_tasks_get
Retrieving the results by id: GET https://api.dataforseo.com/v2/kwrd_sv_tasks_get/$task_id

The structure of the v2 URL comprised of:

https HTTPS protocol
api.dataforseo.com Hostname
v2 API version
kwrd_sv
kwrd_sv_tasks_post
kwrd_sv_tasks_get
kwrd_sv_tasks_get/$task_id
The endpoint, to which the request is made

The endpoint, to which the request is made and task id variable


In the third API version, we decided to harmonize the URLs within the whole system:

Setting Live task: POST https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live
Setting Standard task: POST https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/task_post
Getting completed tasks: GET https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/tasks_ready
Retrieving the results by id: GET https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/task_get/$id

The URL structure contains:

https HTTPS protocol
api.dataforseo.com Hostname
v3 API version
keywords_data The name of the API to which the request is made
google_ads Search engine
search_volume Type of data that will be retrieved
live
task_post
tasks_ready
task_get/$id
Type of the task that you set

Type of the task that you set and the id variable

 
Parallels between v2 and v3

Google Ads Keywords Data API v3 mainly corresponds to the functionality of v2 Google endpoints with only a few considerable changes.

First off, we have deprecated the ‘Search Volume for Keyword’ endpoint due to its low popularity among users. Nevertheless, the v3 ‘Search Volume’ endpoint is equal to the ‘Bulk Keyword Search Volume’ from v2. This way of retrieving the search volume data allows sending up to 700 keywords in one request. The price per one keyword is extremely cheaper compared to that of ‘Search Volume for Keyword’, hence the ‘Search Volume’ is a more cost-efficient and convenient solution especially for large-scale projects.

Secondly, the Keywords for Category v2 endpoint is no longer present in Google Ads Keywords Data API v3. However, you can use Keywords For Categories in DataForSEO Labs API as an alternative solution.

Lastly, Ads Traffic by Platforms v2 is, unfortunately, deprecated in Google Ads Keywords Data API v3. The latest version of Google Ads API no longer supports platforms as of now. Yet, we are looking for alternative solutions for you and will keep you updated on this matter.

As for other endpoints, there were no significant changes: several endpoints were renamed, and the limits were mainly increased. You can review the parallels in the table below:

v2 endpoint v2 limit v3 endpoint v3 limit
Search Volume for Keyword Post: 1 Search Volume Post: 1,000
Bulk Keyword Search Volume Post: 700 Search Volume Post: 1,000
Keywords for Domain Get: 700 Keywords For Site Get: 2,000
Keywords for Keywords Post: 200
Get: up to 700
Keywords For Keywords Post: 20
Get: up to 20,000
Ads Traffic for Keywords Post: 2,500 Ads Traffic By Keywords Post: 1,000

 
Extended list of locations

Version three of Keywords Data API introduces several new locations, that were not available in v2. Our system uses Google Ads API as a data source, so the supported locations correspond to Google Geographical Targeting.

We have refined the list of locations according to the latest changes. In v3, we support several new location types for Keywords Data API: Canton, Congressional District, Department, TV Region.

Get the full List of Google Ads Locations for Keywords Data

Facilitated pricing model

The new pricing model is probably the most significant change we introduced with v3. In a nutshell, with v3 you will be spending less, and your expenses will be tied to US dollars instead of credits.

Note: the new pricing model does not apply to DataForSEO v2.

Dollar-pegged prices
We’ve discarded the credit-based billing system and moved on to US dollars. The information in the pricing table and account dashboard has been aligned with the new pricing model.

Check new pricing

Pricing changes
The cost of using both Standard and Live methods of all Keywords Data API endpoints has decreased by 50%.

The table below illustrates the difference between v2 and v3 prices for one request to Keywords Data API.

API version Standard Live
v2 $0.1 $0.15
v3 $0.05 $0.075

 

Migration Roadmap

As you start working with the new version, you will quickly find out that this is not an incremental upgrade and it will take some effort to implement it. The good news, however, is that we’ve incorporated a number of new features and improved the overall usability of the API from the developer’s standpoint.

Migrating to the new version takes four simple but essential steps:

1Test and iterate

We have set up a new stand-alone account dashboard for version three. All it takes to start your test-drive is logging in. After you click “Login” on our website, you will see a dropdown menu. Choose DataForSEO API v3 and enter your v2 credentials to get into the new version’s dashboard.

When you log in for the first time, you will receive $1 for testing the service. It is enough for sending more than 300 requests to SERP API using the Live method. In case you want to test v3 longer before migrating, we can transfer the required amount of money from your v2 account. In this way, no additional payment will be required.

You can also use the free Sandbox feature to facilitate the migration process.

DataForSEO API v3 login
Learn more about using Sandbox

2Upgrade your examples

Same as we had it in the previous version, v3 runs on the REST technology and HTTP protocol, so you can apply our APIs to almost any programming language. We have prepared new examples for PHP, Python, and C#. You can download the necessary examples from the Introduction page and import them into your library.

Download new examples

3Get familiar with the changes, new documentation and pricing model

Striving to improve the developer experience and overall system performance, we have fine-tuned some features, while also adding new opportunities and deprecating superfluous v2 functionality. Before you begin your work with the v3, we recommend checking the outline of changes and the v3 documentation.

General Changes Outlined
DataForSEO v3 docs

One of the essential changes is the deprecation of credit notion and price variations that were tied to the amount of money you pay. Instead, we decided to implement an easier approach and even reduced the API cost. Unlike version two, the requests to v3 APIs have a fixed price in the US dollars. Check the links below for more information on the new billing model.

SERP API v3 pricing explained
Keywords Data API v3 pricing explained

4Move your funds

Once you are prepared to switch to the new version, you might have some funds remaining on your account balance. We have thought of this beforehand, and we want to reassure you that the migration will not drag any money loss. Your funds from v2 will be transferred to your new v3 account balance.

Contact our support team to request the fund transfer or get more instructions on the migration process

Exit mobile version