×

Request a Demo

×

Subscribe

 Shareablee

Home Resources Blog

API V1.4 Documentation

About API v1.4

The Shareablee API is offered to clients to integrate with Shareablee's metrics data. This specifies the technical details for implementation.

This version of the api can be accessed at: http://api.shareablee.com/v1.4/

Authentication

Each call must be authenticated with HTTP Basic AUTH using your API token. The token is generated by doing this following steps:

  • Get api key and secret from you account representative
  • Encode your api key and secret into base64 using the format api_key:secret (joined with a colon)

The output of the base64 encoding of the api key and secret is the API token for querying the api.

Example:

curl "http://api.shareablee.com/v1.4/me/" -H "Authorization: Basic {API TOKEN}"

Where {API TOKEN} is replaced by your API token generated above

Read Only

The API is read-only and can be interacted with using GET requests only.

Errors

Any calls that return an error will return the appropriate HTTP code and a human readable message.

Throttling

Each API token and IP address are limited to 5 requests per second. Rate limited requests return HTTP 429 "Too many requests" with a json response "Rate limit exceeded. Please try again later."

Notes

Realtime: Some endpoints have realtime variants or are only available with realtime data. If you are interested in retrieving realtime data from our Public API, please contact your account representative for information for realtime access.

Must Do's and Don'ts

Must Dos's:

  • Your application must be submitted for approval before release to production. Please contact api@shareablee.com for more information.
  • Your application submission must include a brief but clear use-case for each endpoint used and screen shots of how data is presented in your application (if applicable).
  • You may not request, collect, and/or store any personal data which may include social URLs, labels, userIDs, friendly names or handles, this is Personal Data subject to GDPR.

Don'ts:

  • Applications may not attempt to access endpoints or data which is not expressly licensed.
  • You may not enumerate dictionary contents for categories not expressly licensed.
  • You may not store any Shareablee data more than 60 days.
  • Shareablee category, entity, object IDs and property names are Shareablee data and not licensed except by express agreement. You may only use this information to effect your requests for metrics or content.
  • ISINs are offered as a convenience only and follow the published ISO 6166 guidelines. Your use of ISIN's may be subject to additional terms from the numbering authority.

Resource/user/{entity_id}/{service}

The entity_id is the id associated with a page on different services. Services include facebook twitter and instagram. Each has the same interface for endpoints.

Endpoints

User Content/user/{entity_id}/{service}/content/

Returns a hash-map with 100 pieces of content for a given user identified by the entity_id.

Required field:

  • entity_id: The entity_id is the unique ID for an entity.

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • sort_ascending: Optional parameter to specify sort direction. Defaults to true if not supplied
  • page: Optional parameter to specify which page to retrieve. Page numbers are 0 based, "page=0" retrieves first page of results

Notes:

  • facebook and twitter are the only supported services at the moment
  • If a start_date or end_date is provided, both must be provided
  • start_date must be before the end_date
  • Paging will be done for you with the link provided in next_page value returned in the results hash-map

Example response:

{
    "name": "My Facebook Page",
    "object_id": 123,
    "entity_id": 123456,
    "content": [
        {
            "username": "My Facebook Page",
            "entity_id": 123456,
            "fans":1000,
            "word_count": 40,
            "post_id": 8284950382,
            "content": "The text content of the post",
            "post_url": "http://facebook.com/example/url",
            "link": "http://shareablee.com",
            "post_type": "link",
            "like_count": 42,
            "reactions_count": 55,
            "comment_count": 13,
            "share_count": 100,
            "total_actions": 168,
            "total_actions_percent_fans": 15.5,
            "native_video_views": 12,
            "impression_count": 10000,
            "impressions_percent_fans": 10,
            "created_at": "2013-07-29T00:37:26+00:00"
        }
    ],
    "next_page":
    "http://api.shareablee.com/v1.4/user/{entity_id}/user/content/?start_date={start_date}&end_date={end_date}&page=2"
}
    

Fields by Service

Facebook

        "total_actions"
        "created_time"
        "related_user_name"
        "word_count"
        "likes_count"
        "reactions_count"
        "shares_count"
        "comments_count"
        "post_id"
        "link_to_likes"
        "link"
        "content"
        "post_type"
        "native_video_views"
      

Twitter

        "user_name"
        "status_id"
        "content"
        "retweet_count"
        "like_count"
        "total_actions"
        "created_at"
        "user_id"
      

User Metrics /user/{entity_id}/{service}/metrics/

Returns a hash-map of all metrics for a given user identified by the entity_id.

Required field:

  • entity_id: The entity_id is the unique ID for an entity.

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"

Notes:

  • Expected result fields can be found below in Fields by Service.
  • If a start_date or end_date is provided, both must be provided
  • start_date must be before the end_date

Example response:

