API Documentation

BTW API Access (30-day free trial)

Authentication

BTW API endpoints require authentication, which you can do with a free trial API key. This key works across both APIs and should be included in the Authorization header of your requests.

For ongoing access to our API or to inquire about a custom endpoint, email us at support@btw.co.

Authorization: Bearer YourApiKey
Get API Key

Endpoints

GET https://btw.co/api/trends/feed sample response

Returns the current top 10 trending stories.

Query Parameters (optional)
GET https://btw.co/api/trends/feed?
include=Technology,Science
&exclude=Politics
&num=10
Where include and exclude can be any of the following category keys separated by commas: 
New,ArtsEntertainment,Business,
Culture,Law,Politics,Science,
Sports,Technology,World
Where num can be a number from 1 - 100.
Required Headers
Authorization: Bearer YourApiKey
Optional Headers
Accept: application/json

Data Dictionary

TitleThe headline or main title of the news story.
PositionThe story's rank or placement among trending stories (e.g., 1 = most viral).
PositionChangeHow much the story's global rank (before any category filtering) has changed since the last update (e.g., +2 means it moved up two spots).
ScoreA numerical value showing how viral or significant the story is based on trend signals.
CategoryKeysA list of topic categories the story belongs to (e.g., "Business," "Technology").
BodyA short paragraph summarizing the main details of the story.
KeywordsKey terms or phrases extracted from the story to help with search, tagging, or discovery.
KeyPointsA list of bullet points summarizing the most important facts or takeaways from the story.
KeyFiguresList of important people, companies, or organizations mentioned in the story (empty if none detected).
SentimentLeftA short summary of how left-leaning sources are reacting to the story.
SentimentRightA short summary of how right-leaning sources are reacting to the story.
ArticleCountThe total number of individual articles associated with the story.
ArticlesA collection of individual articles associated with the story.
QasA collection of question-and-answer pairs providing additional context, background, or analysis related to the story.
POST https://btw.co/api/trends/search sample response

Returns current and historically trending stories based on the free-text search input.

Request Body (JSON)
{ "Query": "Weather anomolies in California" }
Alternately, the query parameter can be specified as part of the query string.
GET https://btw.co/api/trends/search?
query=Weather anomolies in California
Required Headers
Authorization: Bearer YourApiKey
Optional Headers
Content-Type: application/json
Accept: application/json