Welcome to the NewsWhip Developer Hub!

NewsWhip APIs give you raw access to the world’s largest and fastest human engagement database; real time data trends, aggregated data, statistics, and social engagement metrics for hundreds of millions of stories, tracked since January 1, 2014.

Use the power of NewsWhip data to create and customize your own solutions, perfectly suited to your company’s goals. In the hub you'll find the information you need to be successful with our API.

 
gethttps://api.newswhip.com/v1/region/Region/Category/Time Period
curl "https://api.newswhip.com/v1/region/World/All/24?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "articles": [
    {
      "delta_time": 292,
      "recent_fb_counts": 121080,
      "recent_tw_counts": 5186,
      "relatedStories": [
        
      ],
      "fb_data": {
        "total_engagement_count": 438712,
        "total_count_delta": 121080,
        "delta_period": 292,
        "delta_period_unit": "m",
        "fb_overperforming": 27.785593513761
      },
      "tw_data": {
        "tw_count": 31157,
        "total_count_delta": 5186,
        "delta_period": 292,
        "delta_period_unit": "m",
        "tw_overperforming": 20.063359883215
      },
      "li_data": {
        "li_count": 0,
        "total_count_delta": 0,
        "delta_period": 292,
        "delta_period_unit": "m"
      },
      "pi_data": {
        "pi_count": 22,
        "delta_period": 292,
        "delta_period_unit": "m"
      },
      "predicted_interactions": 1131719,
      "predicted_timestamp": 1522338239279,
      "uuid": "97b2ca00-31f7-11e8-be5b-ef989ddb8d11",
      "publication_timestamp": 1522179772000,
      "link": "https://www.nytimes.com/2018/03/27/opinion/nikolas-cruz-shooting-florida.html",
      "headline": "Opinion | I Tried to Befriend Nikolas Cruz. He Still Killed My Friends.",
      "excerpt": "The notion that the Parkland shootings wouldn\u2019t have occurred if students had been kinder is deeply dangerous.",
      "keywords": "Parkland Shooting,Nikolas Cruz,Marjory Stoneman Douglas,Murders and Homicides",
      "source": {
        "publisher": "nytimes.com",
        "link": "https://nytimes.com",
        "country": "United States",
        "country_code": "us"
      },
      "image_link": "https://static01.nyt.com/images/2018/03/27/opinion/27Robinson/27Robinson-facebookJumbo.jpg",
      "has_video": false,
      "nw_score": 1781.0086007513,
      "max_nw_score": 9797.2621208147,
      "topics": [
        {
          "id": 2,
          "name": "News"
        },
        {
          "id": 19,
          "name": "Opinion"
        }
      ],
      "authors": [
        "ISABELLE ROBINSON"
      ],
      "entities": [
        
      ]
    }
  ]
}
{"error":{"message":"Unknown country or region. Received: Wod","id":"2f0c0762-f0ea-4b5a-bd3e-019d259895e2"}}

Path Params

Region
string
required

Filters articles published in {region}. The region should be passed in English, using the reference data linked below.

Category
string
required

Filters articles by {category}. Note: the category (topic) should be passed in English, using the reference data linked below.

Time Period
int32
required

Filters articles published within the last {time_period} hours. Valid time_periods range from 1 up to 168 hours

Query Params

key
string
required

Your API key

size
int32

The number of results you wish to have returned in the request. The default is 150 if this is omitted. The maximum you can specify is 500.

 

To use this endpoint you will need the following reference data:

Suggest Edits

/publisher

 
gethttps://api.newswhip.com/v1/publisher/Publisher/Time Period
curl "https://api.newswhip.com/v1/publisher/nytimes.com/24?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "articles": [
    {
      "delta_time": 211,
      "recent_fb_counts": 3760,
      "recent_tw_counts": 188,
      "videos": [],
      "relatedStories": [],
      "fb_data": {
        "total_engagement_count": 48195,
        "total_count_delta": 3760,
        "delta_period": 211,
        "delta_period_unit": "m",
        "fb_overperforming": 2.884757949529689
      },
      "tw_data": {
        "tw_count": 7431,
        "total_count_delta": 188,
        "delta_period": 211,
        "delta_period_unit": "m",
        "tw_overperforming": 4.646973523569058
      },
      "li_data": {
        "li_count": 0,
        "total_count_delta": 0,
        "delta_period": 211,
        "delta_period_unit": "m"
      },
      "pi_data": {
        "pi_count": 1,
        "delta_period": 211,
        "delta_period_unit": "m"
      },
      "predicted_interactions": 74438,
      "predicted_timestamp": 1522571075969,
      "uuid": "3a4c6b20-3443-11e8-ab88-49c2dc76b82d",
      "publication_timestamp": 1522432393000,
      "link": "https://www.nytimes.com/2018/03/30/us/stephon-clark-independent-autopsy.html",
      "headline": "Stephon Clark Was Shot 8 Times Primarily in His Back, Family-Ordered Autopsy Finds",
      "excerpt": "A lawyer for the family said the findings proved that Mr. Clark could not have been moving in a threatening fashion toward Sacramento officers when they opened fire.",
      "keywords": "Stephon Clark,Police Brutality;Police Misconduct;Police Shootings",
      "source": {
        "publisher": "nytimes.com",
        "link": "https://nytimes.com",
        "country": "United States",
        "country_code": "us"
      },
      "image_link": "https://static01.nyt.com/images/2018/03/22/autossell/sacramento-schooting2/sacramento-schooting2-facebookJumbo-v2.jpg",
      "has_video": true,
      "nw_score": 280.85125702122036,
      "max_nw_score": 3212.7672437775227,
      "topics": [
        {
          "id": 2,
          "name": "News"
        },
        {
          "id": 668,
          "name": "Events"
        }
      ],
      "authors": [
        "FRANCES ROBLES"
      ],
      "entities": [
        "Sacramento",
        "Mr Clark"
      ]
    }
  ]
}
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Bad Request</title>
        <link rel="shortcut icon" href="data:image/png;">
        <style>
            html, body, pre {
                margin: 0;
                padding: 0;
                font-family: Monaco, 'Lucida Console', monospace;
                background: #ECECEC;
            }
            h1 {
                margin: 0;
                background: #AD632A;
                padding: 20px 45px;
                color: #fff;
                text-shadow: 1px 1px 1px rgba(0,0,0,.3);
                border-bottom: 1px solid #9F5805;
                font-size: 28px;
            }
            p#detail {
                margin: 0;
                padding: 15px 45px;
                background: #F6A960;
                border-top: 4px solid #D29052;
                color: #733512;
                text-shadow: 1px 1px 1px rgba(255,255,255,.3);
                font-size: 14px;
                border-bottom: 1px solid #BA7F5B;
            }
        </style>
    </head>
    <body>
        <h1>Bad Request</h1>

        <p id="detail">
            For request 'GET /api/v1/publisher/your_pubisher/your_time_period?key=DevHub' [Cannot parse parameter time as Int: For input string: &quot;null&quot;]
        </p>

    </body>