{
  "entity_id": "123",
  "name": "My Facebook Page",
  "object_id": "123456",
  "metrics": {
    "call_to_website_total_actions": 12187,
    "offer_count": 0,
    "status_likes": 769,
    "status_percent_total_posts": 0.1737619461337967,
    "photo_percent_total_actions": 14.014566259706971,
    "call_to_like_percent_total_actions": 0.0,
    "call_to_like_total_actions": 0,
    "link_count": 987,
    "includes_question_count": 193,
    "question_percent_total_actions": 0.0,
    "call_to_comment_total_actions": 14284,
    "engagers_percent_male": 62.51732083330034,
    "video_shares": 27784,
    "actions_per_male_engager": 2.6499018428218606,
    "link_shares": 246726,
    "status_shares": 107,
    "photo_shares": 37437,
    "shares_percent_total_actions": 21.630625328822187,
    "frequency_day": 38.36666666666667,
    "engagers_percent_new": 67.98183980110258,
    "link_comments": 51212,
    "other_comments": 0,
    "latest_page_score": 75,
    "latest_fans": 6023945,
    "fans_by_country": [
      {
        "code": "US",
        "percent": 44.681927580571475,
        "value": 900598,
        "full_name": "United States"
      },
      {
        "code": "IN",
        "percent": 8.400728097436534,
        "value": 169323,
        "full_name": "India"
      }
    ],
    "comments_count": 61815,
    "includes_question_percent_total_actions": 13.21561932251019,
    "call_to_other_percent_total_posts": 0.4344048653344918,
    "call_to_like_count": 0,
    "call_to_website_percent_total_actions": 0.8447654280424414,
    "call_to_like_percent_total_posts": 0.0,
    "actions_per_female_engager": 2.0824284929654824,
    "shares_average": 271.115551694179,
    "question_percent_total_posts": 0.0,
    "offer_comments": 0,
    "other_count": 0,
    "call_to_website_percent_total_posts": 2.3457862728062553,
    "call_to_other_percent_total_actions": 0.363428664907403,
    "status_percent_total_actions": 0.0679305915714772,
    "call_to_other_count": 5,
    "likes_percent_total_actions": 74.08454863241163,
    "call_to_share_count": 0,
    "engagers_percent_female": 37.482679166699654,
    "link_likes": 867967,
    "other_percent_total_actions": 0.0,
    "call_to_website_count": 27,
    "likes_count": 1068780,
    "offer_percent_total_actions": 0.0,
    "question_comments": 0,
    "comments_percent_total_actions": 4.2848260387661865,
    "link_percent_total_posts": 85.75152041702867,
    "photo_percent_total_posts": 10.165073848827106,
    "video_percent_total_actions": 5.1005476730653125,
    "includes_question_total_actions": 190655,
    "status_comments": 104,
    "likes_average": 928.5664639443962,
    "question_likes": 0,
    "call_to_comment_percent_total_actions": 0.9901230306193675,
    "link_percent_total_actions": 80.81695547565624,
    "includes_question_percent_total_posts": 16.76802780191138,
    "actions_percent_female": 32.026536625936885,
    "post_count": 1151,
    "total_actions": 1442649,
    "offer_likes": 0,
    "other_shares": 0,
    "offer_percent_total_posts": 0.0,
    "question_count": 0,
    "offer_shares": 0,
    "photo_count": 117,
    "call_to_share_percent_total_posts": 0.0,
    "call_to_comment_percent_total_posts": 1.3900955690703736,
    "status_count": 2,
    "question_shares": 0,
    "video_count": 45,
    "reactions_count": 1095381,
    "actions_per_engager": 2.552124495049584,
    "comments_average": 53.70547350130322,
    "call_to_other_total_actions": 5243,
    "fan_average": 5967411.3,
    "call_to_comment_count": 16,
    "photo_comments": 6766,
    "call_to_share_percent_total_actions": 0.0,
    "total_modeled_impressions_count": 650821096,
    "other_likes": 0,
    "total_actions_percent_fans_per_post": 0.02100387297151578,
    "frequency_week": 268.56666666666666,
    "engagers_percent_returning": 32.01816019889742,
    "unique_engaged_audience": 565273,
    "shares_count": 312054,
    "video_comments": 3733,
    "photo_likes": 157978,
    "other_percent_total_posts": 0.0,
    "call_to_share_total_actions": 0,
    "total_actions_average": 1253.3874891398784,
    "actions_percent_male": 67.97346337406312,
    "video_percent_total_posts": 3.909643788010426,
    "video_likes": 42066,
    "native_video_views": 123456
  }
}
    

User Time Series /user/{entity_id}/{service}/time_series/

Returns a list of the values of the requested fields per day in date range.

Required field:

  • entity_id: The entity_id is the unique ID for an entity. service: The service is the platform i.e "facebook".

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • fields: list of metrics fields. Available fields listed below in Fields by Service.

Notes:

  • facebook and twitter are the only supported services at the moment.
  • If a start_date or end_date is provided, both must be provided.
  • start_date must be before the end_date.

Example response:

{
    "entity_id": "1234",
    "name": "The Example",
    "object_id": "1234"
    "total_actions": [
        {
            "date": "2015-12-07",
            "value": 65030
        },
        {
            "date": "2015-12-08",
            "value": 43824
        }
    ]
}
    

User Real Time Series /realtime/user/{entity_id}/{service}/time_series/

Returns a list of the values of the requested fields per day in date offset range.

Required field:

  • entity_id: The entity_id is the unique ID for an entity. service: The service is the platform i.e "facebook".

Params:

  • start_offset: Date offset from today from 0 to 6
  • end_offset: Date offset from today from 0 to 6
  • fields: list of metrics fields. Available fields listed below in Fields by Service.

Notes:

  • This endpoint is only available with realtime data for facebook and twitter services.
  • If a start_offset or end_offset is provided, both must be provided.
  • start_offset must be less than the end_date.

Example response:

{
    "entity_id": "1234",
    "name": "The Example",
    "object_id": "1234"
    "total_actions": [
        {
            "date_offset": 0,
            "value": 65030
        },
        {
            "date_offset": 1,
            "value": 43824
        }
    ]
}
    

Fields by Service

