Fetching Owned Analytics

In this tutorial we’ll cover the basics of accessing owned social analytics features using the API.

Note that you need access to the Meltwater API, plus Engage or Social Analytics features in the Meltwater application to use these features.

Before you start

To run through this tutorial, you will need:

Authentication

To call any of the endpoints in this guide you need to provide your API token as a header called apikey, for example:

curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"

For full details take a look at the Authentication page.

Fetching your connected accounts

When calling the API to fetch owned social analytics you must provide the account IDs you would like data for.

You can fetch your list of accounts by calling the GET /v3/owned/accounts endpoint:

curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The response will be similar to the following:

{
    "count": 10,
    "accounts": [
        {
            "id": "12345678945687853",
            "name": "My Facebook account",
            "logo": "http://...",
            "source": "facebook"
        },
        {
            "id": "12345678945687234",
            "name": "My Instagram account",
            "logo": "http://...",
            "source": "instagram",
            "username": "my_instagram_account"
        },
        {
            "id": "urn:li:organization:12522",
            "name": "My LinkedIn account",
            "logo": "http://...",
            "source": "linkedin",
            "username": ""
        }
    ] 
}

Here you are fetching the accounts that you have set up owned connections for in the Meltwater application. For each account you’ll see an id, which you’ll use in the account_ids parameter when fetching metrics and analytics.

All your connections are returned in this one call, regardless of the social network the connection is for.

Note that for LinkedIn, the ID of accounts is in the form urn:li:organization:<id>. You need to pass this entire string as the account ID when requesting posts and metrics.

Fetching numeric account metrics

The API supports a number of account-level metrics. You can fetch these metrics to report the performance of your owned social accounts.

First we’ll take a look at ‘numeric’ metrics (basic metrics like the number of page fans), later in the guide we’ll look at demographic metrics and analytics.

Understanding which metrics are available

The metrics available for each of your accounts depends on the social network they belong to, currently supported networks include:

  • Facebook
  • Instagram
  • LinkedIn
  • X
  • Tiktok

As we expect this list to grow over time, we provide a full list of metrics per network on the Social Analytics Metrics page. Metrics on this page are listed by source, then whether they are account-level or post-level, and finally by type.

You can also call the GET /v3/owned/supported_metrics endpoint to programmatically fetch the list of supported metrics.

Making an API call

You can fetch numeric account metrics by calling the GET /v3/owned/accounts/metrics/numeric endpoint.

Note this endpoint only supports int and float account metrics. There are separate endpoints for breakdown, nested-breakdown and heatmap typed account metrics.

When fetching account metrics you provide the following parameters:

  • source: The social network of the accounts you are requesting (for example facebook)
  • account_ids: One or more IDs of accounts you’d like metrics for (up to 10 accounts), as a comma-separated list
  • start: The start of the time period (inclusive)
  • end: The end of the time period (inclusive)
  • metrics: One or more metrics you’d like fetched (up to 10 metrics), as a comma-separated list

For example this call would fetch the page_fans metric for a single Facebook account, for the first week of December 2021.

curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/numeric?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=page_fans" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The response will be similar to the following:

{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "daily_values": [
                {
                    "date": "2021-12-06",
                    "page_fans": 350
                },
                ...
            ]
        }
    ]
}

In the response the API returns:

  • For each account requested
    • For each date in the requested time period
      • A daily value for each requested metric

Note you can request multiple metrics for multiple accounts in one API call, but the accounts must be from the same social network.

Fetching demographic analytics

In addition to simple numeric account metrics, the API also allows you to fetch demographic-breakdowns of account fans and followers.

The endpoint you need to call for a particular breakdown will depend on the metric’s type, as listed on the Social Analytics Metrics page. For example the demographics_audience_city metric is of type breakdown, so you would call the GET /v3/owned/accounts/metrics/breakdown endpoint.

All of the metrics endpoints require the same parameters:

  • source: The social network of the accounts you are requesting (for example facebook)
  • account_ids: One or more IDs of accounts you’d like metrics for (up to 10 accounts), as a comma-separated list
  • start: The start of the time period (inclusive)
  • end: The end of the time period (inclusive)
  • metrics: One or more metrics you’d like fetched (up to 10 metrics), as a comma-separated list

Fetching breakdown metrics

A ‘breakdown’ metric is an analysis that provides a single-level breakdown by a category or concept. For example, the demographics_audience_country metric breaks down the audience for a Facebook page by country.

As an example of a breakdown metric request, this call would fetch the demographics_audience_country metric for a single Facebook account, for the first week of December 2021.

curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/breakdown?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=demographics_audience_country" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The response will be similar to the following:

{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "username": "",
            "daily_values": [
                {
                    "date": "2022-01-28",
                    "demographics_audience_country": [
                        {
                            "key": "NO",
                            "key_label": "Norway",
                            "value": 591
                        },
                        ..
                    ]
                }
            ]
        }
    ]
}

The API returns for each account requested, the breakdown for each date in the requested time range.

Fetching nested-breakdown metrics

A ‘nested-breakdown’ metric is an analysis that provides a double-level breakdown by two categories or concepts. For example, the demographics_gender_age metric breaks down the audience for a Facebook page by firstly gender, then age group.

As an example of a nested-breakdown metric request, this call would fetch the demographics_gender_age metric for a single Facebook account, for the first week of December 2021.

curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/nested_breakdown?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=demographics_gender_age" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The response will be similar to the following:

{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "username": "",
            "daily_values": [
                {
                    "date": "2022-01-28",
                    "demographics_gender_age": [
                        {
                            "key": "male",
                            "subkey": "55-64",
                            "value": 591
                        },
                        ..
                    ]
                }
            ]
        }
    ]
}

The API returns for each account requested, the breakdown for each date in the requested time range.

Fetching heatmap metrics

A ‘heatmap’ metric is an analysis that provides a break down over date and time. For example, the page_fans_heatmap metric breaks down the audience for a Facebook page by how active they are each day and hour.

As an example of a heatmap metric request, this call would fetch the page_fans_heatmap metric for a single Facebook account, for the first week of December 2021.

curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/heatmap?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=page_fans_heatmap" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The response will be similar to the following:

{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "username": "",
            "daily_values": [
                {
                    "date": "2022-01-28",
                    "page_fans_heatmap": [
                        {
                            "hour": 0,
                            "value": 9212
                        },
                        ..
                    ]
                }
            ]
        }
    ]
}

In this case, for each day in the requested range, the API returns an hourly value for the metric. Note that the time is always in PST timezone.