</html>

Path Params

Publisher
string
required

Any domain or subdomain. i.e. nytimes.com, blog.newswhip.com

Time Period
int32
required

Filters articles published within the last {time_period} hours. Valid time_periods range from 1 up to 168 hours

Query Params

key
string
required

Your API key.

size
int32

The number of results you wish to have returned in the request. The default is 150 if this is omitted. The maximum you can specify is 500.

 
gethttps://api.newswhip.com/v1/local/City/All/Time Period
curl "https://api.newswhip.com/v1/local/Seattle, WA/All/24?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "articles": [
    {
      "delta_time": 249,
      "recent_fb_counts": 41,
      "recent_tw_counts": 1,
      "videos": [
        "http://www.youtube.com/watch?v=2vk8T35bbQc",
        "http://www.youtube.com/watch?v=28G9VLQezVg",
        "http://www.youtube.com/watch?v=c02O4Wvo7QI",
        "http://www.youtube.com/watch?v=TuuumQ4hcDg",
        "http://www.youtube.com/watch?v=nnFZKnlQlDw"
      ],
      "relatedStories": [],
      "fb_data": {
        "total_engagement_count": 2422,
        "total_count_delta": 41,
        "delta_period": 249,
        "delta_period_unit": "m"
      },
      "tw_data": {
        "tw_count": 7,
        "total_count_delta": 1,
        "delta_period": 249,
        "delta_period_unit": "m"
      },
      "li_data": {
        "li_count": 0,
        "total_count_delta": 0,
        "delta_period": 249,
        "delta_period_unit": "m"
      },
      "pi_data": {
        "pi_count": 1,
        "delta_period": 249,
        "delta_period_unit": "m"
      },
      "predicted_interactions": 2638,
      "predicted_timestamp": 1522561756839,
      "uuid": "184c2eb0-343f-11e8-9e4c-83fcdd16cc63",
      "publication_timestamp": 1522430612000,
      "link": "http://bipartisanreport.com/2018/03/30/breaking-fbi-detains-trump-ally-at-airport-donald-feeling-robert-mueller-heat/",
      "headline": "BREAKING: FBI Detains Trump Ally At Airport - Donald Feeling Robert Mueller Heat",
      "excerpt": "The Russia investigation is continuing to proceed, whether the president and his allies are fond of the idea or not. Although the House Intelligence Committee moved to end its investigation, other lines of inquiry are still very much open. Special Counsel Robert Mueller, for instance, has proven that he will leave no stone unturned in … Continued",
      "keywords": "",
      "source": {
        "publisher": "bipartisanreport.com",
        "link": "http://bipartisanreport.com",
        "country": "United States",
        "country_code": "us"
      },
      "image_link": "http://cdn.bipartisanreport.com/wordpress/wp-content/uploads/2018/03/935503612.jpg",
      "has_video": true,
      "nw_score": 6.6169187100695535,
      "max_nw_score": 1029.80745168683,
      "topics": [
        {
          "id": 2,
          "name": "News"
        },
        {
          "id": 20,
          "name": "Politics"
        }
      ],
      "authors": [
        "Caleb Newton"
      ],
      "entities": [
        "Russia",
        "House Intelligence Committee",
        "Robert Mueller"
      ]
    }
  ]
}
{
  "error": {
    "message": "time parameter is invalid. Received: 9999999",
    "id": "7554ca00-30ab-4ba0-a472-4e533e76e59a"
  }
}

Path Params

City
string
required

Any city or local region. See below for available local regions. i.e. New York, NY, London, Toronto, Hamburg-Schleswig-Holstein.

Time Period
int32
required

Filters articles published within the last {time_period} hours. Valid time_periods range from 1 up to 168 hours

Query Params

key
string
required

Your API key.

size
int32

The number of results you wish to have returned in the request. The default is 150 if this is omitted. The maximum you can specify is 500.

 

To use this endpoint you will need the following reference data:

Suggest Edits

/trendingEntities

 
gethttps://api.newswhip.com/v1/trendingEntities
curl "https://api.newswhip.com/v1/trendingEntities?timeRange=24&q=happiness&key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "trendingEntities": [
    "Joshua Jackson",
    "Gulf Cooperation Council",
    "GCC",
    "Tiffany Trump",
    "APC",
    "Amazon Home Assistants",
    "Nobel Peace Prize",
    "BG",
    "ANI",
    "Pope Francis",
    "PCP"
  ]
}
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Bad Request</title>
        <link rel="shortcut icon" href="data:image/png;">
        <style>
            html, body, pre {
                margin: 0;
                padding: 0;
                font-family: Monaco, 'Lucida Console', monospace;
                background: #ECECEC;
            }
            h1 {
                margin: 0;
                background: #AD632A;
                padding: 20px 45px;
                color: #fff;
                text-shadow: 1px 1px 1px rgba(0,0,0,.3);
                border-bottom: 1px solid #9F5805;
                font-size: 28px;
            }
            p#detail {
                margin: 0;
                padding: 15px 45px;
                background: #F6A960;
                border-top: 4px solid #D29052;
                color: #733512;
                text-shadow: 1px 1px 1px rgba(255,255,255,.3);
                font-size: 14px;
                border-bottom: 1px solid #BA7F5B;
            }
        </style>
    </head>
    <body>
        <h1>Bad Request</h1>

        <p id="detail">
            For request 'GET /api/v1/trendingEntities?timeRange=10000000000000000&amp;q=Trump&amp;key=DevHub' [Cannot parse parameter timeRange as Int: For input string: &quot;10000000000000000&quot;]
        </p>

    </body>
</html>

Query Params

timeRange
int32
required

Searches for trending entities over the given number of hours (default=24)

q
string
required