Facebook

        "total_actions"
        "likes_count"
        "shares_count"
        "comments_count"
        "post_count"
        "total_actions_percent_fans_per_post"
        "latest_page_score"
        "latest_fans"
        "total_actions_average"
        "unique_engaged_audience"
        "total_modeled_impressions_count"
        "frequency_day"
        "frequency_week"
        "link_count"
        "link_percent_total_posts"
        "link_percent_total_actions"
        "other_count"
        "other_percent_total_posts"
        "other_percent_total_actions"
        "photo_count"
        "photo_percent_total_posts"
        "photo_percent_total_actions"
        "question_count"
        "question_percent_total_posts"
        "question_percent_total_actions"
        "status_count"
        "status_percent_total_posts"
        "status_percent_total_actions"
        "video_count"
        "video_percent_total_posts"
        "video_percent_total_actions"
        "call_to_website_total_actions"
        "includes_question_percent_total_actions"
        "comments_percent_total_actions"
        "offer_count"
        "call_to_comment_count"
        "photo_shares"
        "shares_percent_total_actions"
        "call_to_comment_percent_total_actions"
        "call_to_other_percent_total_posts"
        "call_to_like_count"
        "includes_question_percent_total_posts"
        "call_to_like_percent_total_actions"
        "call_to_website_percent_total_actions"
        "call_to_like_total_actions"
        "call_to_like_percent_total_posts"
        "video_shares"
        "call_to_website_count"
        "fan_average"
        "question_likes"
        "call_to_comment_total_actions"
        "call_to_share_percent_total_actions"
        "offer_likes"
        "other_shares"
        "offer_percent_total_posts"
        "shares_average"
        "link_shares"
        "other_likes"
        "offer_shares"
        "offer_comments"
        "status_likes"
        "call_to_share_percent_total_posts"
        "includes_question_count"
        "call_to_website_percent_total_posts"
        "call_to_other_percent_total_actions"
        "call_to_comment_percent_total_posts"
        "call_to_other_count"
        "likes_percent_total_actions"
        "call_to_share_count"
        "link_likes"
        "photo_comments"
        "video_comments"
        "includes_question_total_actions"
        "status_shares"
        "question_shares"
        "offer_percent_total_actions"
        "link_comments"
        "call_to_share_total_actions"
        "other_comments"
        "comments_average"
        "question_comments"
        "call_to_other_total_actions"
        "photo_likes"
        "status_comments"
        "likes_average"
        "video_likes"
        "native_video_views" *(available on User Metrics endpoint)
      

Twitter

        "followers_count"
        "retweets_count"
        "likes_count"
        "total_actions_per_tweet"
        "total_actions_percent_followers_per_tweet"
        "total_actions"
        "tweet_count"
        "unique_engaged_audience"
        "retweets_percent_total_actions"
        "likes_percent_total_actions"
        "includes_video_count"
        "includes_link_percent_total_actions"
        "includes_link_count"
        "call_to_retweet_percent_total_tweets"
        "includes_hashtag_count"
        "tweets_per_week"
        "includes_hashtag_percent_total_tweets"
        "includes_photo_percent_total_tweets"
        "call_to_retweet_percent_actions"
        "includes_link_percent_total_tweets"
        "followers_average"
        "retweets_average"
        "tweets_per_day"
        "includes_photo_total_actions"
        "includes_link_total_actions"
        "includes_photo_count"
        "includes_photo_percent_total_actions"
        "includes_hashtag_percent_total_actions"
        "likes_average"
        "includes_hashtag_total_actions"
      

Instagram

        "latest_followers"
        "likes_count"
        "comments_count"
        "total_actions_average"
        "total_actions_percent_followers_per_media"
        "total_actions"
        "media_count"
        "includes_question_percent_total_actions"
        "image_percent_total_media"
        "includes_question_total_actions"
        "includes_question_count"
        "includes_link_percent_total_media"
        "video_percent_total_media"
        "includes_link_percent_total_actions"
        "includes_link_count"
        "includes_question_percent_total_media"
        "includes_hashtag_count"
        "includes_hashtag_percent_total_media"
        "video_total_actions"
        "image_total_actions"
        "likes_percent_total_actions"
        "image_percent_total_actions"
        "video_count"
        "comments_percent_total_actions"
        "comments_average"
        "includes_hashtag_percent_total_actions"
        "includes_link_total_actions"
        "video_percent_total_actions"
        "follower_average"
        "image_count"
        "likes_average"
        "includes_hashtag_total_actions"
      

Google Plus

        "post_note_count"
        "includes_question_percent_total_post_note"
        "total_actions_per_post_note"
        "post_note_total_actions"
        "includes_question_percent_total_post_note_actions"
        "photo_percent_total_post_note"
        "post_note_per_week"
        "includes_question_count"
        "includes_link_count"
        "post_note_reshares_per_total_post_note"
        "includes_hashtag_percent_total_post_note
        "includes_hashtag_count"
        "includes_link_percent_total_post_note"
        "video_percent_total_post_note"
        "post_note_comments_count"
        "photo_count"
        "includes_hashtag_percent_total_post_note_actions"
        "post_note_plusones_per_total_post_note"
        "post_note_comments_per_total_post_note"
        "photo_percent_total_post_note_actions"
        "video_count"
        "text_percent_total_post_note"
        "video_percent_total_post_note_actions"
        "post_note_plusones_percent_total_actions"
        "text_count"
        "text_percent_total_post_note_actions"
        "post_note_plusones_count"
        "post_note_reshares_percent_total_actions"
        "post_note_reshares_count"
        "post_note_per_day"
        "post_note_comments_percent_total_actions"
      

Tumblr

        "includes_question_percent_total_actions"
        "quote_count"
        "reblogs_percent_total_actions"
        "call_to_comment_count"
        "audio_count"
        "call_to_reblog_percent_total_posts"
        "call_to_comment_percent_total_actions"
        "call_to_like_count"
        "includes_question_percent_total_posts"
        "call_to_like_percent_total_actions"
        "reblogs_count"
        "link_count"
        "call_to_like_percent_total_posts"
        "audio_percent_total_actions"
        "includes_question_count"
        "chat_percent_total_posts"
        "audio_percent_total_posts"
        "reblogs_average"
        "total_actions"
        "includes_link_percent_total_actions"
        "includes_link_count"
        "photo_percent_total_actions"
        "includes_hashtag_count"
        "photo_percent_total_posts"
        "quote_percent_total_posts"
        "total_post_count"
        "call_to_reblog_count"
        "photo_count"
        "includes_tag_count"
        "total_actions_per_post"
        "video_percent_total_actions"
        "call_to_comment_percent_total_posts"
        "answer_count"
        "likes_percent_total_actions"
        "chat_percent_total_actions"
        "includes_link_percent_total_posts"
        "likes_count"
        "video_count"
        "video_percent_total_posts"
        "includes_tag_percent_total_actions"
        "answer_percent_total_actions"
        "call_to_reblog_percent_total_actions"
        "quote_percent_total_actions"
        "likes_average"
        "link_percent_total_posts"
        "includes_tag_percent_total_posts"
        "chat_count"
        "answer_percent_total_posts"
        "includes_hashtag_percent_total_posts"
        "includes_hashtag_percent_total_actions"
      

