Help Center

  • Fill out my online form
  • Domain Metrics By Categories: how the new endpoint works

    By calling the Domain Metrics By Categories endpoint, you can receive up to 1,000 domains relevant to the specified categories, including the dynamics of domain metrics within the indicated time frame.

    POST https://api.dataforseo.com/v3/dataforseo_labs/domain_metrics_by_categories/live

    You will receive historical ranking data from Google SERPs, along with valuable current and historical domain metrics, such as traffic volume, estimated paid traffic cost, and more.

    By providing the dynamics of changes in domain metrics, the endpoint enables you to discover how much traffic and how many ranking positions a specific domain has lost or gained over a certain time period.

    In the following paragraphs, we will provide insights into how the Domain Metrics By Categories endpoint works so that you can fully utilize its capabilities.

    Setting a task

    The Domain Metrics By Categories endpoint has 5 required fields:

    1 category_codes — product and service categories for which you want to receive a list of domains and their metrics (you can download the full list of possible categories here).

    2 first_date — first date of comparison period for which domains and metrics are provided. It should be specified in the YYYYMMDD format. Example: "first_date": "2021-06-01".

    Note: first_date cannot be greater than today’s date. The dates specified in first_date and second_date cannot point to the same month of the same year.

    You can specify the dates in any order: first_date can be greater than second_date and vice versa. The minimum date you can specify is 2020-10-01.

    3 second_date — second date of comparison period for which domains and metrics are provided. It should be specified in the YYYYMMDD format. Example: "second_date": "2021-10-01".

    Note: second_date cannot be greater than today’s date. The dates specified in first_date and second_date cannot point to the same month of the same year.

    You can specify the dates in any order: second_date can be greater than first_date and vice versa. The minimum date you can specify is 2020-10-01.

    4 location_name or location_code.

    5 language_name or language_code.

    Your basic POST request will be structured as in the following example:

    [
      {
        "location_code": 2840,
        "language_code": "en",
        "category_codes": [
          13418
        ],
        "first_date": "2021-06-01",
        "second_date": "2021-10-01"
      }
    ]

    In later paragraphs, we will walk you through more advanced parameters, but for now, let’s keep things simple and analyze the response for a basic request.

    Understanding the response

    In the API response, you will get a list of domains for the specified categories, their current metrics, and historical metrics for the indicated dates.

    {
        "version": "0.1.20210917",
        "status_code": 20000,
        "status_message": "Ok.",
        "time": "4.7066 sec.",
        "cost": 0.105,
        "tasks_count": 1,
        "tasks_error": 0,
        "tasks": [
            {
                "id": "11261146-1535-0362-0000-646ca3727739",
                "status_code": 20000,
                "status_message": "Ok.",
                "time": "4.6271 sec.",
                "cost": 0.105,
                "result_count": 1,
                "path": [
                    "v3",
                    "dataforseo_labs",
                    "domain_metrics_by_categories",
                    "live"
                ],
                "data": {
                    "api": "dataforseo_labs",
                    "function": "domain_metrics_by_categories",
                    "location_code": 2840,
                    "language_code": "en",
                    "category_codes": [
                        13418
                    ],
                    "first_date": "2021-06-01",
                    "second_date": "2021-10-01",
                    "limit": 5
                },
                "result": [
                    {
                        "categories": [
                            13418
                        ],
                        "location_code": 2840,
                        "language_code": "en",
                        "total_count": 314026,
                        "items_count": 5,
                        "items": [
                            {
                                "top_categories": [
                                    13418
                                ],
                                "organic_etv": 45904100.2760021,
                                "organic_count": 38,
                                "organic_is_lost": 10,
                                "organic_is_new": 4,
                                "domain": "www.fsbooks.com",
                                "main_domain": "fsbooks.com",
                                "metrics_history": {
                                    "202110": {
                                        "organic": {
                                            "pos_1": 4,
                                            "pos_2_3": 1,
                                            "pos_4_10": 2,
                                            "pos_11_20": 8,
                                            "pos_21_30": 4,
                                            "pos_31_40": 6,
                                            "pos_41_50": 6,
                                            "pos_51_60": 8,
                                            "pos_61_70": 7,
                                            "pos_71_80": 2,
                                            "pos_81_90": 4,
                                            "pos_91_100": 5,
                                            "etv": 56240091.361999445,
                                            "impressions_etv": 0.3295499999076128,
                                            "count": 56,
                                            "estimated_paid_traffic_cost": 45681888.22868996,
                                            "is_new": 13,
                                            "is_up": 32,
                                            "is_down": 10,
                                            "is_lost": 0
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    },
                                    "202106": {
                                        "organic": {
                                            "pos_1": 4,
                                            "pos_2_3": 0,
                                            "pos_4_10": 3,
                                            "pos_11_20": 1,
                                            "pos_21_30": 3,
                                            "pos_31_40": 5,
                                            "pos_41_50": 6,
                                            "pos_51_60": 4,
                                            "pos_61_70": 2,
                                            "pos_71_80": 5,
                                            "pos_81_90": 1,
                                            "pos_91_100": 3,
                                            "etv": 24891321.334743157,
                                            "impressions_etv": 0.14168541129827497,
                                            "count": 36,
                                            "estimated_paid_traffic_cost": 25543831.564895175,
                                            "is_new": 12,
                                            "is_up": 12,
                                            "is_down": 1,
                                            "is_lost": 9
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    }
                                },
                                "metrics_difference": {
                                    "organic": {
                                        "pos_1": 1,
                                        "pos_2_3": 1,
                                        "pos_4_10": -1,
                                        "pos_11_20": 7,
                                        "pos_21_30": 2,
                                        "pos_31_40": 1,
                                        "pos_41_50": 0,
                                        "pos_51_60": 4,
                                        "pos_61_70": 5,
                                        "pos_71_80": -3,
                                        "pos_81_90": 3,
                                        "pos_91_100": 2,
                                        "etv": 31348770.027256288,
                                        "impressions_etv": 0.18786458860933783,
                                        "count": 21,
                                        "estimated_paid_traffic_cost": 20138056.663794786,
                                        "is_new": 1,
                                        "is_up": 20,
                                        "is_down": 9,
                                        "is_lost": -9
                                    },
                                    "paid": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 0,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": 0,
                                        "pos_51_60": 0,
                                        "pos_61_70": 0,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 0,
                                        "impressions_etv": 0,
                                        "count": 0,
                                        "estimated_paid_traffic_cost": 0,
                                        "is_new": 0,
                                        "is_up": 0,
                                        "is_down": 0,
                                        "is_lost": 0
                                    },
                                    "featured_snippet": null,
                                    "local_pack": null
                                }
                            },
                            {
                                "top_categories": [
                                    13418
                                ],
                                "organic_etv": 45904083.70269999,
                                "organic_count": 67,
                                "organic_is_lost": 27,
                                "organic_is_new": 61,
                                "domain": "facba.com",
                                "main_domain": "facba.com",
                                "metrics_history": {
                                    "202110": {
                                        "organic": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 5,
                                            "pos_21_30": 6,
                                            "pos_31_40": 7,
                                            "pos_41_50": 6,
                                            "pos_51_60": 4,
                                            "pos_61_70": 5,
                                            "pos_71_80": 8,
                                            "pos_81_90": 1,
                                            "pos_91_100": 0,
                                            "etv": 81.84499886073172,
                                            "impressions_etv": 0.03717000037431717,
                                            "count": 42,
                                            "estimated_paid_traffic_cost": 38.35519281961024,
                                            "is_new": 34,
                                            "is_up": 3,
                                            "is_down": 0,
                                            "is_lost": 11
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    },
                                    "202106": {
                                        "organic": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 1,
                                            "pos_41_50": 1,
                                            "pos_51_60": 1,
                                            "pos_61_70": 1,
                                            "pos_71_80": 0,
                                            "pos_81_90": 1,
                                            "pos_91_100": 0,
                                            "etv": 1.2826395328938962,
                                            "impressions_etv": 0,
                                            "count": 5,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 1,
                                            "is_lost": 4
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    }
                                },
                                "metrics_difference": {
                                    "organic": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 0,
                                        "pos_11_20": 5,
                                        "pos_21_30": 6,
                                        "pos_31_40": 6,
                                        "pos_41_50": 5,
                                        "pos_51_60": 4,
                                        "pos_61_70": 4,
                                        "pos_71_80": 8,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 80.56235932783783,
                                        "impressions_etv": 0.03717000037431717,
                                        "count": 37,
                                        "estimated_paid_traffic_cost": 38.35519281961024,
                                        "is_new": 34,
                                        "is_up": 3,
                                        "is_down": -1,
                                        "is_lost": 7
                                    },
                                    "paid": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 0,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": 0,
                                        "pos_51_60": 0,
                                        "pos_61_70": 0,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 0,
                                        "impressions_etv": 0,
                                        "count": 0,
                                        "estimated_paid_traffic_cost": 0,
                                        "is_new": 0,
                                        "is_up": 0,
                                        "is_down": 0,
                                        "is_lost": 0
                                    },
                                    "featured_snippet": null,
                                    "local_pack": null
                                }
                            },
                            {
                                "top_categories": [
                                    13418
                                ],
                                "organic_etv": 29970000,
                                "organic_count": 1,
                                "organic_is_lost": null,
                                "organic_is_new": null,
                                "domain": "www.yahstube.com",
                                "main_domain": "yahstube.com",
                                "metrics_history": {
                                    "202110": {
                                        "organic": {
                                            "pos_1": 0,
                                            "pos_2_3": 1,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 29970000,
                                            "impressions_etv": 0,
                                            "count": 1,
                                            "estimated_paid_traffic_cost": 1691117.25,
                                            "is_new": 1,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    },
                                    "202106": {
                                        "organic": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    }
                                },
                                "metrics_difference": {
                                    "organic": {
                                        "pos_1": 0,
                                        "pos_2_3": 1,
                                        "pos_4_10": 0,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": 0,
                                        "pos_51_60": 0,
                                        "pos_61_70": 0,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 29970000,
                                        "impressions_etv": 0,
                                        "count": 1,
                                        "estimated_paid_traffic_cost": 1691117.25,
                                        "is_new": 1,
                                        "is_up": 0,
                                        "is_down": 0,
                                        "is_lost": 0
                                    },
                                    "paid": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 0,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": 0,
                                        "pos_51_60": 0,
                                        "pos_61_70": 0,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 0,
                                        "impressions_etv": 0,
                                        "count": 0,
                                        "estimated_paid_traffic_cost": 0,
                                        "is_new": 0,
                                        "is_up": 0,
                                        "is_down": 0,
                                        "is_lost": 0
                                    },
                                    "featured_snippet": null,
                                    "local_pack": null
                                }
                            },
                            {
                                "top_categories": [
                                    13418
                                ],
                                "organic_etv": 25262413.238000475,
                                "organic_count": 11,
                                "organic_is_lost": 1,
                                "organic_is_new": 1,
                                "domain": "www.mmogle.com",
                                "main_domain": "mmogle.com",
                                "metrics_history": {
                                    "202110": {
                                        "organic": {
                                            "pos_1": 0,
                                            "pos_2_3": 1,
                                            "pos_4_10": 3,
                                            "pos_11_20": 4,
                                            "pos_21_30": 2,
                                            "pos_31_40": 1,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 13462216.243000206,
                                            "impressions_etv": 0,
                                            "count": 12,
                                            "estimated_paid_traffic_cost": 16128294.129425466,
                                            "is_new": 2,
                                            "is_up": 4,
                                            "is_down": 6,
                                            "is_lost": 5
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    },
                                    "202106": {
                                        "organic": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 5,
                                            "pos_11_20": 4,
                                            "pos_21_30": 2,
                                            "pos_31_40": 1,
                                            "pos_41_50": 1,
                                            "pos_51_60": 2,
                                            "pos_61_70": 2,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 1,
                                            "etv": 2009.7753101305364,
                                            "impressions_etv": 0,
                                            "count": 17,
                                            "estimated_paid_traffic_cost": 8105.116276218943,
                                            "is_new": 4,
                                            "is_up": 7,
                                            "is_down": 1,
                                            "is_lost": 5
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    }
                                },
                                "metrics_difference": {
                                    "organic": {
                                        "pos_1": 0,
                                        "pos_2_3": 1,
                                        "pos_4_10": -2,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": -1,
                                        "pos_51_60": -2,
                                        "pos_61_70": -2,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": -1,
                                        "etv": 13460206.467690075,
                                        "impressions_etv": 0,
                                        "count": -5,
                                        "estimated_paid_traffic_cost": 16120189.013149247,
                                        "is_new": -2,
                                        "is_up": -3,
                                        "is_down": 5,
                                        "is_lost": -1
                                    },
                                    "paid": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 0,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": 0,
                                        "pos_51_60": 0,
                                        "pos_61_70": 0,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 0,
                                        "impressions_etv": 0,
                                        "count": 0,
                                        "estimated_paid_traffic_cost": 0,
                                        "is_new": 0,
                                        "is_up": 0,
                                        "is_down": 0,
                                        "is_lost": 0
                                    },
                                    "featured_snippet": null,
                                    "local_pack": null
                                }
                            },
                            {
                                "top_categories": [
                                    13418
                                ],
                                "organic_etv": 20673062.80290506,
                                "organic_count": 150,
                                "organic_is_lost": 50,
                                "organic_is_new": 59,
                                "domain": "www.mailmartusa.com",
                                "main_domain": "mailmartusa.com",
                                "metrics_history": {
                                    "202110": {
                                        "organic": {
                                            "pos_1": 3,
                                            "pos_2_3": 0,
                                            "pos_4_10": 6,
                                            "pos_11_20": 12,
                                            "pos_21_30": 10,
                                            "pos_31_40": 26,
                                            "pos_41_50": 22,
                                            "pos_51_60": 28,
                                            "pos_61_70": 22,
                                            "pos_71_80": 22,
                                            "pos_81_90": 20,
                                            "pos_91_100": 13,
                                            "etv": 216.35684056393802,
                                            "impressions_etv": 21.58559979405254,
                                            "count": 183,
                                            "estimated_paid_traffic_cost": 294.48714182991534,
                                            "is_new": 78,
                                            "is_up": 50,
                                            "is_down": 40,
                                            "is_lost": 101
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    },
                                    "202106": {
                                        "organic": {
                                            "pos_1": 3,
                                            "pos_2_3": 0,
                                            "pos_4_10": 4,
                                            "pos_11_20": 16,
                                            "pos_21_30": 16,
                                            "pos_31_40": 17,
                                            "pos_41_50": 22,
                                            "pos_51_60": 22,
                                            "pos_61_70": 25,
                                            "pos_71_80": 19,
                                            "pos_81_90": 14,
                                            "pos_91_100": 13,
                                            "etv": 101.52650393724082,
                                            "impressions_etv": 10.027975080675601,
                                            "count": 171,
                                            "estimated_paid_traffic_cost": 291.12712890185685,
                                            "is_new": 43,
                                            "is_up": 48,
                                            "is_down": 30,
                                            "is_lost": 76
                                        },
                                        "paid": {
                                            "pos_1": 0,
                                            "pos_2_3": 0,
                                            "pos_4_10": 0,
                                            "pos_11_20": 0,
                                            "pos_21_30": 0,
                                            "pos_31_40": 0,
                                            "pos_41_50": 0,
                                            "pos_51_60": 0,
                                            "pos_61_70": 0,
                                            "pos_71_80": 0,
                                            "pos_81_90": 0,
                                            "pos_91_100": 0,
                                            "etv": 0,
                                            "impressions_etv": 0,
                                            "count": 0,
                                            "estimated_paid_traffic_cost": 0,
                                            "is_new": 0,
                                            "is_up": 0,
                                            "is_down": 0,
                                            "is_lost": 0
                                        },
                                        "featured_snippet": null,
                                        "local_pack": null
                                    }
                                },
                                "metrics_difference": {
                                    "organic": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 3,
                                        "pos_11_20": -4,
                                        "pos_21_30": -7,
                                        "pos_31_40": 8,
                                        "pos_41_50": 0,
                                        "pos_51_60": 6,
                                        "pos_61_70": -4,
                                        "pos_71_80": 2,
                                        "pos_81_90": 6,
                                        "pos_91_100": 1,
                                        "etv": 114.8303366266972,
                                        "impressions_etv": 11.55762471337694,
                                        "count": 12,
                                        "estimated_paid_traffic_cost": 3.360012928058495,
                                        "is_new": 35,
                                        "is_up": 2,
                                        "is_down": 11,
                                        "is_lost": 25
                                    },
                                    "paid": {
                                        "pos_1": 0,
                                        "pos_2_3": 0,
                                        "pos_4_10": 0,
                                        "pos_11_20": 0,
                                        "pos_21_30": 0,
                                        "pos_31_40": 0,
                                        "pos_41_50": 0,
                                        "pos_51_60": 0,
                                        "pos_61_70": 0,
                                        "pos_71_80": 0,
                                        "pos_81_90": 0,
                                        "pos_91_100": 0,
                                        "etv": 0,
                                        "impressions_etv": 0,
                                        "count": 0,
                                        "estimated_paid_traffic_cost": 0,
                                        "is_new": 0,
                                        "is_up": 0,
                                        "is_down": 0,
                                        "is_lost": 0
                                    },
                                    "featured_snippet": null,
                                    "local_pack": null
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }

    Note: the API response will provide a list of domains relevant to the exact categories you indicated. Consequently, if you specify one category in a POST request, you will get domains relevant to that one category only. Domains that are relevant to two or more categories will not be included in the response. To expand the list without specifying additional categories in a POST request, you should use the top_categories_count parameter. Learn how it works in this help center guide.

    As you can see in the response above, the API provides four current metrics (organic_etv, organic_count, organic_is_lost, and organic_is_new) — all the other metrics are historical and provided for indicated dates.

    The dates you specified will be displayed in the YYYYMM format. Below them, you will find the metrics_difference parameter that provides the dynamics of domain metrics.

    As mentioned, you can specify the dates in any order: first_date can be greater than second_date and vice versa. In the API response, the first displayed date will always be the one that is greater. What’s important, when calculating metrics_difference for a domain, the API will always subtract the metrics as of the greater date from the ones as of the smaller date.

    For example, if a domain had an organic estimated traffic value (ETV) of 216.35684056393802 on 202106 and 335.55784956083563 on 202104, the metrics_difference in organic ETV would be:

    216.35684056393802 – 335.55784956083563 = -119.201008997

    The same calculation is performed for each historical metric in the response.

    Advanced parameters

    You can get more specific results by using several advanced parameters when setting a task:

    • etv_min — minimum current organic ETV of the domain. If specified, the API will return only domains with organic_etv greater than the specified value.
    • etv_max — maximum current organic ETV of the domain. If specified, the API will return only domains with organic_etv lesser than the specified value.
    • top_categories_count — number of additional domain categories. By using this parameter, you can receive domains relevant to additional categories that are not specified in category_codes. Refer to this guide to learn more.
    • include_subdomains — whether to include or exclude subdomains. If false, the API response will contain main_domain only. If true, the API will return main_domain plus its subdomains (if available). By default, the parameter is set to true.
    • item_types — indicates the type of search results included in the response. By default, the API provides data from organic and paid search. You can also receive data from featured snippets and local packs by specifying the parameter as "item_types": ["organic", "paid", "featured_snippet", "local_pack"].
    • filters — you can filter domains by using several filtering parameters. For example, you can make the API display domains that had organic impressions ETV greater than 2500 on one of the specified date: "filters": ["metrics_history.202110.organic.impressions_etv", ">", 2500]. To learn more about using filters with DataForSEO Labs API, please refer to this help center article.
    • order_by — instead of filtering domains, you can order them by different values, using the same rules as in the filters array to sort the results. Learn more in this guide.