Skip to content

API: Shares endpoint use and overview

GET /shares/posts

Retrieve a listing of top posts by social shares across top social networks. The counting methodology is to find all posts published within the specified period (using the pub_date_start parameter), sort those by total shares across all social networks, and then return those top posts. By default only total shares are returned. To find out the number of shares within a time period, specify period_start and period_end

Optional Parameters

pub_date_startPublication filter start date; see Date/Time Handling for formatting details.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
period_startStart of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to 90 days ago, limited to most recent 90 days.
period_endEnd of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limitNumber of records to retrieve; defaults to “10”.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

GET /shares/post/detail

For a given canonical URL, return the total share counts across the top social networks. The following table shows what each integer value returned in the response contains.

KeySocial Network
twTwitter
fbFacebook
liLinkedin
piPinterest

Response document will contain a key for each social network. There is also a total key summing them for convenience. Note that some keys may not be present for older posts. In February 2018, LinkedIn turned off access to shares data from their network. In April 2023, Twitter shares were discontinued.

Query Arguments

urlCanonical URL for which share counts should be retrieved.

Optional Parameters

callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

GET /shares/(meta)/(value)/detail

Returns a list of posts falling under the specified author, section or tag.

Path Arguments

metaone of author, section, tag
valueThe value of the the author, section or tag

Optional Parameters

pub_date_startPublication filter start date; see Date/Time Handling for formatting details.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limitNumber of records to retrieve; defaults to 10.
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

Last updated: August 15, 2024