Additional Audience Fields (Selected Partners)

        "actions_percent_male",
        "actions_percent_female",
        "actions_per_engager",
        "engagers_percent_new",
        "engagers_percent_returning",
        "actions_per_male_engager",
        "actions_per_female_engager",
        "engagers_percent_male",
        "engagers_percent_female"
      

Audience Overlap Comparison (Selected Partners)
/user/{entity_id}/{service}/overlap/comparison/property/

Returns a json object of cross engagement data on the entity_id vs the object_ids for each month and service in the time range.

Required fields:

  • entity_id: The entity_id is the unique ID for an entity.
  • service: "facebook"

Params:

  • object_id: An entity's id to use for comparison against the entity_id in the url. Pass in multiple to compare the base entity_id to more than one target. (Required)
  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-09-30"

Notes:

  • For audience_percent_overlap, '-' value represents overlap unavailable, while a '*' value represents overlap data below reporting threshold.
  • start_date must be before the end_date
  • Only data from one month will be returned, with priority given to more recent data. For example, if you request from 2015-10-01 to 2015-11-11, then only November results will be returned.

Example response:

    "entity_id": 24689,
    "end_date": "2015-10-31",
    "service": "facebook",
    "results": [
        {
            "audience_percent_overlap": 0.14,
            "entity_id": 123456,
            "name": "bar1"
            "object_id": "987654",
        },
        {
            "audience_percent_overlap": 0.7,
            "entity_id": 98765,
            "name": "bar2"
            "object_id": "123987",
        }
    ],
    "object_id": "344657882",
    "start_date": "2015-10-01",
    "name": "foo"
}

Audience Affinity Comparison (Selected Partners)
/user/{entity_id}/{service}/affinity/comparison/property/

Returns a json object of affinity data on the entity_id vs the object_ids for the lastest month in the date range.

Required fields:

  • entity_id: The entity_id is the unique ID for an entity.
  • service: Only "facebook" is currently supported.

Params:

  • object_id: An entity's id to use for comparison against the entity_id in the url. Pass in multiple to compare the base entity_id to more than one target. (Required)
  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-09-30"

Notes:

  • Earliest start date is 2015-12-01
  • start_date must be before the end_date
  • Only data from one month will be returned, with priority given to more recent data. For example, if you request from 2015-12-01 to 2016-01-31, then only January results will be returned.

Example response:

{
    "end_date": "2015-12-31",
    "service": "facebook",
    "unique_engaged_users": 202196
    "results": [
        {
            "unique_engaged_users": 8902,
            "affinity": 1.4,
            "object_id": 123456,
            "name": "bar1"
        },
        {
            "unique_engaged_users": 2741,
            "affinity": 2.7,
            "object_id": 98765,
            "name": "bar2"
        }
    ],
    "object_id": 24689,
    "start_date": "2015-12-01",
    "name": "foo"
}

Audience Overlap Ranking (Selected Partners)
/user/{entity_id}/{service}/overlap/ranking/property/

Returns a json object of property level cross engagement data for the entity_id sorted by a cross engagement metric.

Required fields:

  • entity_id: The entity_id is the unique ID for an entity.
  • service: "facebook" is the only valid choice at the moment.
  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-09-30"

Params:

  • limit: The number of results to be returned. Defaults to 25 and maximum is 100.

Notes:

  • For audience_percent_overlap, '-' value represents overlap unavailable, while a '*' value represents overlap data below reporting threshold.
  • start_date must be before the end_date
  • Only data from one month will be returned, with priority given to more recent data. For example, if you request from 2015-10-01 to 2015-11-11, then only November results will be returned.

Example response:

{
    "entity_id": 24680,
    "end_date": "2015-10-31",
    "service": "facebook",
    "results": [
        {
            "audience_percent_overlap": 6.25,
            "entity_id": 7548,
            "name": "bar1",
            "object_id": "12345"
        },
        {
            "audience_percent_overlap": 3.77,
            "entity_id": 1298,
            "name": "bar2",
            "object_id": "23456"
        },
        {
            "audience_percent_overlap": 3.66,
            "entity_id": 9746,
            "name": "bar3",
            "object_id": "34567"
        },
        {
            "audience_percent_overlap": 3.59,
            "entity_id": 6757,
            "name": "bar4",
            "object_id": "45678"
        },
        {
            "audience_percent_overlap": 3.33,
            "entity_id": 9753,
            "name": "bar5",
            "object_id": "56789"
        }
    ],
    "object_id": "129567867",
    "start_date": "2015-10-01",
    "name": "foo"
}
    

Audience Affinity Ranking (Selected Partners)
/user/{entity_id}/{service}/affinity/ranking/property/

Returns a json object of property level affinity data for the entity_id sorted by affinity.

Required fields:

  • entity_id: The entity_id is the unique ID for an entity.
  • service: Only "facebook" is currently supported.
  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-09-30"

Params:

Notes:

  • Earliest start date is 2015-12-01
  • start_date must be before the end_date
  • Only data from one month will be returned, with priority given to more recent data. For example, if you request from 2015-12-01 to 2015-01-31, then only January results will be returned.

Example response:

