keywords_data/dataforseo_trends/demography/live

Setting Live ‘DataForSEO Trends Demography’ Tasks

This endpoint will provide you with the demographic breakdown (by age and gender) of keyword popularity per each specified term based on DataForSEO Trends data. You can check keyword trends for Google Search, Google News, and Google Shopping.

How our algorithm works: Our algorithm provides insights into the popularity of specific keywords based on their association with relevant web pages, news articles, or shopping listings, as well as the popularity of each relevant piece of content. We also combine this information with anonymous user web behavior data from various sources. Learn more on our Help Center.

You will get information for every single keyword in an array.

You can send up to 5 keywords in one keywords array. Our system will charge your account per each request, no matter what number of keywords an array has.

Historical data for the web type: available from 2004-01-01;
Historical data for other types: available from 2008-01-01.

POST

Your account will be charged for each request.
The cost can be calculated on the Pricing page.

All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method. When setting a task, you should send all task parameters in the task array of the generic POST array. You can send up to 2000 API calls per minute, each Live API call can contain only one task. The maximum number of requests that can be sent simultaneously is limited to 30.
Visit DataForSEO Help Center to get practical tips for request handling depending on your Keyword Data API payload volume.

Below you will find a detailed description of the fields you can use for setting a task.

Description of the fields for setting a task:

