Fetching Owned Posts

In this tutorial we’ll cover the basics of accessing owned social posts 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 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.

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: **********"