A Kickstart Guide to Using DataForSEO APIs

While you can’t see them, APIs are everywhere, continuously working in the background to fuel a myriad of digital functionalities that have become essential to our lives.

At DataForSEO, we specialize in APIs that offer a gateway to SEO and marketing data for developers and data enthusiasts alike. We believe that valuable digital insights should be within reach for everyone, so in this article, we provide an accessible starting point for beginners and a comprehensive guide to DataForSEO APIs for experienced users.

This article contains all the necessary information and key resources to consult for streamlined interaction with our APIs. We explain what an API is, give an in-depth overview of how DataForSEO APIs work, and include all the essential steps for making DataForSEO API calls.

Contents:

What is an API?
How do APIs work?
Authorization and API key
What is an endpoint?
HTTP request methods
Request body and JSON parameters
Non-technical guidelines for making DataForSEO API calls using Postman
Developer guidelines for making requests to DataForSEO API
A quick guide to our data
Summary

What is an API?

An API, short for Application Programming Interface, is a set of rules that facilitates the exchange of information between different software systems, apps, or devices.

API examples

Understanding application programming interfaces may be easier with some real-life examples, so let’s consider a few.

• Stripe API enables developers to simplify transactions by adding online payment processing services into their apps or software.
• OpenWeatherMap API helps to obtain real-time weather data for different locations straight in your app.
• DataForSEO’s APIs allow developers and data enthusiasts to access powerful SEO and marketing insights (such as search volume, ranking data, backlink stats, and more) and integrate them into their tools, or platforms.

If you are interested in learning more about APIs for SEO software development, check out this informative blog post.

What are REST APIs

DataForSEO specializes in REST APIs. REST, or Representational State Transfer, is the most popular approach to building web APIs based on six principles:

• Uniform interface (UI) – unique resources identifiable through a single URL.
• Client-server model – API clients handle UI and request gathering, while API servers manage data access, workload, and security.
• Stateless operations – each request contains complete client information, while the server doesn’t retain any information about the client state.
• RESTful resource caching – response data is labeled as cacheable or non-cacheable.
• Layered system – hierarchical architecture restricting each component to interact only with its immediate layer.
• Code on demand – the server can return static resources (in XML or JSON) or executable codes as needed.

If some terminology is unclear, don’t worry; we will explain everything step by step in the next parts. The key takeaway is that these principles make a RESTful API service scalable, easily maintainable, flexible, and lightweight.

While other architectural concepts like SOAP and GraphQL exist, this article will focus on REST APIs to provide you with insights into how DataForSEO APIs operate and how to work with them.

How do APIs work?

At its core, an API acts as an intermediary operating in a request and response cycle between an API client and an API server.

Now that you understand the core principle, let’s delve into the components of REST APIs and learn their roles.

To understand API workflow better, we should first talk about an API client. It can be a code or a tool, but either way, an API client is an indispensable component responsible for assembling and sending requests and receiving responses from the API server. It also manages the flow of data (showing it to the user or integrating it into a broader data flow within a software).

An API request, also referred to as an API call, is the process during which an API client sends a request to the server and delivers back the server’s response.

The API server is one of the indispensable components for API functioning. It is in charge of authentication, validation of input parameters, response data formatting, and the flow of information between the API client and a database.

While the database is not considered an API component, an API cannot operate without it. The API server uses a database to store, manipulate, and extract data that it serves to the API client as a response.

API response is the data the API server sends back to the API client following an API request.

If you’re still confused, let’s break it down in simple terms. Imagine you are in a bakery and you (the client) want to get a cake. You don’t need to know the recipe or buy any ingredients, you just approach the shopkeeper (the API) and ask (with an API request) for a chocolate cake. The shopkeeper hands your order to the baker (server or data source). The baker prepares it, and the shopkeeper hands you the ready-made cake. Similarly, accessing valuable data through API ensures a hassle-free experience, much like ordering a cake.

Now, let’s touch on some concepts you should understand when working with DataForSEO APIs.

Authorization and API key

Commercial APIs commonly require authorization before you can access their functionality. To access DataForSEO APIs, you should use an API key, which is a combination of the login and password credentials.

Your API login is the same as the email address you use to create an account with DataForSEO.
A secure API password is automatically generated for you by our system after you create an account.

Note that your API password is intended for authentication when making requests to DataForSEO API and is different from the account password used for dashboard access.

You can always find your DataForSEO API login and password in the Account Dashboard. Your API login will always remain visible, while your API password will be hidden 24 hours after registration for security reasons. If you need the API password later, you can obtain it via the email address you used for creating an account.

What is an endpoint?

An API endpoint is a specific URL that represents a path for accessing a certain function or resource (e.g. a data set). You may think of an endpoint as a destination explaining to the API server how to proceed with your call.

For example, the following endpoint will tell the API server that you want to do something with the list of locations for Google SERP API:

https://api.dataforseo.com/v3/serp/google/locations

However, to tell it exactly what needs to be done, you should also use the appropriate HTTP request method.

HTTP request methods