{
    "end_date": "2015-12-31",
    "service": "facebook",
    "unique_engaged_users": 202196
    "results": [
        {
            "unique_engaged_users": 8902,
            "affinity": 6.25,
            "name": "bar1",
            "object_id": 12345
        },
        {
            "unique_engaged_users": 2741,
            "affinity": 3.77,
            "name": "bar2",
            "object_id": 23456
        },
        {
            "unique_engaged_users": 1050,
            "affinity": 3.66,
            "name": "bar3",
            "object_id": 34567
        },
        {
            "unique_engaged_users": 30437,
            "affinity": 3.59,
            "name": "bar4",
            "object_id": 45678
        },
        {
            "unique_engaged_users": 10760,
            "affinity": 3.33,
            "name": "bar5",
            "object_id": 56789
        }
    ],
    "object_id": 24680,
    "start_date": "2015-12-01",
    "name": "foo"
}
    

Page Insights (Selected Partners)
/user/{entity_id}/{service}/insights/page/

Returns a json object of property level insights data for the entity_id.

Required fields:

  • entity_id: The entity_id is the unique ID for an entity.
  • service: Only "facebook" is currently supported.

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2017-07-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2017-07-31"
  • fields: comma separated list of metrics fields to include in response. Available fields listed below in example response.

Notes:

  • Earliest start date is 2016-01-01
  • start_date must be before the end_date
  • If no start or end date is supplied, the last 30 days will be returned

Example response:

{
  "object": {
      "start": "2017-07-20",
      "end": "2017-07-20",
      "name": "Shareablee"
  },
  "data": {
      "2017-07-20": {
          "page_impressions": 17173937,
          "page_reach": 4216734,
          "page_paid_impressions": 0,
          "page_paid_reach": 0,
          "page_organic_impressions": 11621705,
          "page_organic_reach": 1589877,
          "page_engaged_users": 536047,
          "page_consumptions": 917989,
          "page_consumers": 474220,
          "page_new_likes": 863,
          "page_unlikes": 422,
          "page_views": 7066,
          "page_viewers": 2374,
          "page_video_views": 1436417,
          "page_paid_video_views": 0,
          "page_organic_video_views": 1436417,
          "page_video_viewers": 792154,
          "page_video_30_second_views": 336755,
          "page_video_paid_30_second_views": 0,
          "page_video_organic_30_second_views": 336755,
          "page_video_30_second_viewers": 260119,
          "page_video_10_second_views": 741176,
          "page_video_paid_10_second_views": 0,
          "page_video_organic_10_second_views": 741176,
          "page_video_10_second_viewers": 510710,
          "page_consumption_video_play": 50121,
          "page_consumption_other_clicks": 643127,
          "page_consumption_photo_view": 38742,
          "page_consumption_link_clicks": 185999,
          "page_consumption_button_clicks": 0,
          "page_consumer_video_play": 46675,
          "page_consumer_other_clicks": 367592,
          "page_consumer_photo_view": 22637,
          "page_consumer_link_clicks": 147457,
          "page_consumer_button_clicks": 0,
          "page_like_total": 763765,
          "page_love_total": 97180,
          "page_wow_total": 6483,
          "page_haha_total": 4547,
          "page_sorry_total": 584,
          "page_angry_total": 902,
          "page_negative_feedback_by_type": {
              "unlike_page_clicks": 0,
              "hide_all_clicks": 324,
              "report_spam_clicks": 3,
              "xbutton_clicks": 0,
              "hide_clicks": 796
          },
          "page_positive_feedback_by_type": {
              "comment": 23797,
              "claim": 0,
              "like": 868118,
              "other": 30107,
              "link": 42513,
              "answer": 0
          }
      }
  }
}

Resource/user/{entity_id}/cross_platform

The entity_id is the id associated with a page on different services. Services include facebook twitter and instagram. Each has the same interface for endpoints.

Endpoints

Cross Platform User Info /user/{entity_id}/cross_platform/

Returns service specific information related to a given entity_id.

Required field:

  • entity_id: The entity_id is the unique ID for an entity.

Params:

  • services: List of services. i.e "facebook,twitter,instagram".

Notes:

  • facebook, twitter, and instagram are the only supported services at the moment.

Example response:

{
    "entity_id": "1234",
    "name": "The Example",
    "facebook": {
        "website": "https://facebook.com/example",
        "about": "Official Facebook page for Example.",
        "profile_picture": "https://graph.facebook.com/123/example",
        "display_name": "Example",
        "description": "Subscribe to Example",
        "link": "https://www.facebook.com/example/",
        "user_name": "TheExample",
        "object_id": "1111"
    },
    "twitter": {
        "profile_picture": "https://twitter.com/example",
        "user_name": "theexample",
        "object_id": "14587"
    },
    "instagram": {
        "user_name": "theexample",
        "object_id": "987456"
    }
}

User Cross Platform Top Content /user/{entity_id}/cross_platform/top_content/

Returns a hash-map with n pieces of top content for a given user identified by the entity_id across supported services.

Required field:

  • entity_id: The entity_id is the unique ID for an entity.

Params:

  • services: List of services to reference to find top content. i.e "facebook,twitter,instagram"
  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • limit: Integer, limits the number of results. Default is 10.

Notes:

  • Real time variant is available at /realtime/user/{entity_id}/cross_platform/top_content/
  • If a start_date or end_date is provided, both must be provided.
  • start_date must be before the end_date.
  • The highest limit that may be requested is 100.

Example response:

