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 | |
fb | |
li | |
pi |
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
.
Last updated: August 15, 2024