Site icon DataForSEO

Rules and limitations of “keyword” and “keywords” fields in DataForSEO APIs

Anatolii

As you may have noticed, keyword or keywords fields in various DataForSEO APIs have different limitations and rules you need to follow to correctly set the task. The limitations of these fields depend on the specifics of the APIs and the types of tasks they are used for. With the large number of endpoints that use the keyword or keywords fields, it is easy to get confused about how to set tasks properly and follow all requirements correctly.

In this article, we will explain all the rules and limitations of keyword and keywords fields in different APIs to make your work with DataForSEO endpoints convenient and efficient.

Contents:

SERP API
Keywords Data API
Domain Analytics API
DataForSEO Labs API
Content Analysis API
Merchant API
App Data API
Business Data API

SERP API

In the SERP API endpoints, the keyword field is a required field for setting a task, and you can specify up to 700 characters in it. Please not that the limit is applied to characters before the string is urlendcoded. For example, the "hello%20world" query is calculated as "hello world", e.g., as 11 characters.

If you enter encoded characters as %##, they will be decoded (plus character + will be decoded as a space character). Therefore, if you need to use the % character for your keyword, you should specify it as %25, and for using the + character, you should write %2B.

Keep in mind that if you write in the keyword field 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 5. However, you can use the ‘-site:’ parameter with no extra charge.

Please note that queries containing the ‘cache:’ parameter are not supported and will return a validation error.

If you are using the Google Jobs endpoint of SERP API, remember that the keyword you specify must indicate a job title.

Keywords Data API

Within the endpoints of Keywords Data API, the rules and limitations for keyword-related fields may vary significantly.

1. In the keywords field of the Google Ads Keywords Data API, several important rules and limitations must be observed to ensure correct data retrieval and avoid errors.

First, in the Search Volume and Ad Traffic By Keywords endpoints keywords is a required field when setting a task, and you can specify up to 1,000 keywords per request. Each keyword is limited to a maximum of 80 characters and 10 words. All keywords will automatically be converted to lowercase format upon submission.

In the Keywords for Keywords endpoint, you can specify up to 20 keywords, and the maximum number of characters for each keyword is also 80. All keywords will also be converted into lowercase format.

It is essential to be aware of several key points when working with keywords:

2. In the Bing Ads Keywords Data API, there are also several important rules and limitations for keywords fields.

First, in the Search Volume and Search Volume History endpoints, the keywords field is also a required input. You can specify up to 1,000 keywords in a single request, with each keyword being limited to 100 characters. All keywords will be automatically converted to lowercase, and the data will be returned in a separate array.

In case of Keywords for Keywords you can specify a maximum of 200 keywords, with each keyword containing no more than 100 characters. Similar to the other endpoints, the keywords will be converted to lowercase, and the data will be provided in a separate array.

In the Keyword Performance endpoint, keywords is again a required field. Here, you can specify up to 1,000 keywords, with a maximum of 80 characters per keyword and a limit of 10 words per keyword phrase. The keywords also will be converted to lowercase, and the data will be returned in a separate array.

3. In the Google Trends API, specific rules for keywords field are the following.

The keywords field is a required parameter. You can specify a maximum of 5 keywords in a single request. It is important to note that any commas (,) included in the specified keywords will be automatically unset and ignored, which could affect the accuracy of the query if not carefully managed.

4. For all endpoints of DataForSEO Trends API, the keywords field is also mandatory, and you can specify up to 5 keywords in a single request. It is crucial to avoid using symbols and special characters, such as UTF symbols or emojis, as these may cause errors or affect the accuracy of the data returned.
Additionally, if you specify keywords using non-Latin characters, the data retrieved will be limited to the countries where those characters are commonly used.

5. In the endpoints of Clickstream Data API, the keywords field is required, and all keywords must be encoded using UTF-8. You can specify up to 1,000 keywords in an array, with each keyword being at least 3 characters long. All submitted keywords will be automatically converted to lowercase format.

It is important to note that certain symbols and characters, such as UTF symbols and emojis, are not permitted and may result in errors during submission.

Domain Analytics API

In the Domain Analytics API, the use of keywords varies slightly depending on the endpoint but shares some common rules.

For instance, in the Aggregation Technologies endpoint, keywords represent the target keyword in a domain’s meta keywords. This field becomes mandatory if you do not specify a group, category, or technology. At least one of these fields (group, category, keyword, or technology) must be set. Keywords must be in UTF-8 encoding, and an example of this usage could be "seo".

In the Technologies Summary, Domains By Technology and Domains by HTML Terms endpoints, keywords fields are used similarly, targeting the domain’s title, description, or meta keywords. They are required unless groups, technology_paths, categories, or technologies are provided. You can specify up to 10 keywords per request, and these keywords must also be in UTF-8 encoding. An example of this would be ["seo", "software"].

DataForSEO Labs API

1 Google, Bing & Amazon endpoints

In DataForSEO Labs API keywords play a central role across various endpoints, with specific rules and limitations that vary slightly depending on the service being used. For instance, in the Google Related Keywords & Google Keyword Suggestions endpoint, keywords is a required field. Each keyword will automatically be converted to lowercase upon submission. UTF-8 encoding is also required. The same rules apply to the Bing Related Keywords and Amazon Related Keywords endpoints.