Matches all trending entities related to the given {q}.

key
string
required

Your API key.

size
int32

The number of results you wish to have returned in the request. The default is 150 if this is omitted. The maximum you can specify is 500.

 
Suggest Edits

/articles

 
posthttps://api.newswhip.com/v1/articles
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": ["country_code:(us OR gb) AND -publisher:youtube.com AND headline:rihanna"],
    "language": "en",
    "video_only":false,
    "sort_by": "nw_max_score",
    "find_related": false,
    "size": 1
}' "https://api.newswhip.com/v1/articles?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "articles": [
    {
      "delta_time": 548,
      "recent_fb_counts": 54761,
      "recent_tw_counts": 0,
      "relatedStories": [],
      "fb_data": {
        "total_engagement_count": 1096120,
        "total_count_delta": 54761,
        "delta_period": 548,
        "delta_period_unit": "m",
        "fb_overperforming": 26.570010165941973
      },
      "tw_data": {
        "tw_count": 0,
        "total_count_delta": 0,
        "delta_period": 548,
        "delta_period_unit": "m"
      },
      "li_data": {
        "li_count": 0,
        "total_count_delta": 0,
        "delta_period": 548,
        "delta_period_unit": "m"
      },
      "pi_data": {
        "pi_count": 2,
        "delta_period": 548,
        "delta_period_unit": "m"
      },
      "predicted_interactions": 1281202,
      "predicted_timestamp": 1522319800242,
      "uuid": "3c75f3a0-309a-11e8-a52e-a128b18e226e",
      "publication_timestamp": 1521989222000,
      "link": "https://viralhatch.com/index.php/2018/03/25/90-have-no-idea-what-this-is-do-you-share-if-you-do/",
      "headline": "90% Have No Idea What This Is. Do You? SHARE if you do..",
      "excerpt": "Have you ever seen one of these?",
      "keywords": "",
      "source": {
        "publisher": "viralhatch.com",
        "link": "https://viralhatch.com",
        "country": "United States",
        "country_code": "us"
      },
      "image_link": "https://viralhatch.com/wp-content/uploads/2018/03/ghght.jpg",
      "has_video": false,
      "nw_score": 532.8919847752009,
      "max_nw_score": 5263.7731261133695,
      "topics": [],
      "authors": null,
      "entities": []
    }
  ]
}
{
  "error": {
    "message": "Fields 'foo' is not allowed for filters query!",
    "id": "6958f453-0acd-4c59-9f68-d82b42daa9f3"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

See the Notes section at the bottom of this page. The Lucene query strings section shares important considerations, including the limits to the number of filters that are allowed.

from
int32

Unix timestamp in milliseconds. Filters articles published after {from}. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before {to}. Defaults to now.

language
string

Two letter ISO 639-1 language code. Defaults to any language.

sort_by
string

See notes below.

video_only
boolean

Ignored when searching by the content_type youtube. Defaults to false.

default_fields
array of strings

Up to 3 available fields to be used filtering only by keywords (like "Barack Obama"). Defaults to headline, summary, and authors.

size
int32

Max number of articles to be returned (includes relatedStories). Defaults to 200. The maximum you can specify is 5,000.

find_related
boolean

Related stories will be collapsed when set. Ignored when searching by the content_type youtube. Defaults to true.

content_type
string

Filter by stories or youtube. Defaults to stories.

search_full_text
boolean

If you want to search the full article text, set this to true. Defaults to false.

 

To use this endpoint you will need the following reference data:

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

Naming differences

For historical reasons, the queryable fields headline and summary differ in naming from their Article counterparts link and excerpt.

Filters

The following filtering options can be used in the filters body parameter.

Field
Type
Description

headline

String

summary

String

authors

String

country_code

String

Two letter (lower case) ISO 3166 country code.

region_code

String

Available regions (lower case):

  • na North America
  • eu Europe
  • oc Oceania
  • sea South East Asia
  • sa South America
  • as Asia
  • me Middle East
  • af Africa

language

String

Supported languages are listed in Supported Languages.

categories

Number

Supported categories are listed in Topics.

publisher

String

TLD such as newswhip.com.

domain

String

Exact domain where the article was published. e.g. blog.newswhip.com.

domains

String

The possible permutations of publisher and subdomains. See this section of the data dictionary for an explanation of the difference between publisher, domain, and domains.

href

String

Search by the full url of the article eg. "href:\"https://www.coldwellbankerhomes.com/az/concho/669-county-road-8235-stanford/pid_18337473/\""

siteStructure

Handy for articles that follows a particular path on a site, e.g: to look for all articles with url follows "http://www.complex.com/tag/politics", use filter with publisher:complex.com AND siteStructure:\\/tags\\/politics or publisher:complex.com AND siteStructure:"/tags/politics" will be sufficient.

Sort By

For all content types or the stories content type

Sorts one of the following in descending order:

  • default
  • fb_total_engagement
  • fb_tw_overperforming
  • fb_overperforming
  • tw_overperforming
  • predicted_interactions
  • twitter
  • linkedin
  • fb_tw_and_li
  • fb_tw_li_and_pi
  • nw_max_score
  • created_at

The default sort_by is nw_max_score when the selected time range is <= 25h, otherwise it will be fb_tw_overperforming.

For the youtube content type

When the content_type is set to youtube, the default sort order is by created_at. You can also sort in descending order by

  • yt_likes
  • yt_views
  • yt_comments
  • yt_dislikes
  • fb_total_engagement
  • twitter
  • created_at.
 
posthttps://api.newswhip.com/v1/fbPosts
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": ["country_code:us"],
    "sort_by":"fb_likes",
    "content_type":"Status"
}' "https://api.newswhip.com/v1/fbPosts?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "fbPosts": [
    {
      "page_id": "1557825057865287",
      "page_name": "JayShettyIW",
      "post_type": "Native Video",
      "is_live_video": false,
      "fb_story": "Jay Shetty added a new episode.",
      "fb_sponsor_tags": [],
      "fb_data": {
        "total_engagement_count": 2941272,
        "total_count_delta": 116841,
        "delta_period": 493,
        "delta_period_unit": "m",
        "fb_overperforming": 11.044809337609504,
        "reactions": {
          "comments": 54114,
          "likes": 405282,
          "shares": 2362549,
          "loves": 104918,
          "wows": 13387,
          "hahas": 441,
          "sads": 500,
          "angrys": 81
        }
      },
      "uuid": "f94dab70-31c7-11e8-a52e-a128b18e226e",
      "publication_timestamp": 1522159200000,
      "link": "https://www.facebook.com/1557825057865287/posts/1995740577407064",
      "headline": "Before You Feel Pressure Watch This",
      "excerpt": "Everyone has a different clock. Wait for your time",
      "keywords": "",
      "source": {
        "publisher": "",
        "link": "http://",
        "country": "United States",
        "country_code": "us"
      },
      "image_link": "https://scontent.xx.fbcdn.net/v/t15.0-10/s720x720/27599510_1995747294073059_3197960858223247360_n.jpg?_nc_cat=0&oh=ae39d986d63f1cf2dac596d3f93cf53b&oe=5B303B2E",
      "has_video": true,
      "nw_score": 869.3953298785547,
      "max_nw_score": 16524.22956588446,
      "topics": [
        {
          "id": 285,
          "name": "Viral Sites"
        }
      ],
      "authors": null,
      "entities": []
    },
    {
      "page_id": "92304305160",
      "page_name": "Will Smith",
      "post_type": "Native Video",
      "is_live_video": false,
      "fb_story": "",
      "fb_sponsor_tags": [],
      "fb_data": {
        "total_engagement_count": 2730954,
        "total_count_delta": 30339,
        "delta_period": 683,
        "delta_period_unit": "m",
        "fb_overperforming": 8.63659222535034,
        "reactions": {
          "comments": 74647,
          "likes": 1094596,
          "shares": 849410,
          "loves": 566717,
          "wows": 4295,
          "hahas": 141110,
          "sads": 107,
          "angrys": 72
        }
      },
      "uuid": "888447c0-3044-11e8-a52e-a128b18e226e",
      "publication_timestamp": 1521993008000,
      "link": "https://www.facebook.com/92304305160/posts/10160067736600161",
      "headline": "",
      "excerpt": "#Bucketlist - Salsa Lessons from @MarcAnthony... ✔️ \n\nI just realized this is my 100th Post - Thank You All! Let’s Go Get the next 💯",
      "keywords": "",
      "source": {
        "publisher": "",
        "link": "http://",
        "country": "United States",
        "country_code": "us"
      },
      "image_link": "https://scontent.xx.fbcdn.net/v/t15.0-10/s720x720/27603910_10160067743400161_4242397347268526080_n.jpg?_nc_cat=0&oh=54bdf5c764e8fe2bfab3911e2f0474fc&oe=5B2F7118",
      "has_video": true,
      "nw_score": 227.7659232536071,
      "max_nw_score": 89325.11841407913,
      "topics": [
        {
          "id": 3,
          "name": "Entertainment"
        },
        {
          "id": 699,
          "name": "Celebrity"
        }
      ],
      "authors": null,
      "entities": []
    }
  ]
}
{
  "error": {
    "message": "Fields 'foo_field' is not allowed for filters query!",
    "id": "cdf16324-3c65-4330-9137-ea8efcf7e3a0"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

See the Notes section at the bottom of this page. The Lucene query strings section shares important considerations, including the limits to the number of filters that are allowed.

from
int32

Unix timestamp in milliseconds. Filters articles published after {from}. Defaults to 1 week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before {to}. Defaults to now.

language
string

Two letter ISO 639-1 language code. Defaults to any language.

default_fields
array of strings

Up to 3 available fields to be used when filtering only by keywords (like "Barack Obama"). Defaults to page_name and external_link. You can choose from: headline, external_link, page_id, page_name, country_code, authors, language, region_code, and summary.

size
int32

Max number of articles to be returned (includes relatedStories.) Defaults to 200. The maximum you can specify is 5,000.

content_type
string

video, live_video, link, photo, status, branded_content, event. Defaults to return all content types.

sort_by
string

Sorts by the following in descending order: default, nw_max_score, fb_overperforming, fb_total_engagement, created_at, fb_likes, fb_shares, fb_comments, fb_loves, fb_wows, fb_hahas, fb_sads, fb_angrys. The default sort_by is nw_max score when the selected time-range is <= 25h, otherwise it will be fb_overperforming.

 

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

Filters

The following filtering options can be used in the filters body parameter.

Field
Type
Description

language

String

country_code

String

Two letter (lower case) ISO 3166 country code

region_code

String

Available regions (lower case):

  • na North America
  • eu Europe
  • oc Oceania
  • sea South East Asia
  • sa South America
  • as Asia
  • me Middle East
  • af Africa

authors

String

page_id

Integer

Facebook page ID.

page_name

String

Facebook page username, usually the one that comes after ‘@’

external_link

String

The href shared inside facebook post

fb_story

String

A description generated by Facebook about an event eg. Tom shared 3 photos or John shared a link

 
posthttps://api.newswhip.com/v1/igPosts
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": ["fashion"],
    "sort_by":"ig_likes"
}' "https://api.newswhip.com/v1/igPosts?key=DevHub"
A binary file was returned

You couldn't be authenticated

[
  {
    "ig_post_type": "Image",
    "ig_link": "https://www.instagram.com/p/Bg_EOYQBdhb/",
    "ig_user_name": "rado",
    "ig_full_user_name": "Rado",
    "ig_profile_image": "https://scontent.cdninstagram.com/vp/baa959fe4cff3e1ba97e99a69805a98e/5B75BED6/t51.2885-19/10413039_1437900013135312_1271698239_a.jpg",
    "ig_filter": "Normal",
    "ig_tags": [
      "aries",
      "truestarsign",
      "true",
      "hightechceramic",
      "diamonds",
      "durable",
      "ceramic"
    ],
    "ig_likes": 58,
    "ig_comments": 2,
    "id": "405ba8a0-34d4-11e8-a52e-a128b18e226e",
    "created_at": 1522494596000,
    "instagram_id": "1747133760740382811_1349567446",
    "ig_post_text": "Blue mother-of-pearl dial, diamonds and Rado's pioneering plasma high-tech ceramic combine for a watch that's designed to stand the test of time for the Aries in your life.  #TrueStarSign #Aries #True #Diamonds #Ceramic #HighTechCeramic #Durable"
  }
]
{
  "error": {
    "message": "Fields 'foo_field' is not allowed for filters query!",
    "id": "8d7d56c7-7bab-4dd7-9795-e997a2dade11"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

See the Notes section at the bottom of this page. The Lucene query strings section shares important considerations, including the limits to the number of filters that are allowed.

from
int32

Unix timestamp in milliseconds. Filters posts published after {from}. Unix timestamp in milliseconds. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters posts published before {to}. Unix timestamp in milliseconds. Defaults to now.

language
string

Two letter ISO 639-1 language code. Defaults to any language.

default_fields
array of strings

Up to 3 available fields to be used when filtering only by keywords (like "Barack Obama"). Defaults to ig_tags and ig_post_text.

size
int32

Max number of posts to be returned. Defaults to 200. The maximum you can specify is 5,000.

content_type
string

video, images, or carousel

sort_by
string

Sorts by the following in descending order created_at, ig_likes, or ig_comments. Defaults to created_at.

 

Known issue

This API is provided for historical research purposes only. It no longer provides up to date posts or metrics. This is as a result of unplanned changes to the Instagram API in 2018.

  • For dates between 2018-03-30 and 2018-04-04 there are a reduced number of posts available via the /igPosts endpoint. Instagram engagement metrics were also refreshed less frequently than usual.
  • For dates between 2018-04-04 and 2018-04-09, and for all dates after 2018-05-01, no Instagram posts or engagement metrics are available.

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

Filters

The following filtering options can be used in the filters body parameter.

Field
Type
Description

language

String

country_code

String

Two letter (lower case) ISO 3166 country code

region_code

String

Available regions (lower case):

  • na North America
  • eu Europe
  • oc Oceania
  • sea South East Asia
  • sa South America
  • as Asia
  • me Middle East
  • af Africa

ig_post_text

String

The written content of the post.

ig_user_name

String

The handle of the Instagram user.

ig_tags

String

The hashtags used in the post.

posthttps://api.newswhip.com/v1/stats
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": ["3d printing"],
    "language" : "en",
    "sort_by" : "fb_total.sum",
    "aggregate_by" : "domain"
}' "https://api.newswhip.com/v1/stats?key=DevHub"
A binary file was returned

You couldn't be authenticated

[
  {
    "key": "globo.com",
    "stats": {
      "fb_total": {
        "count": 14389,
        "min": 0,
        "max": 305086,
        "avg": 756.6266592535965,
        "sum": 10887101,
        "sum_of_squares": 359712851941,
        "variance": 24426671.838377476,
        "std_deviation": 4942.334654632108
      },
      "twitter": {
        "count": 8336,
        "min": 1,
        "max": 3672,
        "avg": 20.574136276391556,
        "sum": 171506,
        "sum_of_squares": 108514118,
        "variance": 12594.233467344193,
        "std_deviation": 112.22403248566768
      },
      "pinterest": {
        "count": 268,
        "min": 1,
        "max": 156,
        "avg": 4.742537313432836,
        "sum": 1271,
        "sum_of_squares": 53221,
        "variance": 176.09416072621966,
        "std_deviation": 13.270047502786856
      },
      "linkedin": {
        "count": 0,
        "min": "Infinity",
        "max": "-Infinity",
        "avg": "NaN",
        "sum": 0,
        "sum_of_squares": 0,
        "variance": "NaN",
        "std_deviation": "NaN"
      }
    },
    "total": 11058607
  }
]
{
  "error": {
    "message": "List((/aggregate_by,List(ValidationError(List(error.path.missing),WrappedArray()))), (/sort_by,List(ValidationError(List(error.path.missing),WrappedArray()))))",
    "id": "7b5212d7-c1b8-46c0-beba-da916ac58960"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

See the Notes section at the bottom of this page. The Lucene query strings section shares important considerations, including the limits to the number of filters that are allowed.

from
int32

Unix timestamp in milliseconds. Filters articles published after {from}. Unix timestamp in milliseconds. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before {to}. Unix timestamp in milliseconds. Defaults to now.

language
string

Two letter ISO 639-1 language code. Defaults to any language.

sort_by
string
required

Can sort using the following fields: fb_total, twitter, pinterest, linkedin. You can use the following values count, min, max, avg, sum, sum_of_squares, variance, std_deviation. For example, fb_total.sum or pinterest.max.

default_fields
array of strings

Up to 3 available fields to be used filtering only by keywords (like "Barack Obama"). Defaults to headline, summary, and authors.

size
int32

Max number of articles to be returned (includes relatedStories). Defaults to 200. The maximum you can specify is 5,000.

find_related
boolean

Related stories will be collapsed when set. Ignored when searching by the content_type youtube. Defaults to true.

content_type
string

Filters by stories or youtube. Defaults to stories.

aggregate_by
string
required

One of (“publisher”, “domains”, “domain”, “language”, “authors”, “categories”, “country_code”). See below for information about these options.

 

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

Filtering

You can filter for any option that is available for the /articles endpoint.

Aggregation

The Data dictionary provides notes on how publisher, domain, and domains are populated with data. Please read v1/stats aggregation options to make a decision on which is an appropriate aggregation option for your use case.

Suggest Edits

/trendingEntities

 
posthttps://api.newswhip.com/v1/trendingEntities
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": [],
    "from":1481932800000,
    "to":1494975600000
}' "https://api.newswhip.com/v1/trendingEntities?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "trendingEntities": [
    "NRA",
    "House",
    "Eagles",
    "Olympic",
    "Hillary Clinton",
    "Cleveland Cavaliers",
    "Black",
    "GOP",
    "Premier League",
    "D.C",
    "NBC",
    "Golden Globes",
    "IPL",
    "NASA",
    "DACA"
  ]
}
{
  "error": {
    "message": "from/to parameter is invalid. Received: 31690708-07-05T01:46:40.000Z -> 2018-03-31T11:53:22.723Z",
    "id": "965fdc97-51ae-473d-8fe9-b15f6a9491e5"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

Choose from publisher, categories, headline, countryCode

from
int32

Unix timestamp in milliseconds. Filters articles published after {from}. Unix timestamp in milliseconds. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before {to}. Unix timestamp in milliseconds. Defaults to now.

 

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

To use this endpoint you will need the following reference data:

Notes:

  • Response time: As this endpoint is aggregating a large amount of data it can take up to 5 seconds to return a response.
  • Maximum number of results: The max number of trending entities returned is 15 but it can be less if you search is more specific.
Suggest Edits

/twitterInfluencers

 
posthttps://api.newswhip.com/v1/twitterInfluencers
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": ["country_code:us"],
    "size": 250
}' "https://api.newswhip.com/v1/twitterInfluencers?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "twitterInfluencers": [
    {
      "twitter_id": 168683422,
      "twitter_handle": "BigHitEnt",
      "likes_count": 6,
      "followers_count": 6054861,
      "following_count": 18,
      "statuses_count": 4711,
      "max_retweet_value": 90757,
      "social_referrals": [
        {
          "article_id": "43b5dc60-3140-11e8-be5b-ef989ddb8d11",
          "twitter_url": "https://twitter.com/any/status/978421147711651840",
          "favourite_count": 247379,
          "rt_count": 90757,
          "created_at": 1522108754000,
          "description": "How did they do the impossible, and crack the elusive and highly competitive American market? BTS is perhaps the most successful K-pop act of all time -- incredible when you consider the demand they've been able to generate in English-speaking markets.",
          "article_url": "https://www.forbes.com/sites/cfthomas/2018/03/26/bts-the-k-pop-group-that-finally-won-america-over/"
        }
      ]
    }
  ]
}
{
  "error": {
    "message": "Fields 'countryCode' is not allowed for filters query!",
    "id": "29d06ec3-0265-48e2-a3e4-acda03933f50"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

Choose from publisher, categories, country_code, headline, summary, region_code, language, domain.

from
int32

Unix timestamp in milliseconds. Filters articles published after {from}. Unix timestamp in milliseconds. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before {to}. Unix timestamp in milliseconds. Defaults to now.

language
string

Two letter ISO 639-1 language code. Defaults to any language.

size
int32

Number of influencers to return (max 500). Defaults to 200. The maximum you can specify is 5,000.

 

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

  • Filtering on keyword: If only a query string is passed into the filter it will search on headline, authors and summary.
  • Response time: As this endpoint is aggregating a large amount of data it can take up to 5 seconds to return a response.
Suggest Edits

/fbInfluencers

 
posthttps://api.newswhip.com/v1/fbInfluencers
curl -H "Content-Type: application/json" -X POST -d '{
    "filters": ["country_code:us"],
    "size": 250
}' "https://api.newswhip.com/v1/fbInfluencers?key=DevHub"
A binary file was returned

You couldn't be authenticated

{
  "fbInfluencers": [
    {
      "fb_page_id": 169597416843751,
      "fb_username": "StandUpAmerica",
      "about": "We reject Donald Trump's dangerous agenda.  Join us to fight back!",
      "followers_count": 1223257,
      "likes_count": 1223257,
      "profile_image": "https://scontent.xx.fbcdn.net/v/t1.0-1/p50x50/17201451_252064575263701_2807050516564195940_n.jpg?_nc_cat=0&oh=d372b746f090e6e23cf150d3d65e4406&oe=5B34EE5E",
      "max_fb_interactions": 164246,
      "social_referrals": [
        {
          "article_id": "784a01b0-2fcc-11e8-ab88-49c2dc76b82d",
          "fb_post_id": "169597416843751_466933743776782",
          "headline": "Stunning photos show how many people joined the March for Our Lives protests in cities across the US",
          "description": "Throngs of people hit the streets on Saturday in cities across the United States for the March for Our Lives protests against gun violence.",
          "fb_total_interactions": 164246,
          "created_at": 1521948383000,
          "article_url": "http://www.businessinsider.com/photos-march-for-our-lives-crowds-2018-3"
        },
        {
          "article_id": "6a731200-30ff-11e8-8010-b589f56f0c06",
          "fb_post_id": "169597416843751_467780303692126",
          "headline": "It’s official: March for Our Lives was one of the biggest youth protests since the Vietnam War",
          "description": "The preliminary crowd counts confirm the weekend’s marches and rallies were huge.",
          "fb_total_interactions": 98396,
          "created_at": 1522076814000,
          "article_url": "https://www.vox.com/policy-and-politics/2018/3/26/17160646/march-for-our-lives-crowd-size-count"
        },
        {
          "article_id": "fb0b5a00-2fa3-11e8-be5b-ef989ddb8d11",
          "fb_post_id": "169597416843751_466828240453999",
          "headline": "This Is What The March For Our Lives Looked Like From Space",
          "description": "Whoa.",
          "fb_total_interactions": 65564,
          "created_at": 1521930886000,
          "article_url": "https://www.huffingtonpost.com/entry/this-is-what-the-march-for-our-lives-looked-like-from-space_us_5ab6ae5de4b008c9e5f7dbe4"
        },
        {
          "article_id": "a72bd270-2f7b-11e8-8010-b589f56f0c06",
          "fb_post_id": "169597416843751_466628110474012",
          "headline": "Students descend on Mar-a-Lago as Trump flees thousands in DC",
          "description": "If Trump was hoping to find a safe space at his luxury resort, he's about to figure out he was sorely mistaken.",
          "fb_total_interactions": 46234,
          "created_at": 1521909111000,
          "article_url": "https://shareblue.com/march-for-our-lives-pennsylvania-avenue-to-mar-a-lago/"
        },
        {
          "article_id": "d8a9b5f0-2f9a-11e8-be5b-ef989ddb8d11",
          "fb_post_id": "169597416843751_466759080460915",
          "headline": "Organizers estimate 800K people in DC for march so far: report",
          "description": "Organizers are reporting as many as 800,000 people gathered in Washington, D.C., on Saturday afternoon for the anti-gun violence rally, NBC reported. ",
          "fb_total_interactions": 42502,
          "created_at": 1521922932000,
          "article_url": "http://thehill.com/blogs/blog-briefing-room/news/380116-organizers-estimate-800k-people-in-dc-for-march-so-far"
        },
        {
          "article_id": "a0929420-336e-11e8-8010-b589f56f0c06",
          "fb_post_id": "169597416843751_469580743512082",
          "headline": "TripAdvisor says it will stop ads for right-wing TV host Laura Ingraham after she criticized Parkland shooting survivor",
          "description": "Online travel website TripAdvisor said it will stop advertising on right-wing host Laura Ingraham's television after she attacked a victim of the February Parkland, Florida school shooting on Twitter.",
          "fb_total_interactions": 30762,
          "created_at": 1522371000000,
          "article_url": "https://www.cnbc.com/2018/03/29/tripadvisor-drops-laura-ingraham-after-she-attacked-parkland-activist.html"
        },
        {
          "article_id": "badbfa40-2f83-11e8-9e4c-83fcdd16cc63",
          "fb_post_id": "169597416843751_466707257132764",
          "headline": "Photos From the \"March for Our Lives\"",
          "description": "Hundreds of thousands of Americans are taking to the streets today in hundreds of coordinated protests, calling for lawmakers to address school safety and gun violence.",
          "fb_total_interactions": 29547,
          "created_at": 1521917356000,
          "article_url": "https://www.theatlantic.com/photo/2018/03/photos-from-the-march-for-our-lives/556454/"
        },
        {
          "article_id": "4fb29480-3394-11e8-a52e-a128b18e226e",
          "fb_post_id": "169597416843751_469517180185105",
          "headline": "Advertisers desert Ingraham over Parkland controversy",
          "description": "At least half a dozen advertisers on Laura Ingraham's primetime Fox News show pulled their support on Thursday in response to her comments mocking Parkland, Fla., shooting survivor David Hogg over his rejection from colleg",
          "fb_total_interactions": 25715,
          "created_at": 1522359516000,
          "article_url": "http://thehill.com/blogs/blog-briefing-room/news/380901-advertisers-desert-ingraham-over-parkland-controversy"
        },
        {
          "article_id": "a4caead0-3367-11e8-ab88-49c2dc76b82d",
          "fb_post_id": "169597416843751_469380743532082",
          "headline": "Laura Ingraham just lost an advertiser over David Hogg's boycott",
          "description": "Hogg is asking his nearly 600,000 Twitter followers to boycott Laura Ingraham's advertisers",
          "fb_total_interactions": 25373,
          "created_at": 1522340516000,
          "article_url": "https://news.vice.com/en_us/article/43b3md/laura-ingraham-just-lost-an-advertiser-over-david-hoggs-boycott"
        },
        {
          "article_id": "a7edffe0-31be-11e8-ab88-49c2dc76b82d",
          "fb_post_id": "169597416843751_468387043631452",
          "headline": "The US needs to borrow almost $300 billion this week",
          "description": "Uncle Sam needs to borrow a ton of money this week even as Washington engages in a trade spat with China, its biggest foreign creditor.",
          "fb_total_interactions": 25240,
          "created_at": 1522167262000,
          "article_url": "http://money.cnn.com/2018/03/27/investing/us-debt-sale-record-treasury/index.html"
        },
        {
          "article_id": "84923c60-320d-11e8-be5b-ef989ddb8d11",
          "fb_post_id": "169597416843751_468831330253690",
          "headline": "Senator asks the NRA to hand over records on foreign funding, spending",
          "description": "Sen. Ron Wyden asked the NRA to turn over detailed internal records about foreign funding it received in the past three years and how it spent that money, including whether any of it went toward influencing American elections.",
          "fb_total_interactions": 23300,
          "created_at": 1522249015000,
          "article_url": "https://www.pbs.org/newshour/nation/senator-asks-the-nra-to-hand-over-records-on-foreign-funding-spending"
        },
        {
          "article_id": "3cf26aa0-338f-11e8-be5b-ef989ddb8d11",
          "fb_post_id": "169597416843751_469560030180820",
          "headline": "E.P.A. Prepares to Roll Back Rules Requiring Cars to Be Cleaner and More Efficient",
          "description": "The Trump administration, handing automakers a victory, is preparing to announce an effort to weaken strict Obama-era pollution standards.",
          "fb_total_interactions": 12842,
          "created_at": 1522366957000,
          "article_url": "https://www.nytimes.com/2018/03/29/climate/epa-cafe-auto-pollution-rollback.html"
        }
      ]
    }
  ]
}
{
  "error": {
    "message": "Fields 'foo_field' is not allowed for filters query!",
    "id": "58a59557-b7f4-42a9-b65f-af33d666499c"
  }
}

Query Params

key
string
required

Your API key.

Body Params

filters
array of strings
required

Choose from publisher, categories, country_code, headline, summary, region_code, language, domain.

from
int32

Unix timestamp in milliseconds. Filters articles published after {from}. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before {to}. Defaults to now.

language
string

Two letter ISO 639-1 language code. Defaults to any language.

size
int32

Number of influencers to return (max 500). Defaults to 200. The maximum you can specify is 5,000.

 

Time range

The maximum range between the from and to dates in your query cannot exceed 6 months.

  • Filtering on keyword: If only a query string is passed into the filter it will search on headline, authors and summary.
  • Response time: As this endpoint is aggregating a large amount of data it can take up to 5 seconds to return a response.
Suggest Edits

About the Syndication API

 

Availability

This endpoint is only available to customers who have purchased access to the Syndication product. It is not included with a Historical (POST) API subscription.

Introduction

The NewsWhip Syndication product is a text matching service that makes it straightforward to identify uses of your content by other publishers. The Syndication API makes it possible for you to access those matches programmatically.

An example use of the Syndication service and API would be:

  • You provide a feed of stories about politics.
  • We receive the feed, and the Syndication service checks that content against the millions of sites we monitor daily.
  • You use the API to request all of the matched articles where the match rate is 70% or higher, and where the content was published in the last 24 hours.
  • The API returns a full list of all the matched articles, along with their social engagement.
  • You then show that data in a dashboard or workflow tool, which allows your team to react to the information.

Glossary

Term
Definition

Matched article

Material that has been discovered by NewsWhip and found to contain text that matches content that was originally published by you.

If your company’s name is Foo and a third party publisher’s name is Bar, this is the content that was published by Bar using Foo’s original intellectual property.

Matched content

Material that has been discovered by NewsWhip and found to contain text that matches content that was originally published by you.

If your company’s name is Foo and a third party publisher’s name is Bar, this is the content that was published by Bar using Foo’s original intellectual property.

Source article

Material provided by you in your feed, which is used by NewsWhip as the basis for finding similar content published by others.

If your company’s name is Foo and a third party publisher’s name is Bar, this is the content that was published by Foo.

Source content

Material provided by you in your feed, which is used by NewsWhip as the basis for finding similar content published by others.

If your company’s name is Foo and a third party publisher’s name is Bar, this is the content that was published by Foo.

Syndicated article

Material provided by you in your feed, which is used by NewsWhip as the basis for finding similar content published by others.

If your company’s name is Foo and a third party publisher’s name is Bar, this is the content that was published by Foo.

Syndicated content

Material provided by you in your feed, which is used by NewsWhip as the basis for finding similar content published by others.

If your company’s name is Foo and a third party publisher’s name is Bar, this is the content that was published by Foo.

Suggest Edits

/syndicatedArticles

 
posthttps://api.newswhip.com/v1/syndicatedArticles
curl -H "Content-Type: application/json" -X POST -d '{
	"filters": ["country_code: us"],
	"syndication_query": {
  	  "filters": ["Trump"],
  	  "from": 1520431594200,
  	  "to": 1520431595200
    	},
  	"size": 10,
  	"min_match_rate": 10
}' "https://api.newswhip.com/v1/syndicatedArticles?key=YOUR_KEY"
A binary file was returned

