Owned Social Analytics - API Quickstart

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:

Your Meltwater API token
An owned social connection configured for your Meltwater account

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"
        }
    ] 
}

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.

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

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.

Fetching posts

You can use the API to fetch the top posts for owned social accounts. You might do this to report the most engaged with posts in a period of time for example.

When calling the API you can fetch multiple posts for multiple accounts in one API call. Note the accounts must be from the same social network.

You can fetch posts by calling the GET /v3/owned/accounts/posts/top_posts endpoint.

When fetching posts you must 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 posts 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)

Optionally you can also provide any of the following parameters:

post_types: The types of the post you’d like to fetch, for example status, as a comma-separated list
sort_by: The field to sort posts by, defaults to created_at
sort_order: The direction of the sort applied, defaults to desc
page_size: The number of posts to return per page, defaults to 10, maximum of 100
page: The page number to return, default to 1

If you have a large number of posts for your accounts you can use the page_size and page parameters to paginate through these.

The API will return the top posts, ordered by your sort options for the requested time period.

Sort order options

We aim to make features across social networks, but as each network has different names for their concepts and metrics the sort order options differ per network for the Top Posts endpoint.

Sort orders of engagement_rate and created_at are supported for all networks.

In addition we support the following sort order options for each network:

Facebook: comments_count, reactions_count, shares_count
Instagram: comments_count
LinkedIn: comment_count
TikTok: comments

For example this call would fetch the top posts sorted by descending engagement_rate, for a single Facebook account, for the first week of December 2021.

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

The response will be similar to the following:

{
    "count": 9,
    "page": 1,
    "page_size": 10,
    "posts": [
        {
            "post_id": "12345678945687853_4619537758143245",
            "post_type": "status",
            "url": "https://www.facebook.com/12345678945687853/posts/4619537758143245/",
            "content": "Example post content",
            "media_url": "",
            "tags": [
                "My Tag",
                "My Other Tag"
            ],
            "metrics": {
                "comments_count": 3,
                "post_impressions_organic_unique": 6,
                ...
            },
            "account": {
                "source": "facebook",
                "id": "12345678945687853",
                "name": "My Facebook Account"
            },
            "created_at": "2021-12-07T17:50:01+0000"
        },
        ...
    ]
}

The count field in the response tells you how many posts are available for the accounts in the timeframe.

For each post the API returns:

The ID, type and URL for the post
When the post was created
The account which the post belongs to
All available metrics for the post

Note that the post metrics available will vary by social network. These are documented on the Social Analytics Metrics page.

Filtering using Tags

The top_posts endpoint allows you to filter results based on tags users have applied to posts in the Meltwater application. For instance users may tag posts for a particular campaign.

To results to specific tags use the following parameters for the endpoint:

tag: The tag(s) to filter to. You can provide multiple values, as in the example below.
match_all_tags: Set to true if you want posts to match all tags you provide, or false to match one or more of your tags. (Defaults to false.)

curl -X GET \
--url "https://api.meltwater.com/v3/owned/accounts/posts/top_posts?source=facebook&account_ids=12345678945687853&start=2021-12-06&end=2021-12-12&tag=MyTag&tag=MyOtherTag" \
--header "Accept: application/json" \
--header "apikey: **********"

MELTWATER API

Your account

Analyst guides

Developer guides

API reference

Help

Owned Social Analytics - API Quickstart

Before you start

Authentication

Fetching your connected accounts

Fetching numeric account metrics

Understanding which metrics are available

Making an API call

Fetching demographic analytics

Fetching breakdown metrics

Fetching nested-breakdown metrics

Fetching heatmap metrics

Fetching posts

Filtering using Tags

Table of contents