{
    "entity_id": "1234"
    "top_content": [
        {
            "fields": {
                "username": "My Instagram",
                "entity_id": "1234",
                "user_id": "98765",
                "total_actions": 5000,
                "content": "My Picture Content.",
                "post_id": "111",
                "link": "https://instagram.com/example",
                "created_time": "2015-12-11T00:01:00Z",
                "comments_count": 110,
                "post_type": "picture",
                "thumbnail": "http://instagr.am/example",
                "likes_count": 600
            },
            "service": "instagram"
        },
            {
            "fields": {
                "username": "mytwitter",
                "entity_id": "1234",
                "user_id": "101010",
                "total_actions": 4000,
                "content": "Tweet Message.",
                "post_id": "1009700",
                "like_count": 300,
                "post_type": "photo",
                "created_time": "2015-12-10T00:01:00Z",
                "retweet_count": 400,
                "thumbnail": "http://twitter.com/thumbnail/example"
            },
            "service": "twitter"
        },
            {
            "fields": {
                "username": "My Facebook Page",
                "shares_count": 100,
                "entity_id": "1234",
                "user_id": "1050",
                "total_actions": 500,
                "content": "Facebook Post Message.",
                "post_id": "1050_123",
                "link": "http://facebook./example",
                "created_time": "2015-12-11T00:30:00Z",
                "comments_count": 100,
                "post_type": "link",
                "thumbnail": "https://facebook.com/example/thumbnail",
                "likes_count": 9000
            },
            "service": "facebook"
        }
    ]
}

Resource/category/{category_id}/{service}

The category_id is the id associated with a category on different services. Services include facebook twitter and instagram. Each has the same interface for endpoints.

Category Member Info /category/{category_id}/{service}/

Returns service specific information related to the members from a given category_id.

Required field:

  • category_id: The category_id is the unique ID for a category. service: The service is the platform i.e "facebook".

Params:

Notes:

  • facebook, twitter, and instagram are the only supported services at the moment.

Example response:

{
    "object_id": "1234",
    "name": "My Category",
    "isin": "US1234567890",
    "members": [
        {
            "entity_id": "111",
            "name": "The Example",
            "facebook": {
            "website": "https://facebook.com/example",
            "about": "Official Facebook page for Example.",
            "profile_picture": "https://graph.facebook.com/123/example",
            "display_name": "Example",
            "description": "Subscribe to Example",
            "link": "https://www.facebook.com/example/",
            "user_name": "TheExample",
            "object_id": "4569"
            }
        },
            {
            "entity_id": "222",
            "name": "The Example",
            "facebook": {
            "website": "https://facebook.com/example",
            "about": "Official Facebook page for Example.",
            "profile_picture": "https://graph.facebook.com/123/example",
            "display_name": "Example",
            "description": "Subscribe to Example",
            "link": "https://www.facebook.com/example/",
            "user_name": "TheExample",
            "object_id": "9654"
            }
        }
    ]
}

Category Metrics /category/{category_id}/{service}/metrics/

Returns a hash-map of all metrics for a given category identified by the category_id.

Required field:

  • category_id: The category_id is the unique ID for a category.

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"

Notes:

  • Expected result fields can be found below in Fields by Service.
  • If a start_date or end_date is provided, both must be provided
  • start_date must be before the end_date

Example response:

{
  "name": "My Category",
  "object_id": "1234",
  "isin": "US1234567890",
  "metrics": {
    "call_to_website_total_actions": 8935.691308691308,
    "offer_count": 0.012987012987012988,
    "status_likes": 1626.4275724275724,
    "status_percent_total_posts": 0.5044882372497765,
    "photo_percent_total_actions": 21.44768006449263,
    "call_to_like_percent_total_actions": 0.11030859795365183,
    "call_to_like_total_actions": 529.7892107892108,
    "link_count": 278.5904095904096,
    "includes_question_count": 41.000999000999,
    "question_percent_total_actions": 0.0,
    "call_to_comment_total_actions": 1035.7892107892108,
    "engagers_percent_male": 36.94085243301642,
    "video_shares": 48325.22277722278,
    "actions_per_male_engager": 2.823125010067888,
    "link_shares": 45395.796203796206,
    "status_shares": 334.7152847152847,
    "photo_shares": 13391.16883116883,
    "shares_percent_total_actions": 22.371766543484757,
    "frequency_day": 10.917649017649017,
    "engagers_percent_new": 70.31265913887758,
    "link_comments": 13419.35064935065,
    "other_comments": 0.0,
    "latest_page_score": 67.87612387612387,
    "latest_fans": 907077.8661338661,
    "comments_count": 20894.897102897103,
    "includes_question_percent_total_actions": 9.043373088863847,
    "call_to_other_percent_total_posts": 0.4221352601896559,
    "call_to_like_count": 0.46153846153846156,
    "call_to_website_percent_total_actions": 1.8605202973839874,
    "call_to_like_percent_total_posts": 0.14091509408065103,
    "actions_per_female_engager": 2.4183695488448516,
    "shares_average": 328.05271810575954,
    "question_percent_total_posts": 0.0,
    "offer_comments": 0.01998001998001998,
    "other_count": 0.0,
    "call_to_website_percent_total_posts": 2.6401754423422408,
    "call_to_other_percent_total_actions": 0.42229040610293417,
    "status_percent_total_actions": 0.4353060631100408,
    "call_to_other_count": 1.3826173826173827,
    "likes_percent_total_actions": 73.27766014005816,
    "call_to_share_count": 0.26973026973026976,
    "engagers_percent_female": 63.059147566983576,
    "link_likes": 219250.04295704296,
    "other_percent_total_actions": 0.0,
    "call_to_website_count": 8.647352647352648,
    "likes_count": 351937.33266733267,
    "offer_percent_total_actions": 8.715377450662737e-05,
    "question_comments": 0.0,
    "comments_percent_total_actions": 4.35057331645709,
    "link_percent_total_posts": 85.05811985103261,
    "photo_percent_total_posts": 10.113250594008973,
    "video_percent_total_actions": 20.22035086728468,
    "includes_question_total_actions": 43433.43656343656,
    "status_comments": 129.54145854145855,
    "likes_average": 1074.5211174383953,
    "question_likes": 0.0,
    "call_to_comment_percent_total_actions": 0.2156639910568829,
    "link_percent_total_actions": 57.89657585133814,
    "includes_question_percent_total_posts": 12.518262535190647,
    "actions_percent_female": 59.38741225613755,
    "post_count": 327.52947052947053,
    "total_actions": 480279.16283716285,
    "offer_likes": 0.36863136863136864,
    "other_shares": 0.0,
    "offer_percent_total_posts": 0.003965143339931739,
    "question_count": 0.0,
    "offer_shares": 0.029970029970029972,
    "photo_count": 33.12387612387612,
    "call_to_share_percent_total_posts": 0.08235297706012074,
    "call_to_comment_percent_total_posts": 0.16318089898949847,
    "status_count": 1.6523476523476524,
    "question_shares": 0.0,
    "video_count": 14.149850149850149,
    "actions_per_engager": 2.6698078684494377,
    "comments_average": 63.7954718063058,
    "call_to_other_total_actions": 2028.1728271728273,
    "fan_average": 893691.9817515818,
    "call_to_comment_count": 0.5344655344655345,
    "photo_comments": 2282.262737262737,
    "call_to_share_percent_total_actions": 0.14913154841376988,
    "total_modeled_impressions_count": 90659334.34165834,
    "other_likes": 0.0,
    "total_actions_percent_fans_per_post": 0.16407994446548196,
    "frequency_week": 76.42354312354313,
    "engagers_percent_returning": 29.687340861122422,
    "unique_engaged_audience": 179892,
    "shares_count": 107446.93306693307,
    "video_comments": 5063.722277722278,
    "photo_likes": 87335.30669330669,
    "other_percent_total_posts": 0.0,
    "call_to_share_total_actions": 716.2477522477523,
    "total_actions_average": 1466.3693073504608,
    "actions_percent_male": 40.612587743862456,
    "video_percent_total_posts": 4.3201761743687035,
    "video_likes": 43725.18681318681,
    "native_video_views_average": 234567.890
  }
}
    