You couldn't be authenticated

{
  "match_rate": 100,
  "syndication_metadata": {
    "syndication_story_id": "12345abcde",
    "syndication_full_slug": "Lorem ipsum",
    "syndication_topics": [
      {
        "type": "your_topic",
        "value": "Some value,Another value"
      }
    ]
  },
  "fb_data": {
    "total_engagement_count": 0,
    "total_count_delta": 0,
    "delta_period": 0,
    "delta_period_unit": "m"
  },
  "tw_data": {
    "tw_count": 0,
    "total_count_delta": 0,
    "delta_period": 0,
    "delta_period_unit": "m"
  },
  "li_data": {
    "li_count": 0,
    "total_count_delta": 0,
    "delta_period": 0,
    "delta_period_unit": "m"
  },
  "pi_data": {
    "pi_count": 0,
    "delta_period": 0,
    "delta_period_unit": "m"
  },
  "predicted_interactions": 6573,
  "predicted_timestamp": 1520437526361,
  "uuid": "be4871c0-2210-11e8-9397-5b951bbaa0cb",
  "publication_timestamp": 1520431594204,
  "link": "http://www.cetusnews.com/business/US-trade-deficit-jumps-to-more-than-nine-year-high.SJkYFLoAP6_z.html",
  "headline": "US trade deficit jumps to more than nine-year high",
  "excerpt": "The Commerce Department said on Wednesday the trade gap jumped 5.0 percent to $56.6 billion.",
  "keywords": "",
  "source": {
    "publisher": "cetusnews.com",
    "link": "http://cetusnews.com",
    "country": "United States",
    "country_code": "us"
  },
  "image_link": "https://static.foxbusiness.com/foxbusiness.com/content/uploads/2018/02/2016-12-02T102401Z_1_LYNXMPECB10IF_3_CHINA-ECONOMY-TRADE-2.jpg",
  "has_video": true,
  "nw_score": 0,
  "max_nw_score": 0,
  "topics": [
    
  ],
  "authors": null,
  "entities": [
    
  ]
}
{
  "error": {
    "message": "Fields 'foo_field' is not allowed for filters query!",
    "id": "58a59557-b7f4-42a9-b65f-af33d666499c"
  }
}

