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_start	Publication filter start date; see Date/Time Handling for formatting details.
pub_date_end	Publication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
period_start	Start 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_end	End of date range to consider traffic from; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limit	Number of records to retrieve; defaults to “10”.
page	Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callback	JSON-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.

Key	Social Network
tw	Twitter
fb	Facebook
li	Linkedin
pi	Pinterest

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

url	Canonical URL for which share counts should be retrieved.

Optional Parameters

callback	JSON-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

meta	one of author, section, tag
value	The value of the the author, section or tag

Optional Parameters

pub_date_start	Publication filter start date; see Date/Time Handling for formatting details.
pub_date_end	Publication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limit	Number of records to retrieve; defaults to 10.
page	Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
callback	JSON-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.