Category Time Series /category/{category_id}/{service}/time_series/

Returns a list of the values of the requested fields per day in date range.

Required field:

  • category_id: The category_id is the unique ID for a category. service: The service is the platform i.e "facebook".

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • fields: list of metrics fields. Available fields listed below in Fields by Service.

Notes:

  • facebook and twitter are the supported services for this endpoint.
  • If a start_date or end_date is provided, both must be provided.
  • start_date must be before the end_date.

Example response:

{
    "object_id": "1234",
    "name": "The Example",
    "total_actions": [
        {
            "date": "2015-12-07",
            "value": 65030
        },
        {
            "date": "2015-12-08",
            "value": 43824
        },
            "likes_count": [
        {
            "date": "2015-12-07",
            "value": 65030
        },
        {
            "date": "2015-12-08",
            "value": 43824
        }
    ]
}
    

Fields by Service

Facebook

        "total_actions"
        "likes_count"
        "shares_count"
        "comments_count"
        "post_count"
        "total_actions_percent_fans_per_post"
        "latest_page_score"
        "latest_fans"
        "total_actions_average"
        "unique_engaged_audience"
        "total_modeled_impressions_count"
        "frequency_day"
        "frequency_week"
        "link_count"
        "link_percent_total_posts"
        "link_percent_total_actions"
        "other_count"
        "other_percent_total_posts"
        "other_percent_total_actions"
        "photo_count"
        "photo_percent_total_posts"
        "photo_percent_total_actions"
        "question_count"
        "question_percent_total_posts"
        "question_percent_total_actions"
        "status_count"
        "status_percent_total_posts"
        "status_percent_total_actions"
        "video_count"
        "video_percent_total_posts"
        "video_percent_total_actions"
      

Twitter

        "followers_count"
        "retweets_count"
        "likes_count"
        "total_actions_per_tweet"
        "total_actions_percent_followers_per_tweet"
        "total_actions"
        "tweet_count"
        "unique_engaged_audience"
      

Instagram

        "latest_followers",
        "likes_count",
        "comments_count",
        "total_actions_average",
        "total_actions_percent_followers_per_media",
        "total_actions",
        "media_count"
      

Additional Audience Fields (Selected Partners)

        "actions_percent_male",
        "actions_percent_female",
        "actions_per_engager",
        "engagers_percent_new",
        "engagers_percent_returning",
        "actions_per_male_engager",
        "actions_per_female_engager",
        "engagers_percent_male",
        "engagers_percent_female"
      

Category Ranking /category/{category_id}/{service}/ranking/

Returns a list of category members of category_id sorted by the metric name metric.

Required field:

  • category_id: The category_id is the unique ID for a category.
  • metric: Currently only supports total_actions

Params:

  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01"

Notes:

  • Currently available for Facebook only
  • If a start_date or end_date is provided, both must be provided
  • start_date must be before the end_date

Example response:

{
    "name": "My Category",
    "object_id": "456",
    "isin": "US1234567890",
    "metric": "total_actions",
    "ranking": [
        {"name": "Property Name1", "object_id": 456, "value": 123},
        {"name": "Property Name2", "object_id": 789, "value": 112},
    ]
}
    


Resource/category/{category_id}/cross_platform

Endpoints

Category Cross Platform Member Info /category/{category_id}/cross_platform/

Returns service specific information related to the members from a given category_id.

Required field:

  • category_id: The category_id is the unique ID for a category.

Params:

  • services: List of services. i.e "facebook,twitter,instagram".

Notes:

  • facebook, twitter, and instagram are the only supported services at the moment.

Example response:

{
    "object_id": "1234",
    "name": "My Category",
    "isin": "US1234567890",
    "members": [
        {
            "entity_id": "111",
            "name": "The Example",
            "facebook": {
                "website": "https://facebook.com/example",
                "about": "Official Facebook page for Example.",
                "profile_picture": "https://graph.facebook.com/123/example",
                "display_name": "Example",
                "description": "Subscribe to Example",
                "link": "https://www.facebook.com/example/",
                "user_name": "TheExample",
                "object_id": "4569"
            }
        },
        {
            "entity_id": "222",
            "name": "The Example",
            "facebook": {
                "website": "https://facebook.com/example",
                "about": "Official Facebook page for Example.",
                "profile_picture": "https://graph.facebook.com/123/example",
                "display_name": "Example",
                "description": "Subscribe to Example",
                "link": "https://www.facebook.com/example/",
                "user_name": "TheExample",
                "object_id": "9654"
            }
        }
    ]
}

Category Cross Platform Top Content /category/{category_id}/cross_platform/top_content/

Returns a hash-map with n pieces of top content for a given category identified by the category_id across supported services.

Required field:

  • category_id: The category_id is the unique ID for a category.

Params:

  • services: List of services to reference to find top content. i.e "facebook,twitter,instagram".
  • start_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01".
  • end_date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01".
  • limit: Integer, limits the number of results. Default is 10.

Notes:

  • Real time variant is available at /realtime/user/{entity_id}/cross_platform/top_content/
  • facebook, twitter, and instagram are supported.
  • If a start_date or end_date is provided, both must be provided.
  • start_date must be before the end_date.
  • The highest limit that may be requested is 100.

Example response:

{
    "category_id": "1234"
    "top_content": [
        {
            "fields": {
                "username": "My Instagram",
                "entity_id": "1234",
                "user_id": "98765",
                "total_actions": 5000,
                "content": "My Picture Content.",
                "post_id": "111",
                "link": "https://instagram.com/example",
                "created_time": "2015-12-11T00:01:00Z",
                "comments_count": 110,
                "post_type": "picture",
                "thumbnail": "http://instagr.am/example",
                "likes_count": 600
            },
            "service": "instagram"
        },
        {
            "fields": {
                "username": "mytwitter",
                "entity_id": "4567",
                "user_id": "101010",
                "total_actions": 4000,
                "content": "Tweet Message.",
                "post_id": "1009700",
                "like_count": 300,
                "post_type": "photo",
                "created_time": "2015-12-10T00:01:00Z",
                "retweet_count": 400,
                "thumbnail": "http://twitter.com/thumbnail/example"
            },
            "service": "twitter"
        },
        {
            "fields": {
                "username": "My Facebook Page",
                "shares_count": 100,
                "entity_id": "2233",
                "user_id": "1050",
                "total_actions": 500,
                "content": "Facebook Post Message.",
                "post_id": "1050_123",
                "link": "http://facebook./example",
                "created_time": "2015-12-11T00:30:00Z",
                "comments_count": 100,
                "post_type": "link",
                "thumbnail": "https://facebook.com/example/thumbnail",
                "likes_count": 9000
            },
            "service": "facebook"
        }
    ]
}

Category Cross Platform Member Rankings /realtime/category/{category_id}/cross_platform/rankings/

Returns a hash-map with a list of ranked members for a given category identified by the category_id across supported services.

Required field:

  • category_id: The category_id is the unique ID for a category.

Params:

  • services: List of services to reference in order to rank users. i.e "facebook,twitter".
  • date: Date string in the format "{year}-{month}-{day}" i.e "2014-01-01". Default is the current day.

Notes:

  • This endpoint is only available with realtime data for facebook and twitter services.
  • Data is based on a 24 hour period up till the current time and the current or provided date.
  • Ranking is based on total_actions for a member.
  • Supports categories with members up to 100.

Example response:

{
    "category_id": 111,
    "date": "2015-11-30",
    "members": [
        {
         "entity_id": 123,
         "total_actions": 100,
         "fans": 199,
         "total_posts": 5,
         "rank": 1,
         "page_score": 26.0
        }
    ],
    "total_actions": 100,
    "fans": 199,
    "total_posts": 5
}

Resource /me

Endpoints

Properties /me/properties/

Returns a serialized list of name, entity_id pairs of properties the token can view.

Due to limitations of underlying databases "all" will be returned if access to all properties is allowed

Example response:

[
    {
    "id": "unique_id_123",
    "name": "Property 123"
    },
    {
    "id": "unique_id_456",
    "name": "Property 456"
    },
    {
    "id": "unique_id_789",
    "name": "Property 789"
    }
]
    

Categories /me/categories/

Returns a serialized list of name, category_id pairs of categories the token can view.

Due to limitations of underlying databases "all" will be returned if access to all categories is allowed

Example response:

[
    {
    "id": "unique_id_123",
    "name": "Property 123"
    },
    {
    "id": "unique_id_456",
    "name": "Property 456"
    },
    {
    "id": "unique_id_789",
    "name": "Property 789"
    }
]
    

FIND /me/find/user/ (Selected Partners)

Returns a list of names and entity ids for all names that contain the search term. Results are sorted by name length ascending (max 50).

Params:

  • term: The search term (Required)

Example response:

{
    "term": "NBA"
    "results": [
        {
            "name": "NBA",
            "object_id": 123456,
            "authorized": "true"
        },
        {
            "name": "NBA Store",
            "object_id": 234561,
            "authorized": "false"
        }
    ]
}
    

Resources

Get an API Token

Shareablee will provide you with an API key and API secret upon request. Please contact your account team to receive these..


Emergency Contact

Have an urgent question or emergency? Email us at api@shareablee.com.


What's New in v1.4?

USER METRICS

  • likes_averageis replacing favorites_average to align with the nomenclature of Twitter.
  • likes_percent_total_actionsis replacing favorites_percent_total_actions to align with the nomenclature of Twitter.

USER AUDIENCE OVERLAP COMPARISON

  • object_id was previously returning a mapping id but has been changed to return the id for that particular service (FB, TW, etc).
  • entity_id was added to return our Shareablee mapping id.

USER AUDIENCE OVERLAP RANKING

  • object_id was previously returning a mapping id but has been changed to return the id for that particular service (FB, TW, etc).
  • entity_id was added to return our Shareablee mapping id.

FIND ENDPOINT

  • /me/find/user/ was previously returning only properties that you specifically do not have access to. This has been opened up to include all properties that match the query term.
  • authorized was added as a return value to compensate for the removal of the restraint.