Similarly, in the Keyword Ideas endpoint, keywords field is also mandatory. The keywords will be converted to lowercase. However, in this case, you can specify up to 200 keywords per request.

In the Historical Search Volume endpoint, keywords is again a required field, with more detailed restrictions. You can specify up to 700 keywords, and each keyword can contain a maximum of 80 characters or up to 10 words per keyword phrase. Like in other endpoints, the keywords will be converted to lowercase. It’s also important to note that if some of the keywords are omitted from the results, it means that Google’s database does not contain data for those keywords, and no charges will apply for the omitted keywords.

For the Google Bulk Keyword Difficulty endpoint, keywords field is also required, and the maximum limit is significantly higher— up to 1,000 keywords can be submitted in one request. Each keyword will be converted to lowercase. UTF-8 encoding is mandatory, just like in the other endpoints. The same rules apply to the Bing Bulk Keyword Difficulty and Amazon Bulk Search Volume endpoints.

In the Search Intent endpoint, the rules are similar to Bulk Keyword Difficulty, where up to 1,000 keywords can be specified, each converted to lowercase. UTF-8 encoding is required here as well.

2 Market Analysis

In the Categories For Keywords endpoint, keywords is a required field. The keywords will automatically be converted to lowercase upon submission. UTF-8 encoding is required, ensuring proper formatting across various languages and character sets. You can specify up to 1,000 keywords in one request.

3 Competitor Research

In the Google SERP Competitors endpoint, keywords is a required field, as the results are directly based on the specified keywords. The keywords will be automatically converted to lowercase format. For this endpoint, you can specify a maximum of 200 keywords. The same rules apply for Bing SERP Competitors endpoint.

Content Analysis API

In the Content Analysis API, the Search, Summary, Sentiment Analysis, Rating Distribution, and Phrase Trends endpoints all require keywords as a mandatory field. Each keyword must be at least 3 characters long and will be automatically converted to lowercase format upon submission. UTF-8 encoding is aslo required.

A unique aspect of these endpoints is the ability to match an exact phrase instead of a stand-alone keyword. To do this, double quotes and backslashes should be used around the phrase. For example, specifying "\"tesla palo alto\"" will search for that exact phrase.

Merchant API

In the Merchant API, keywords is a required field in both the Google Shopping Products and Amazon Products endpoints, with some considerations. For both endpoints, you can specify up to 700 characters in the keyword field. Additionally, all URL encoded characters, such as %##, will be decoded automatically, with the plus character (+) being decoded into a space character. If you need to use the percent character (%) in a keyword, you must specify it as %25 to ensure proper processing.

In the Google Shopping Products endpoint, you also have the flexibility to specify a UPC/EAN (Universal Product Code/European Article Number) in the keyword field. This will return the results that Google Shopping provides for the specified barcode number.

App Data API

In the App Data API, the Google App Searches and Apple App Searches endpoints require keywords as a mandatory field. In both endpoints, you can specify up to 700 characters in the keyword field. Besides, all encoded characters such as %## will be decoded automatically, with the plus character (+) being decoded into a space character. If you need to use the percent character (%) within the keyword, it must be specified as %25 to ensure correct interpretation.

Business Data API

In the Business Data API, keywords play an essential role across various endpoints. In the Google My Business Info and Google My Business Questions and Answers endpoints, the keyword field is required and should indicate the name of the local establishment. You can specify up to 700 characters in the keyword field, and all URL encoded characters like %## will be decoded, with the plus character (+) being replaced by a space. If the % character is necessary in your keyword, it must be specified as %25.

The keyword field can also be used to pass additional parameters:

In the Google Hotel Info endpoint, the keyword field is required if you don’t specify a hotel_identifier. The keyword should indicate the name of the hotel entity, and like the other endpoints, you can specify up to 700 characters in the keyword field. Encoded characters are handled similarly, with %## decoded and the plus character replaced with a space. If you use the keyword field, there is no need to specify the hotel_identifier.

The Google Reviews endpoint also requires a keyword field if neither cid nor place_id are provided. In this case, the keyword should represent the name of the local establishment. As with other endpoints, you can specify up to 700 characters, with all encoded characters decoded, and the plus character replaced with a space.

Keywords containing certain search operators such as allinanchor:, allintext:, and others will result in the charge per task being multiplied by 5. However, queries containing the cache: parameter are not supported and will result in a validation error.

In the Trustpilot Search and Tripadvisor Search endpoints, the keyword field is a required parameter. The keyword you provide should indicate either a business category or a company name (or a prominent place in case of Tripadvisor Search). You are allowed to specify up to 700 characters in the keyword field. As with other similar endpoints, all encoded characters such as %## will be automatically decoded, and the plus character (+) will be replaced with a space. If your keyword needs to include the percent character (%), you must encode it as %25 to ensure proper processing.

Now you understand the difference between the rules and limitations of keyword and keywords fields in various DataForSEO APIs’ endpoints. In case you have additional questions, you can always contact our support team for help or navigate through the Help Center for any additional information.

Exit mobile version