Setting ‘Ad Traffic By Keywords’ Tasks

the maximum custom bid required field the collected data will be based on this value it stands for the price you are willing to pay for an ad; the higher value you specify here, the higher values you will get in the returned metrics learn more in this help center article

keywords match-type required field can take the following values: exact, broad, phrase

starting date of the forecasting time range required field if you specify date_to if you indicate date_from and date_to, you don’t need to specify date_interval minimum value is tomorrow’s date the value you specify in date_from shouldn’t be further than date_to date format: "yyyy-mm-dd" example: "2021-10-30"if Status endpoint returns false in the actual_data field, date_from can be set to the month before last and prior; if Status endpoint returns true in the actual_data field, date_from can be set to the last month and prior

ending date of the forecasting time range required field if you specify date_from if you indicate date_from and date_to, you don’t need to specify date_interval minimum value is date_from +1 day maximum value is current day and month of the next year date format: "yyyy-mm-dd" example: "2022-10-30"

include Google search partners optional field if you specify true, the results will be delivered for owned, operated, and syndicated networks across Google and partner sites that host Google search; default value: false – results are returned for Google search sites

full name of search engine location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_code or location_coordinate you can receive the list of available locations of the search engine with their location_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: London,England,United Kingdom

search engine location code optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_coordinate; you can receive the list of available locations of the search engines with their location_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/locations example: 2840

GPS coordinates of a location optional field if you do not indicate the location, you will receive worldwide results, i.e., for all available locations; if you use this field, you don’t need to specify location_name or location_code; location_coordinate parameter should be specified in the “latitude,longitude” format; the data will be provided for the country the specified coordinates belong to; example: 52.6178549,-155.352142

full name of search engine language optional field you can receive the list of available languages of the search engine with their language_name by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: English

search engine language code optional field you can receive the list of available languages of the search engine with their language_code by making a separate request to https://api.dataforseo.com/v3/keywords_data/google_ads/languages example: en

forecasting date interval optional field if you specify date_interval, you don’t need to indicate date_from and date_to possible values: next_week, next_month, next_quarter default value: next_month

results sorting parameters optional field Use these parameters to sort the results by relevance, impressions, ctr, average_cpc, cost, or clicks in the descending order default value: relevance

URL for sending task results optional field once the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/postbackscript?id=$id http://your-server.com/postbackscript?id=$id&tag=$tag Note: special characters in postback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center

notification URL of a completed task optional field when a task is completed we will notify you by GET request sent to the URL you have specified you can use the ‘$id’ string as a $id variable and ‘$tag’ as urlencoded $tag variable. We will set the necessary values before sending the request. example: http://your-server.com/pingscript?id=$id http://your-server.com/pingscript?id=$id&tag=$tag Note: special characters in pingback_url will be urlencoded; i.a., the # character will be encoded into %23 learn more on our Help Center

user-defined task identifier optional field the character limit is 255 you can use this parameter to identify the task and match it with the result you will find the specified tag value in the data object of the response

the current version of the API

general status code you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions

general informational message you can find the full list of general informational messages here

execution time, seconds

total tasks cost, USD

the number of tasks in the tasksarray

the number of tasks in the tasks array returned with an error

unique task identifier in our system in the Universally unique identifier (UUID) format

status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of response codes here

informational message of the task you can find the full list of general informational messages here

execution time, seconds

cost of the task, USD

number of elements in the result array