HTTP request methods indicate what operations should be performed by following the path you indicate as an endpoint. When working with DataForSEO APIs, you will be using only POST and GET methods.

The GET method allows you to retrieve data from the specified endpoint. Additionally, in some cases, the POST method ensures an enhanced user experience by allowing you to pass your data extraction parameters to our system and facilitating the retrieval of Live task results.

Whenever you make an API request, always check and use the appropriate HTTP method for each endpoint. This information is set by default in our Postman collection and examples for PHP, Python, and C#. You can also find the appropriate HTTP method indicated before the endpoint’s URL in our documentation.

For instance, to retrieve the list of locations available for Google SERP API, you should use the GET method. At the same time, to extract top 100 Google SERP results with either Live or Standard data delivery, you should use a POST call and include endpoint-specific data extraction parameters in the request body.

Request body and JSON parameters

The request body is a section of an HTTP request containing data (parameters). Parameters are the variables or fields intended for specifying your data processing instructions.

When making calls to DataForSEO API, all data in your request body should be sent in JSON format. JSON keeps its data in name-value pairs. We’ll provide an example further.

First, let’s consider the parameters more closely. In our documentation, you will see that some parameters are required while others are optional.

Required fields mean that your API request cannot be processed if your request body does not contain them. For example, you want to make a POST request for processing some Google Search results using this endpoint: https://api.dataforseo.com/v3/serp/google/organic/task_post

Your API call instructions will only be understood by the API server if they include three required parameters specifying the keyword, location, and language you are interested in. Here’s an example of a POST request body containing these parameters.

[
    {
        "language_name": "English",
        "location_name": "United States",
        "keyword": "albert einstein"
    }
]

You can easily understand the name-value relationship in JSON here. The name "language_name" has a value of "English".

You can always find all available POST parameters and instructions for specifying them on the endpoint’s documentation page. For instance, here’s a page describing parameters for Setting Google Organic SERP Tasks.

As for optional fields, you can simply omit them in the body of your API requests. However, note that some optional parameters will be set to default values if you do not specify otherwise. For example, if you do not indicate a device type (desktop or mobile) for which you want to check the search results, the API will return data for the desktop by default.

You will find default values for every optional request parameter in their description on the documentation page of the related endpoint.

There are also optional fields that do not have any default values and do not impact the data you receive in the results. For instance, if you do not use a tag parameter (which can indicate a custom task identifier in your system), the data you retrieve simply will not contain it.

Non-technical guidelines for making DataForSEO API calls using Postman

1 Download and install the Postman tool. Download POSTMAN Examples and import the unarchived JSON file into the tool.

2 Open the DataForSEO collection, and select the API endpoint from it. For example, you can go to the Keyword Data API folder, select Google Ads, and head to the keywords_for_site folder. Launch the task_post or live endpoint.

3 Specify your API key in the Auth tab.

4 If you are making a POST request, add POST parameters to the Body of your request. Make sure to include all parameters marked as required on the selected endpoint’s page in our docs. You can also make a request with the parameters already included in the example.

5 Hit Send to submit your API request.

6 Wait for the response from our API. If you are using the Live method, you will obtain the data you requested in the API response.

If you are using the Standard method, the API response will provide you with the ID of the task you set. You should then copy the ID and proceed to the next step.

➤ Learn more about task ID.
➤ Learn more about the difference between Live and Standard methods.

7 Select the appropriate GET endpoint for collecting the task results, e.g. launch the task_get from the keywords_for_site folder. Replace the example ID at the end of the request URL after task_get/ with the ID of your task.

8 Once again, specify your API key in the Auth tab.

9 Submit your API request by hitting Send, and wait for the response from our API.

The structure of the response body varies depending on the specific DataForSEO API endpoint and the type of data you are requesting.

You can always refer to the DataForSEO documentation to find the necessary endpoint and review an example of its response body structure (lower right section with JSON code) along with a detailed description of the fields the response can contain organized into a handy table.

In case your request returns an error in the status_code and status_message fields, refer to the Errors endpoint of our documentation for instructions, or contact our support team.

Useful resources:

DataForSEO Help Center
Making Your First Call to SERP API v3 via Postman
Making Your First Call to Keywords Data API v3
Using filters in DataForSEO APIs
How to limit the number of duplicate tasks?
Can I set a limit for my payments to DataForSEO?
How do I set an auto-recharge for my account?
Illustrated guide to building a Backlink Checker
Illustrated guide to building a Reputation Management Tool
Illustrated guide to building a Rank Tracking App

Developer guidelines for making requests to DataForSEO API

1 Get an API client. You can create your REST client or use one of the ready-made, officially supported clients for PHP, Python, C#, Java, and TypeScript – listed here in our documentation.

2 Regardless of the programming language, your unique API key should be passed in the ‘Authorization’ header within the request in the following format:

Authorization: Basic login:password

Instead of “login” and “password”, use your API key (login and password) encoded in Base64. You can find your DataForSEO API login and password in the Account Dashboard.

For more information about Authentication for making DataForSEO API calls, refer to our documentation.