Field name	Type	Description
`keywords`	array	keywords required field the maximum number of keywords you can specify: 5 avoid symbols and special characters (e.g., UTF symbols, emojis); specifying non-Latin characters, you’ll get data for the countries where they are used learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this Help Center article
`location_name`	string	full name of search engine location optional field if you don't use this field, you will recieve global results if 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/keywords_data/dataforseo_trends/locations` note that the data will be provided for the country the specified `location_name` belongs to; example: `United Kingdom`
`location_code`	integer	search engine location code optional field if you don't use this field, you will recieve global results if you use this field, you don't need to 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/keywords_data/dataforseo_trends/locations` note that the data will be provided for the country the specified `location_code` belongs to; example: `2840`
`type`	string	dataforseo trends type optional field if you don't specify this field, the `web` type will be used by default possible values: `web`, `news`, `ecommerce`
`date_from`	string	starting date of the time range optional field if you don't specify this field, the current day and month of the preceding year will be used by default minimal value for the `web` type: `2004-01-01` minimal value for other types: `2008-01-01` date format: `"yyyy-mm-dd"` example: `"2019-01-15"`
`date_to`	string	ending date of the time range optional field if you don't specify this field, the today's date will be used by default date format: `"yyyy-mm-dd"` example: `"2019-01-15"`
`time_range`	string	preset time ranges optional field if you specify `date_from` or `date_to` parameters, this field will be ignored when setting a task possible values for all `type` parameters: `past_4_hours`, `past_day`, `past_7_days`, `past_30_days`, `past_90_days`, `past_12_months`, `past_5_years`
`tag`	string	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

‌
As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.

Description of the fields in the results array:

Field name	Type	Description
`version`	string	the current version of the API
`status_code`	integer	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
`status_message`	string	general informational message you can find the full list of general informational messages here
`time`	string	execution time, seconds
`cost`	float	total tasks* cost, USD*
`tasks_count`	integer	the number of tasks in the `tasks`* array*
`tasks_error`	integer	the number of tasks in the `tasks`* array returned with an error*
`tasks`	array	array of tasks
`id`	string	task identifier unique task identifier in our system in the UUID format
`status_code`	integer	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
`status_message`	string	informational message of the task you can find the full list of general informational messages here
`time`	string	execution time, seconds
`cost`	float	cost of the task, USD
`result_count`	integer	number of elements in the `result` array
`path`	array	URL path
`data`	object	contains the same parameters that you specified in the POST request
`result`	array	array of results
`keywords`	array	keywords in a POST array
`type`	array	search engine type in a POST array
`location_code`	integer	location code in a POST array if there is no data, then the value is_`null`n
`language_code`	string	language code in a POST array if there is no data, then the value is_`null`n
`datetime`	string	date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: `2019-11-15 12:57:46 +00:00`
`items_count`	integer	the number of results returned in the `items`* array*
`items`	array	contains keyword popularity and related data
`position`	integer	the alignment of the element can take the following values: `1`, `2`, `3`, `4`, etc.
`type`	string	type of element = ‘demography’
`keywords`	array	relevant keywords the data included in the `demography` and `demography_comparison` is based on the keywords listed in this array
`demography`	object	demographic breakdown of keyword popularity data per each specified term conains keyword popularity data by age and gender
`age`	array	distribution of keyword popularity by age
`keyword`	string	relevant keyword for which demographic data is provided
`values`	array	contains age range and corresponding keyword popularity values
`type`	string	age range can take the following values: `18-24`, `25-34`, `35-44`, `45-54`, `55-64`
`value`	integer	keyword popularity rate within the specified age range using this `value` you can understand how popular a keyword is within each age range; calculation: we determine the highest popularity value for the relevant keyword across all age groups, and then express all other values as a percentage of that highest value (100); a value of `100` is the highest popularity for the term a value of `0` means there was not enough data for this term
`gender`	array	distribution of keyword popularity by gender
`keyword`	string	relevant keyword for which demographic data is provided
`values`	array	contains gender and corresponding keyword popularity values
`type`	string	gender category can take the following values: `female`, `male`
`value`	integer	keyword popularity rate within the specified gender category using this `value` you can understand how popular a keyword is within each gender category; calculation: we determine the highest popularity value for the relevant keyword across all gender categories, and then express all other values as a percentage of that highest value (100); a value of `100` is the highest popularity for the term; a value of `0` means there was not enough data for this term
`demography_comparison`	object	comparison of demographic data on keyword popularity for the specified parameters conains keyword popularity data by age and gender if you specified a single keyword, the value will be `null`
`age`	object	comparison of keyword popularity data by age
`$18-24`	array	indicates age range and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified age range variable can take the following values: `18-24`, `25-34`, `35-44`, `45-54`, `55-64`; using the values from this array, you can understand which of the specified `keywords` is more popular within the related age range; the first value in the array is provided for the first term from the `keywords` array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each age range, and then express all other values as a percentage of the total value (100); a value of `100` is the highest popularity for the term a value of `0` means there was not enough data for this term
`gender`	object	comparison of keyword popularity data by gender
`female`	array	indicates gender category and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified gender category; using the values from this array, you can understand which of the specified `keywords` is more popular within the related gender category; the first value in the array is provided for the first term from the `keywords` array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each gender category, and then express all other values as a percentage of the total value (100); a value of `100` is the highest popularity for the term a value of `0` means there was not enough data for this term
`male`	array	indicates gender category and contains corresponding keyword popularity values contains comparison of keyword popularity for the specified terms within the specified gender category; using the values from this array, you can understand which of the specified `keywords` is more popular within the related gender category; the first value in the array is provided for the first term from the `keywords` array, the second value is provided for the second keyword, and so on; calculation: we determine the total popularity value of all keywords within each gender category, and then express all other values as a percentage of the total value (100); a value of `100` is the highest popularity for the term a value of `0` means there was not enough data for this term

‌‌

Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-access

# Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access 
login="login" 
password="password" 
cred="$(printf ${login}:${password} | base64)" 
curl --location --request POST "https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/demography/live" 
--header "Authorization: Basic ${cred}"  
--header "Content-Type: application/json" 
--data-raw '[
    {
        "keywords": [
            "rugby",
            "cricket"
        ],
        "date_from": "2023-01-01",
        "date_to": "2024-01-01",
        "type": "web",
        "location_name": "United States"
    }
]'

<?php
// You can download this file from here https://cdn.dataforseo.com/v3/examples/php/php_RestClient.zip
require('RestClient.php');
$api_url = 'https://api.dataforseo.com/';
try {
	// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
	$client = new RestClient($api_url, null, 'login', 'password');
} catch (RestClientException $e) {
	echo "n";
	print "HTTP code: {$e->getHttpCode()}n";
	print "Error code: {$e->getCode()}n";
	print "Message: {$e->getMessage()}n";
	print  $e->getTraceAsString();
	echo "n";
	exit();
}
$post_array = array();
// simple way to set a task
$post_array[] = array(
	"location_name" => "United States",
	"date_from" => "2023-01-01",
	"date_to" => "2024-01-01",
	"type" => "web",
	"keywords" => array(
		"rugby",
		"cricket"
	)
);
try {
	// POST /v3/keywords_data/dataforseo_trends/demography/live
	$result = $client->post('/v3/keywords_data/dataforseo_trends/demography/live', $post_array);
	print_r($result);
	// do something with post result
} catch (RestClientException $e) {
	echo "n";
	print "HTTP code: {$e->getHttpCode()}n";
	print "Error code: {$e->getCode()}n";
	print "Message: {$e->getMessage()}n";
	print  $e->getTraceAsString();
	echo "n";
}
$client = null;
?>

const post_array = [];

post_array.push({
  "location_name": "United States",
  "date_from": "2019-01-01",
  "date_to": "2020-01-01",
  "type": "web",
  "category_code": 3,
  "keywords": ["rugby", "cricket"]
});

const axios = require('axios');

axios({
  method: 'post',
  url: 'https://api.dataforseo.com/v3/keywords_data/dataforseo_trends/demography/live',
  auth: {
    username: 'login',
    password: 'password'
  },
  data: post_array,
  headers: {
    'content-type': 'application/json'
  }
}).then(function (response) {
  var result = response['data']['tasks'];
  // Result data
  console.log(result);
}).catch(function (error) {
  console.log(error);
});

from client import RestClient
# You can download this file from here https://cdn.dataforseo.com/v3/examples/python/python_Client.zip
client = RestClient("login", "password")
post_data = dict()
# simple way to set a task
post_data[len(post_data)] = dict(
    location_name="United States",
    date_from="2023-01-01",
    date_to="2024-01-01",
    type="web",
    keywords=[
        "rugby",
        "cricket"
    ]
)
# POST /v3/keywords_data/dataforseo_trends/demography/live
# the full list of possible parameters is available in documentation
response = client.post("/v3/keywords_data/dataforseo_trends/demography/live", post_data)
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response["status_code"] == 20000:
    print(response)
    # do something with result
else:
    print("error. Code: %d Message: %s" % (response["status_code"], response["status_message"]))

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace DataForSeoDemos
{
    public static partial class Demos
    {
        public static async Task keywords_data_trends_explore_live()
        {
            var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.dataforseo.com/"),
                // Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
                DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
            };
            var postData = new List<object>();
            postData.Add(new
            {
                location_name = "United States",
                date_from = "2023-01-01",
                date_to = "2024-01-01",
                type = "web",
                keywords = new[]
                {
                    "rugby",
                    "cricket"
                }
            });
            // POST /v3/keywords_data/dataforseo_trends/demography/live
            // the full list of possible parameters is available in documentation
            var taskPostResponse = await httpClient.PostAsync("/v3/keywords_data/dataforseo_trends/demography/live", new StringContent(JsonConvert.SerializeObject(postData)));
            var result = JsonConvert.DeserializeObject(await taskPostResponse.Content.ReadAsStringAsync());
            // you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
            if (result.status_code == 20000)
            {
                // do something with result
                Console.WriteLine(result);
            }
            else
                Console.WriteLine($"error. Code: {result.status_code} Message: {result.status_message}");
        }
    }
}

The above command returns JSON structured like this:

{
    "version": "0.1.20231117",
    "status_code": 20000,
    "status_message": "Ok.",
    "time": "0.6673 sec.",
    "cost": 0.002,
    "tasks_count": 1,
    "tasks_error": 0,
    "tasks": [
        {
            "id": "03121400-1535-0574-0000-4ef65d6270b3",
            "status_code": 20000,
            "status_message": "Ok.",
            "time": "0.5907 sec.",
            "cost": 0.002,
            "result_count": 1,
            "path": [
                "v3",
                "keywords_data",
                "dataforseo_trends",
                "demography",
                "live"
            ],
            "data": {
                "api": "keywords_data",
                "function": "demography",
                "se": "dataforseo_trends",
                "keywords": [
                    "rugby",
                    "cricket"
                ],
                "date_from": "2023-01-01",
                "date_to": "2024-01-01",
                "type": "web",
                "location_name": "United States"
            },
            "result": [
                {
                    "keywords": [
                        "rugby",
                        "cricket"
                    ],
                    "type": "trends",
                    "location_code": 2840,
                    "language_code": null,
                    "datetime": "2024-03-12 12:00:40 +00:00",
                    "items_count": 1,
                    "items": [
                        {
                            "position": 1,
                            "type": "demography",
                            "keywords": [
                                "rugby",
                                "cricket"
                            ],
                            "demography": {
                                "age": [
                                    {
                                        "keyword": "rugby",
                                        "values": [
                                            {
                                                "type": "18-24",
                                                "value": 73
                                            },
                                            {
                                                "type": "25-34",
                                                "value": 87
                                            },
                                            {
                                                "type": "35-44",
                                                "value": 91
                                            },
                                            {
                                                "type": "45-54",
                                                "value": 100
                                            },
                                            {
                                                "type": "55-64",
                                                "value": 49
                                            }
                                        ]
                                    },
                                    {
                                        "keyword": "cricket",
                                        "values": [
                                            {
                                                "type": "18-24",
                                                "value": 42
                                            },
                                            {
                                                "type": "25-34",
                                                "value": 79
                                            },
                                            {
                                                "type": "35-44",
                                                "value": 100
                                            },
                                            {
                                                "type": "45-54",
                                                "value": 74
                                            },
                                            {
                                                "type": "55-64",
                                                "value": 39
                                            }
                                        ]
                                    }
                                ],
                                "gender": [
                                    {
                                        "keyword": "rugby",
                                        "values": [
                                            {
                                                "type": "female",
                                                "value": 79
                                            },
                                            {
                                                "type": "male",
                                                "value": 100
                                            }
                                        ]
                                    },
                                    {
                                        "keyword": "cricket",
                                        "values": [
                                            {
                                                "type": "female",
                                                "value": 83
                                            },
                                            {
                                                "type": "male",
                                                "value": 100
                                            }
                                        ]
                                    }
                                ]
                            },
                            "demography_comparison": {
                                "age": {
                                    "18-24": [
                                        30,
                                        70
                                    ],
                                    "25-34": [
                                        22,
                                        78
                                    ],
                                    "35-44": [
                                        18,
                                        82
                                    ],
                                    "45-54": [
                                        25,
                                        75
                                    ],
                                    "55-64": [
                                        24,
                                        76
                                    ]
                                },
                                "gender": {
                                    "female": [
                                        20,
                                        80
                                    ],
                                    "male": [
                                        20,
                                        80
                                    ]
                                }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}