openapi: 3.1.0
info:
title: quick-start-api-formerly-get-api Articles Content API
version: '1'
servers:
- url: https://api.newswhip.com/v1
tags:
- name: Content
paths:
/search:
get:
summary: /search
description: ''
operationId: search
parameters:
- name: q
in: query
description: The keywords or phrase that you'd like to search for
required: true
schema:
type: string
default: happiness
- name: key
in: query
description: Your API key.
required: true
schema:
type: string
default: DevHub
- name: size
in: query
description: 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.
schema:
type: integer
format: int32
default: 150
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"total_match\":620,\n \"articles\": [\n {\n \"delta_time\": 263,\n \"recent_fb_counts\": 48,\n \"recent_tw_counts\": 5,\n \"relatedStories\": [\n {\n \"delta_time\": 189,\n \"recent_fb_counts\": 157,\n \"recent_tw_counts\": 0,\n \"relatedStories\": [],\n \"fb_data\": {\n \"total_engagement_count\": 351,\n \"total_count_delta\": 157,\n \"delta_period\": 189,\n \"delta_period_unit\": \"m\"\n },\n \"tw_data\": {\n \"tw_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 189,\n \"delta_period_unit\": \"m\"\n },\n \"li_data\": {\n \"li_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 189,\n \"delta_period_unit\": \"m\"\n },\n \"pi_data\": {\n \"pi_count\": 0,\n \"delta_period\": 189,\n \"delta_period_unit\": \"m\"\n },\n \"predicted_interactions\": 1162,\n \"predicted_timestamp\": 1522560805758,\n \"uuid\": \"fd7f0100-34a4-11e8-a52e-a128b18e226e\",\n \"publication_timestamp\": 1522474219000,\n \"link\": \"http://www.abc.net.au/triplej/news/musicnews/lana-del-rey-shares-sneak-peak-of-new-music-while-in-australia/9606794\",\n \"headline\": \"Lana Del Rey previews new song 'Happiness Is A Butterfly' while in Australia\",\n \"excerpt\": \"\\\"Sing it for my babies on the tourlyfe\\\"\",\n \"keywords\": \"lana del rey, preview, australia\",\n \"source\": {\n \"publisher\": \"abc.net.au\",\n \"domain\": \"abc.net.au\",\n \"link\": \"http://abc.net.au\",\n \"country\": \"Australia\",\n \"country_code\": \"au\",\n \"language\": \"en\"\n },\n \"image_link\": \"http://www.abc.net.au/cm/rimage/9335302-16x9-large.jpg?v=2\",\n \"has_video\": false,\n \"nw_score\": 52.11315038623968,\n \"max_nw_score\": 249.86289135221006,\n \"topics\": [],\n \"authors\": null,\n \"entities\": []\n }\n ]\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"error\": {\n \"message\": \"query can't be empty\",\n \"id\": \"65773da0-5e3c-4a68-bb58-eaf4ccc99a26\"\n }\n}"
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: query can't be empty
id:
type: string
example: 65773da0-5e3c-4a68-bb58-eaf4ccc99a26
deprecated: false
security: []
x-readme:
code-samples:
- language: curl
code: curl "https://api.newswhip.com/v1/search?q=happiness&key=DevHub"
samples-languages:
- curl
tags:
- Content
/articles:
post:
summary: /articles
description: ''
operationId: articles
parameters:
- name: key
in: query
description: Your API key.
required: true
schema:
type: string
default: DevHub
requestBody:
content:
application/json:
schema:
type: object
required:
- filters
properties:
filters:
type: array
description: 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.
items:
type: string
from:
type: integer
description: Unix timestamp in milliseconds. Filters articles published after {from}. Defaults to a week ago.
default: null
format: int64
to:
type: integer
description: Unix timestamp in milliseconds. Filters articles published before {to}. Defaults to now.
default: null
format: int64
language:
type: string
description: Two letter ISO 639-1 language code. Defaults to any language.
default: en
sort_by:
type: string
description: See notes below.
default: default
video_only:
type: boolean
description: Ignored when searching by the content_type youtube. Defaults to false.
default: false
default_fields:
type: array
description: Up to 3 available fields to be used filtering only by keywords (like "Barack Obama"). Defaults to `headline`, `summary`, and `authors`.
default:
- headline
- summary
- authors
items:
type: string
size:
type: integer
description: Max number of articles to be returned (includes relatedStories). Defaults to 200. The maximum you can specify is 5,000.
default: 5
format: int32
find_related:
type: boolean
description: Related stories will be collapsed when set. Ignored when searching by the content_type youtube. Defaults to `true`.
default: true
content_type:
type: string
description: Filter by `stories` or `youtube`. Defaults to `stories`.
search_full_text:
type: boolean
description: If you want to search the full article text, set this to true. Defaults to `false`.
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"total_match\":15602,\n \"articles\": [\n {\n \"delta_time\": 548,\n \"recent_fb_counts\": 54761,\n \"recent_tw_counts\": 0,\n \"relatedStories\": [],\n \"fb_data\": {\n \"total_engagement_count\": 1096120,\n \"total_count_delta\": 54761,\n \"delta_period\": 548,\n \"delta_period_unit\": \"m\",\n \"fb_overperforming\": 26.570010165941973\n },\n \"tw_data\": {\n \"tw_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 548,\n \"delta_period_unit\": \"m\"\n },\n \"li_data\": {\n \"li_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 548,\n \"delta_period_unit\": \"m\"\n },\n \"pi_data\": {\n \"pi_count\": 2,\n \"delta_period\": 548,\n \"delta_period_unit\": \"m\"\n },\n \"predicted_interactions\": 1281202,\n \"predicted_timestamp\": 1522319800242,\n \"uuid\": \"3c75f3a0-309a-11e8-a52e-a128b18e226e\",\n \"publication_timestamp\": 1521989222000,\n \"link\": \"https://viralhatch.com/index.php/2018/03/25/90-have-no-idea-what-this-is-do-you-share-if-you-do/\",\n \"headline\": \"90% Have No Idea What This Is. Do You? SHARE if you do..\",\n \"excerpt\": \"Have you ever seen one of these?\",\n \"keywords\": \"\",\n \"source\": {\n \"publisher\": \"viralhatch.com\",\n \"domain\": \"viralhatch.com\",\n \"link\": \"https://viralhatch.com\",\n \"country\": \"United States\",\n \"country_code\": \"us\",\n \"language\": \"en\" \n },\n \"image_link\": \"https://viralhatch.com/wp-content/uploads/2018/03/ghght.jpg\",\n \"has_video\": false,\n \"nw_score\": 532.8919847752009,\n \"max_nw_score\": 5263.7731261133695,\n \"topics\": [],\n \"authors\": null,\n \"entities\": []\n }\n ]\n}"
schema:
type: object
properties:
total_match:
type: integer
example: 15602
default: 0
articles:
type: array
items:
type: object
properties:
delta_time:
type: integer
example: 548
default: 0
recent_fb_counts:
type: integer
example: 54761
default: 0
recent_tw_counts:
type: integer
example: 0
default: 0
relatedStories:
type: array
fb_data:
type: object
properties:
total_engagement_count:
type: integer
example: 1096120
default: 0
total_count_delta:
type: integer
example: 54761
default: 0
delta_period:
type: integer
example: 548
default: 0
delta_period_unit:
type: string
example: m
fb_overperforming:
type: number
example: 26.570010165941973
default: 0
tw_data:
type: object
properties:
tw_count:
type: integer
example: 0
default: 0
total_count_delta:
type: integer
example: 0
default: 0
delta_period:
type: integer
example: 548
default: 0
delta_period_unit:
type: string
example: m
li_data:
type: object
properties:
li_count:
type: integer
example: 0
default: 0
total_count_delta:
type: integer
example: 0
default: 0
delta_period:
type: integer
example: 548
default: 0
delta_period_unit:
type: string
example: m
pi_data:
type: object
properties:
pi_count:
type: integer
example: 2
default: 0
delta_period:
type: integer
example: 548
default: 0
delta_period_unit:
type: string
example: m
predicted_interactions:
type: integer
example: 1281202
default: 0
predicted_timestamp:
type: integer
example: 1522319800242
default: 0
uuid:
type: string
example: 3c75f3a0-309a-11e8-a52e-a128b18e226e
publication_timestamp:
type: integer
example: 1521989222000
default: 0
link:
type: string
example: https://viralhatch.com/index.php/2018/03/25/90-have-no-idea-what-this-is-do-you-share-if-you-do/
headline:
type: string
example: 90% Have No Idea What This Is. Do You? SHARE if you do..
excerpt:
type: string
example: Have you ever seen one of these?
keywords:
type: string
example: ''
source:
type: object
properties:
publisher:
type: string
example: viralhatch.com
domain:
type: string
example: viralhatch.com
link:
type: string
example: https://viralhatch.com
country:
type: string
example: United States
country_code:
type: string
example: us
language:
type: string
example: en
image_link:
type: string
example: https://viralhatch.com/wp-content/uploads/2018/03/ghght.jpg
has_video:
type: boolean
example: false
default: true
nw_score:
type: number
example: 532.8919847752009
default: 0
max_nw_score:
type: number
example: 5263.7731261133695
default: 0
topics:
type: array
authors: {}
entities:
type: array
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"error\": {\n \"message\": \"Fields 'foo' is not allowed for filters query!\",\n \"id\": \"6958f453-0acd-4c59-9f68-d82b42daa9f3\"\n }\n}"
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: Fields 'foo' is not allowed for filters query!
id:
type: string
example: 6958f453-0acd-4c59-9f68-d82b42daa9f3
deprecated: false
security: []
x-readme:
code-samples:
- language: curl
code: "curl -H \"Content-Type: application/json\" -X POST -d '{\n \"filters\": [\"country_code:(us OR gb) AND -publisher:youtube.com AND headline:rihanna\"],\n \"language\": \"en\",\n \"video_only\":false,\n \"sort_by\": \"nw_max_score\",\n \"find_related\": false,\n \"size\": 1\n}' \"https://api.newswhip.com/v1/articles?key=DevHub\""
samples-languages:
- curl
tags:
- Content
/articlesByHrefs:
post:
summary: /articlesByHrefs
description: ''
operationId: articlesbyhrefs
parameters:
- name: key
in: query
description: Your API key.
required: true
schema:
type: string
default: DevKey
requestBody:
content:
application/json:
schema:
type: object
required:
- hrefs
properties:
hrefs:
type: array
description: List of hrefs you wish to search for up to a maximum of 5
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "[\n {\n \"href\": \"https://www.theanimalclub.net/dogs/senior-dog-is-so-happy-that-family-remembered-his-13th-birthday/\",\n \"articles\": [\n {\n \"delta_time\": 8880,\n \"recent_fb_counts\": 4,\n \"recent_tw_counts\": 0,\n \"relatedStories\": [],\n \"fb_data\": {\n \"total_engagement_count\": 4341,\n \"likes\": 3740,\n \"comments\": 244,\n \"shares\": 357,\n \"total_count_delta\": 4,\n \"delta_period\": 8880,\n \"delta_period_unit\": \"m\"\n },\n \"tw_data\": {\n \"tw_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 8880,\n \"delta_period_unit\": \"m\"\n },\n \"li_data\": {\n \"li_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 8880,\n \"delta_period_unit\": \"m\"\n },\n \"pi_data\": {\n \"pi_count\": 0,\n \"delta_period\": 8880,\n \"delta_period_unit\": \"m\"\n },\n \"predicted_interactions\": 4341.0,\n \"predicted_timestamp\": 1584842548933,\n \"uuid\": \"12f51c50-531a-11ea-b13e-cf0e7a652529\",\n \"publication_timestamp\": 1582102250000,\n \"link\": \"https://www.theanimalclub.net/dogs/senior-dog-is-so-happy-that-family-remembered-his-13th-birthday/\",\n \"headline\": \"Senior dog is so happy that people remembered his 13th birthday\",\n \"excerpt\": \"Such a good doggo.\",\n \"keywords\": \"\",\n \"source\": {\n \"publisher\": \"theanimalclub.net\",\n \"domain\": \"theanimalclub.net\",\n \"link\": \"https://theanimalclub.net\",\n \"country\": \"\",\n \"country_code\": \"\",\n \"language\": \"en\"\n },\n \"image_link\": \"https://www.theanimalclub.net/wp-content/uploads/sites/3/2020/02/Ba.jpg\",\n \"has_video\": false,\n \"nw_score\": 0.00865636383437796,\n \"max_nw_score\": 873.6694656721905,\n \"topics\": [],\n \"authors\": [\n \"The Animal Club\"\n ],\n \"entities\": []\n }\n ]\n }\n]\n"
schema:
type: array
items:
type: object
properties:
href:
type: string
example: https://www.theanimalclub.net/dogs/senior-dog-is-so-happy-that-family-remembered-his-13th-birthday/
articles:
type: array
items:
type: object
properties:
delta_time:
type: integer
example: 8880
default: 0
recent_fb_counts:
type: integer
example: 4
default: 0
recent_tw_counts:
type: integer
example: 0
default: 0
relatedStories:
type: array
fb_data:
type: object
properties:
total_engagement_count:
type: integer
example: 4341
default: 0
likes:
type: integer
example: 3740
default: 0
comments:
type: integer
example: 244
default: 0
shares:
type: integer
example: 357
default: 0
total_count_delta:
type: integer
example: 4
default: 0
delta_period:
type: integer
example: 8880
default: 0
delta_period_unit:
type: string
example: m
tw_data:
type: object
properties:
tw_count:
type: integer
example: 0
default: 0
total_count_delta:
type: integer
example: 0
default: 0
delta_period:
type: integer
example: 8880
default: 0
delta_period_unit:
type: string
example: m
li_data:
type: object
properties:
li_count:
type: integer
example: 0
default: 0
total_count_delta:
type: integer
example: 0
default: 0
delta_period:
type: integer
example: 8880
default: 0
delta_period_unit:
type: string
example: m
pi_data:
type: object
properties:
pi_count:
type: integer
example: 0
default: 0
delta_period:
type: integer
example: 8880
default: 0
delta_period_unit:
type: string
example: m
predicted_interactions:
type: integer
example: 4341
default: 0
predicted_timestamp:
type: integer
example: 1584842548933
default: 0
uuid:
type: string
example: 12f51c50-531a-11ea-b13e-cf0e7a652529
publication_timestamp:
type: integer
example: 1582102250000
default: 0
link:
type: string
example: https://www.theanimalclub.net/dogs/senior-dog-is-so-happy-that-family-remembered-his-13th-birthday/
headline:
type: string
example: Senior dog is so happy that people remembered his 13th birthday
excerpt:
type: string
example: Such a good doggo.
keywords:
type: string
example: ''
source:
type: object
properties:
publisher:
type: string
example: theanimalclub.net
domain:
type: string
example: theanimalclub.net
link:
type: string
example: https://theanimalclub.net
country:
type: string
example: ''
country_code:
type: string
example: ''
language:
type: string
example: en
image_link:
type: string
example: https://www.theanimalclub.net/wp-content/uploads/sites/3/2020/02/Ba.jpg
has_video:
type: boolean
example: false
default: true
nw_score:
type: number
example: 0.00865636383437796
default: 0
max_nw_score:
type: number
example: 873.6694656721905
default: 0
topics:
type: array
authors:
type: array
items:
type: string
example: The Animal Club
entities:
type: array
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"error\": {\n \"message\": \"Number of HREFs exceeds max limit of 5\",\n \"id\": \"50140de9-59d3-465a-9da7-499decdff98a\"\n }\n}"
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: Number of HREFs exceeds max limit of 5
id:
type: string
example: 50140de9-59d3-465a-9da7-499decdff98a
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl -H \"Content-Type: application/json\" -X POST -d '{\n \"hrefs\":[\n \"https://www.theanimalclub.net/dogs/senior-dog-is-so-happy-that-family-remembered-his-13th-birthday/\"\n ]\n}' \"https://api.newswhip.com/v1/articlesByHrefs?key=DevHub\""
samples-languages:
- curl
tags:
- Content
components:
securitySchemes:
sec0:
type: apiKey
in: query
name: key
x-default: DevKey