Query Params

key
string
required

Your API key. The DevHub key will not work for this endpoint.

Body Params

from
int32

Unix timestamp in milliseconds. Filters articles published after. This is based on the matched article. Defaults to a week ago.

to
int32

Unix timestamp in milliseconds. Filters articles published before. This is based on the matched article. Defaults to now.

min_match_rate
int32

Set a minimum match_rate for results. Defaults to 10.

max_match_rate
int32

Set a maximum match_rate for results. Defaults to 100.

language
string

Two letter ISO 639-1 language code of the matched article. Defaults to any language.

sort_by
string

See below for sorting options.

size
int32

The number of results to return in the response. Defaults to 200. The maximum you can specify is 5,000.

filters
array of strings
required

Filters that apply to the matched article. Additional parameters that can be used to refine the data that is returned, based on the matched content properties. If no field is defined but a search string is present, the API will search for the value in headline, summary, and authors. See the Notes section at the bottom of this page. The Lucene query strings section shares important considerations, including the limits to the number of filters that are allowed.

syndication_query
object
required

Filters that apply to the source article. See below for available fields. See the Notes section at the bottom of this page. The Lucene query strings section shares important considerations, including the limits to the number of filters that are allowed.

syndication_query.filters
array of strings
required

Choose from headline, authors, summary, language, and syndication_story_id. If no field is defined but a search string is present, the API will search for the value in syndication_full_slug, summary, and syndication_story_id.