3 Indicate the URL of the API endpoint of your choice. You can copy it from our documentation, e.g. https://api.dataforseo.com/v3/serp/google/organic/task_post

4 Set the appropriate HTTP method (POST/GET). It’s indicated before the URL of the endpoint in our docs.

5 If you are making a POST request, add POST parameters to the body of your request. All data in your request body should be sent in the JSON format (UTF-8 encoding). Include all parameters marked as required in our documentation. Make sure the request body is valid. You can find an example body in the upper right section of the selected endpoint’s page in our docs.

See also:
➤ How to set multiple tasks in one API request?
➤ Using filters in DataForSEO APIs
➤ How do I know when a task is completed? Can I get a list of completed tasks?
➤ How long does DataforSEO keep the results of a task after its completion?
➤ What are pingbacks & postbacks and how to use them with DataForSEO API?

6 If you are making a GET request to obtain the results of a set task, replace $id at the end of the request URL with the ID of your task.

7 Submit your API request.

8 Wait for the response from our API.

If you are setting a task using a Task POST endpoint, save the ID of the task provided in the response. You can use it repeatedly within 30 days to retrieve the results of the task.

If you collect the results of a set task, you can always refer to the DataForSEO documentation to find the necessary endpoint and review an example of its response body structure (lower right section with JSON code) along with a detailed description of the fields the response can contain.

Here are some important components of an API response you should know about when working with DataForSEO API.

DataForSEO status codes and messages

Alongside general HTTP status codes, our system also generates internal API response status codes and messages. They are provided in the response body, e.g.:

"status_code": 20100,
"status_message": "Task Created.",

The status_code and status_message parameters indicated after the version in the response describe the status of your API call, while the status_code and status_message provided in the array of tasks describe the status of a particular task.

The status_code fields of a successful request and a successfully set task indicated in the response body will meet the following condition: 20000 <= status_code <= 29999. Refer to the Errors endpoint of our documentation to get the full list of DataForSEO’s internal status codes and messages.

HTTP response headers

The following response headers are essential for understanding and managing your DataForSEO API requests:

X-RateLimit-Limit indicates the rate limit ceiling per minute for the given API endpoint. Each DataForSEO API has a certain rate limit. If your system requires increased limits, please contact our support team via chat.

X-RateLimit-Remaining states the number of requests remaining in the current rate limit window.

Content-Encoding provides the encoding format of the response data. By default, DataForSEO API responses are compressed with gzip if you use one of the API clients listed here in our docs.

Content-Type indicates the data format in the response body. All DataForSEO API responses are returned in JSON (JavaScript Object Notation) format by default.

We also support responses in the XML (Extensible Markup Language) format – just append .xml to the end of your request URL. In addition to that, you can request HTML (Hypertext Markup Language) data from endpoints that return HTML-encoded results by appending .html to the end of the request URL.

For example, the following requests will return a response encoded in XML or HTML respectively:

https://api.dataforseo.com/v3/appendix/user_data.xml
https://api.dataforseo.com/v3/serp/google/organic/task_get/html/09061543-1535-0066-0000-6240830f56ba.html

Note on request limits

In general, you can send up to 2000 API calls per minute. If your project requires increased limits, please contact our support team.

Note that rate limits may vary per API. We recommend checking our documentation for a specific API and endpoint to learn all the details beforehand.

Useful resources:

Best practices for handling SERP API requests
Best practices for handling Keywords Data API requests
Best practices for handling OnPage API requests
What’s a webhook delay? How to set a delay for sending pingbacks and postbacks?
How to use the Errors and Webhook Resend endpoints to resend pingbacks and postbacks?
Troubleshooting OnPage API
How to limit the number of duplicate tasks?
DataForSEO API Wrapper for LangChain
DataForSEO Status Page
API Status endpoint

A quick guide to our data

We understand that with the large number of APIs and datasets we offer, it’s easy to miss the most suitable option for you. We’ll shed some light on our products and help you find the right solution. Here’s a full list of our APIs and Databases grouped by common use cases of our clients.

Summary

In summary, APIs enable seamless interaction between software systems. The main API components include the API client, API call, API server, and API response. DataForSEO’s REST APIs provide a streamlined way to access SEO and marketing data.

To make a successful DataForSEO API call, use the correct API key for authorization, and include all required request body parameters in POST calls.

For the Live method of data delivery, the data you request is provided in the API response to a single POST call. The more affordable Standard data delivery method requires setting a task with a POST call and making a separate GET request to obtain the results. It has two priorities, Normal and High, determining the speed of data collection. To retrieve results through a GET request, you should append a task ID at the end of the request URL.

To understand and properly process the API response, you should check the response body containing task results (requested data), task ID(s), or an error message.

Whenever necessary, you can consult our documentation for details on JSON parameters available for sending requests and API response fields of the endpoint you are using.

For handling related exceptional or error conditions, refer to the Errors endpoint of our documentation, or contact our support team for assistance.

Ready to leverage the potential of DataForSEO APIs, but don’t have an account? Sign up for a free trial now and collect valuable SEO and marketing insights with your first API request!