syndication_query.topics_filter
string

Same lucene query string style applied as ‘filters’. If no specific type or value is defined but a search string is present, then API will search on both “_type” and “_value” of syndication topics. The _type and _value fields are searchable.

syndication_query.from
integer

Filters articles published after. Unix timestamp in milliseconds. Defaults to a week ago.

syndication_query.to
integer

Filters articles published before. Unix timestamp in milliseconds. Defaults to now.

 

Sorting options

You can sort your results based on the following options. The sort order is always descending.

Option
Definition

created_at

The published date of the matched article.

fb_total_engagement

The total number of interactions (reactions, comments, shares) for the matched article on Facebook.

fb_tw_overperforming

The sum of Facebook and Twitter Overperforming scores,

fb_tw_and_li

The sum of Facebook, Twitter, and LinkedIn engagements.

See Known issues for an update on availability of LinkedIn data.

fb_tw_li_and_pi

The sum of Facebook, Twitter, LinkedIn and Pinterest engagements.

See Known issues for an update on availability of LinkedIn data.

linkedin

Equivalent to li_count, the total number of engagements the matched article has on LinkedIn.

See Known issues for an update on availability of LinkedIn data.

match_rate

The percentage match of the matched article with the source article.

nw_max_score

The maximum social velocity of the matched article to date.

nw_score

The current social velocity of the matched article.

predicted_interactions

The total number engagements we predict that the story will achieve on Facebook and Twitter (combined).

twitter

Equivalent to tw_count, the total number of Influencer Shares the matched article has on Twitter.

This documentation is set up so that you can play with our live API. Click Try It on any endpoint that supports it, and you'll get a real response from our API.

You can specify the parameters of your query by editing the values in the API reference. Change the values in the text boxes/dropdowns, as shown here:

The API response will appear in-line. Clicking on the metadata tab will show you what values were actually sent in the request, along with the headers in the response. If you're new to the API, this is a great way to play around with what's available and get a feel for how to craft your queries.

If you don't have an API key of your own, don't worry. We have provided a default API key in each example.