openapi: 3.1.0
info:
title: quick-start-api-formerly-get-api Articles Rankings API
version: '1'
servers:
- url: https://api.newswhip.com/v1
tags:
- name: Rankings
paths:
/region/{Region}/{Category}/{Time_Period}:
get:
summary: /region
description: ''
operationId: region
parameters:
- name: Region
in: path
description: Filters articles published in {region}. The region should be passed in English, using the reference data linked below.
schema:
type: string
default: World
required: true
- name: Category
in: path
description: 'Filters articles by {category}. Note: the category (topic) should be passed in English, using the reference data linked below.'
schema:
type: string
default: All
required: true
- name: Time_Period
in: path
description: Filters articles published within the last {time_period} hours. Valid time_periods range from 1 up to 168 hours
schema:
type: integer
format: int32
default: 24
required: true
- name: key
in: query
description: Your API key
required: true
schema:
type: string
default: DevKey
- 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\": 1000,\n \"articles\": [\n {\n \"delta_time\": 292,\n \"recent_fb_counts\": 121080,\n \"recent_tw_counts\": 5186,\n \"relatedStories\": [\n \n ],\n \"fb_data\": {\n \"total_engagement_count\": 438712,\n \"total_count_delta\": 121080,\n \"delta_period\": 292,\n \"delta_period_unit\": \"m\",\n \"fb_overperforming\": 27.785593513761\n },\n \"tw_data\": {\n \"tw_count\": 31157,\n \"total_count_delta\": 5186,\n \"delta_period\": 292,\n \"delta_period_unit\": \"m\",\n \"tw_overperforming\": 20.063359883215\n },\n \"li_data\": {\n \"li_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 292,\n \"delta_period_unit\": \"m\"\n },\n \"pi_data\": {\n \"pi_count\": 22,\n \"delta_period\": 292,\n \"delta_period_unit\": \"m\"\n },\n \"predicted_interactions\": 1131719,\n \"predicted_timestamp\": 1522338239279,\n \"uuid\": \"97b2ca00-31f7-11e8-be5b-ef989ddb8d11\",\n \"publication_timestamp\": 1522179772000,\n \"link\": \"https://www.nytimes.com/2018/03/27/opinion/nikolas-cruz-shooting-florida.html\",\n \"headline\": \"Opinion | I Tried to Befriend Nikolas Cruz. He Still Killed My Friends.\",\n \"excerpt\": \"The notion that the Parkland shootings wouldn\\u2019t have occurred if students had been kinder is deeply dangerous.\",\n \"keywords\": \"Parkland Shooting,Nikolas Cruz,Marjory Stoneman Douglas,Murders and Homicides\",\n \"source\": {\n \"publisher\": \"nytimes.com\",\n \"domain\": \"nytimes.com\",\n \"link\": \"https://nytimes.com\",\n \"country\": \"United States\",\n \"country_code\": \"us\",\n \"language\": \"en\"\n },\n \"image_link\": \"https://static01.nyt.com/images/2018/03/27/opinion/27Robinson/27Robinson-facebookJumbo.jpg\",\n \"has_video\": false,\n \"nw_score\": 1781.0086007513,\n \"max_nw_score\": 9797.2621208147,\n \"topics\": [\n {\n \"id\": 2,\n \"name\": \"News\"\n },\n {\n \"id\": 19,\n \"name\": \"Opinion\"\n }\n ],\n \"authors\": [\n \"ISABELLE ROBINSON\"\n ],\n \"entities\": [\n \n ]\n }\n ]\n}"
schema:
type: object
properties:
total_match:
type: integer
example: 1000
default: 0
articles:
type: array
items:
type: object
properties:
delta_time:
type: integer
example: 292
default: 0
recent_fb_counts:
type: integer
example: 121080
default: 0
recent_tw_counts:
type: integer
example: 5186
default: 0
relatedStories:
type: array
fb_data:
type: object
properties:
total_engagement_count:
type: integer
example: 438712
default: 0
total_count_delta:
type: integer
example: 121080
default: 0
delta_period:
type: integer
example: 292
default: 0
delta_period_unit:
type: string
example: m
fb_overperforming:
type: number
example: 27.785593513761
default: 0
tw_data:
type: object
properties:
tw_count:
type: integer
example: 31157
default: 0
total_count_delta:
type: integer
example: 5186
default: 0
delta_period:
type: integer
example: 292
default: 0
delta_period_unit:
type: string
example: m
tw_overperforming:
type: number
example: 20.063359883215
default: 0
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: 292
default: 0
delta_period_unit:
type: string
example: m
pi_data:
type: object
properties:
pi_count:
type: integer
example: 22
default: 0
delta_period:
type: integer
example: 292
default: 0
delta_period_unit:
type: string
example: m
predicted_interactions:
type: integer
example: 1131719
default: 0
predicted_timestamp:
type: integer
example: 1522338239279
default: 0
uuid:
type: string
example: 97b2ca00-31f7-11e8-be5b-ef989ddb8d11
publication_timestamp:
type: integer
example: 1522179772000
default: 0
link:
type: string
example: https://www.nytimes.com/2018/03/27/opinion/nikolas-cruz-shooting-florida.html
headline:
type: string
example: Opinion | I Tried to Befriend Nikolas Cruz. He Still Killed My Friends.
excerpt:
type: string
example: The notion that the Parkland shootings wouldn’t have occurred if students had been kinder is deeply dangerous.
keywords:
type: string
example: Parkland Shooting,Nikolas Cruz,Marjory Stoneman Douglas,Murders and Homicides
source:
type: object
properties:
publisher:
type: string
example: nytimes.com
domain:
type: string
example: nytimes.com
link:
type: string
example: https://nytimes.com
country:
type: string
example: United States
country_code:
type: string
example: us
language:
type: string
example: en
image_link:
type: string
example: https://static01.nyt.com/images/2018/03/27/opinion/27Robinson/27Robinson-facebookJumbo.jpg
has_video:
type: boolean
example: false
default: true
nw_score:
type: number
example: 1781.0086007513
default: 0
max_nw_score:
type: number
example: 9797.2621208147
default: 0
topics:
type: array
items:
type: object
properties:
id:
type: integer
example: 2
default: 0
name:
type: string
example: News
authors:
type: array
items:
type: string
example: ISABELLE ROBINSON
entities:
type: array
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{"error":{"message":"Unknown country or region. Received: Wod","id":"2f0c0762-f0ea-4b5a-bd3e-019d259895e2"}}'
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: 'Unknown country or region. Received: Wod'
id:
type: string
example: 2f0c0762-f0ea-4b5a-bd3e-019d259895e2
deprecated: false
security: []
x-readme:
code-samples:
- language: curl
code: curl "https://api.newswhip.com/v1/region/World/All/24?key=DevHub"
samples-languages:
- curl
tags:
- Rankings
/publisher/{Publisher}/{Time_Period}:
get:
summary: /publisher
description: ''
operationId: publisher
parameters:
- name: Publisher
in: path
description: Any domain or subdomain. i.e. nytimes.com, blog.newswhip.com
schema:
type: string
default: nytimes.com
required: true
- name: Time_Period
in: path
description: Filters articles published within the last {time_period} hours. Valid time_periods range from 1 up to 168 hours
schema:
type: integer
format: int32
default: 24
required: true
- 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\": 702,\n \"articles\": [\n {\n \"delta_time\": 211,\n \"recent_fb_counts\": 3760,\n \"recent_tw_counts\": 188,\n \"videos\": [],\n \"relatedStories\": [],\n \"fb_data\": {\n \"total_engagement_count\": 48195,\n \"total_count_delta\": 3760,\n \"delta_period\": 211,\n \"delta_period_unit\": \"m\",\n \"fb_overperforming\": 2.884757949529689\n },\n \"tw_data\": {\n \"tw_count\": 7431,\n \"total_count_delta\": 188,\n \"delta_period\": 211,\n \"delta_period_unit\": \"m\",\n \"tw_overperforming\": 4.646973523569058\n },\n \"li_data\": {\n \"li_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 211,\n \"delta_period_unit\": \"m\"\n },\n \"pi_data\": {\n \"pi_count\": 1,\n \"delta_period\": 211,\n \"delta_period_unit\": \"m\"\n },\n \"predicted_interactions\": 74438,\n \"predicted_timestamp\": 1522571075969,\n \"uuid\": \"3a4c6b20-3443-11e8-ab88-49c2dc76b82d\",\n \"publication_timestamp\": 1522432393000,\n \"link\": \"https://www.nytimes.com/2018/03/30/us/stephon-clark-independent-autopsy.html\",\n \"headline\": \"Stephon Clark Was Shot 8 Times Primarily in His Back, Family-Ordered Autopsy Finds\",\n \"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.\",\n \"keywords\": \"Stephon Clark,Police Brutality;Police Misconduct;Police Shootings\",\n \"source\": {\n \"publisher\": \"nytimes.com\",\n \"domain\": \"nytimes.com\",\n \"link\": \"https://nytimes.com\",\n \"country\": \"United States\",\n \"country_code\": \"us\",\n \"language\": \"en\"\n },\n \"image_link\": \"https://static01.nyt.com/images/2018/03/22/autossell/sacramento-schooting2/sacramento-schooting2-facebookJumbo-v2.jpg\",\n \"has_video\": true,\n \"nw_score\": 280.85125702122036,\n \"max_nw_score\": 3212.7672437775227,\n \"topics\": [\n {\n \"id\": 2,\n \"name\": \"News\"\n },\n {\n \"id\": 668,\n \"name\": \"Events\"\n }\n ],\n \"authors\": [\n \"FRANCES ROBLES\"\n ],\n \"entities\": [\n \"Sacramento\",\n \"Mr Clark\"\n ]\n }\n ]\n}"
schema:
type: object
properties:
total_match:
type: integer
example: 702
default: 0
articles:
type: array
items:
type: object
properties:
delta_time:
type: integer
example: 211
default: 0
recent_fb_counts:
type: integer
example: 3760
default: 0
recent_tw_counts:
type: integer
example: 188
default: 0
videos:
type: array
relatedStories:
type: array
fb_data:
type: object
properties:
total_engagement_count:
type: integer
example: 48195
default: 0
total_count_delta:
type: integer
example: 3760
default: 0
delta_period:
type: integer
example: 211
default: 0
delta_period_unit:
type: string
example: m
fb_overperforming:
type: number
example: 2.884757949529689
default: 0
tw_data:
type: object
properties:
tw_count:
type: integer
example: 7431
default: 0
total_count_delta:
type: integer
example: 188
default: 0
delta_period:
type: integer
example: 211
default: 0
delta_period_unit:
type: string
example: m
tw_overperforming:
type: number
example: 4.646973523569058
default: 0
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: 211
default: 0
delta_period_unit:
type: string
example: m
pi_data:
type: object
properties:
pi_count:
type: integer
example: 1
default: 0
delta_period:
type: integer
example: 211
default: 0
delta_period_unit:
type: string
example: m
predicted_interactions:
type: integer
example: 74438
default: 0
predicted_timestamp:
type: integer
example: 1522571075969
default: 0
uuid:
type: string
example: 3a4c6b20-3443-11e8-ab88-49c2dc76b82d
publication_timestamp:
type: integer
example: 1522432393000
default: 0
link:
type: string
example: https://www.nytimes.com/2018/03/30/us/stephon-clark-independent-autopsy.html
headline:
type: string
example: Stephon Clark Was Shot 8 Times Primarily in His Back, Family-Ordered Autopsy Finds
excerpt:
type: string
example: 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:
type: string
example: Stephon Clark,Police Brutality;Police Misconduct;Police Shootings
source:
type: object
properties:
publisher:
type: string
example: nytimes.com
domain:
type: string
example: nytimes.com
link:
type: string
example: https://nytimes.com
country:
type: string
example: United States
country_code:
type: string
example: us
language:
type: string
example: en
image_link:
type: string
example: https://static01.nyt.com/images/2018/03/22/autossell/sacramento-schooting2/sacramento-schooting2-facebookJumbo-v2.jpg
has_video:
type: boolean
example: true
default: true
nw_score:
type: number
example: 280.85125702122036
default: 0
max_nw_score:
type: number
example: 3212.7672437775227
default: 0
topics:
type: array
items:
type: object
properties:
id:
type: integer
example: 2
default: 0
name:
type: string
example: News
authors:
type: array
items:
type: string
example: FRANCES ROBLES
entities:
type: array
items:
type: string
example: Sacramento
'400':
description: '400'
content:
text/plain:
examples:
Result:
value: "<!DOCTYPE html>\n<html lang=\"en\">\n <head>\n <title>Bad Request</title>\n <link rel=\"shortcut icon\" href=\"data:image/png;\">\n <style>\n html, body, pre {\n margin: 0;\n padding: 0;\n font-family: Monaco, 'Lucida Console', monospace;\n background: #ECECEC;\n }\n h1 {\n margin: 0;\n background: #AD632A;\n padding: 20px 45px;\n color: #fff;\n text-shadow: 1px 1px 1px rgba(0,0,0,.3);\n border-bottom: 1px solid #9F5805;\n font-size: 28px;\n }\n p#detail {\n margin: 0;\n padding: 15px 45px;\n background: #F6A960;\n border-top: 4px solid #D29052;\n color: #733512;\n text-shadow: 1px 1px 1px rgba(255,255,255,.3);\n font-size: 14px;\n border-bottom: 1px solid #BA7F5B;\n }\n </style>\n </head>\n <body>\n <h1>Bad Request</h1>\n\n <p id=\"detail\">\n For request 'GET /api/v1/publisher/your_pubisher/your_time_period?key=DevHub' [Cannot parse parameter time as Int: For input string: "null"]\n </p>\n\n </body>\n</html>"
deprecated: false
security: []
x-readme:
code-samples:
- language: curl
code: curl "https://api.newswhip.com/v1/publisher/nytimes.com/24?key=DevHub"
samples-languages:
- curl
tags:
- Rankings
/local/{City}/All/{Time_Period}:
get:
summary: /local
description: ''
operationId: local
parameters:
- name: City
in: path
description: Any city or local region. See below for available local regions. i.e. New York, NY, London, Toronto, Hamburg-Schleswig-Holstein.
schema:
type: string
default: Seattle, WA
required: true
- name: Time_Period
in: path
description: Filters articles published within the last {time_period} hours. Valid time_periods range from 1 up to 168 hours
schema:
type: integer
format: int32
default: 24
required: true
- 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\": 249,\n \"recent_fb_counts\": 41,\n \"recent_tw_counts\": 1,\n \"videos\": [\n \"http://www.youtube.com/watch?v=2vk8T35bbQc\",\n \"http://www.youtube.com/watch?v=28G9VLQezVg\",\n \"http://www.youtube.com/watch?v=c02O4Wvo7QI\",\n \"http://www.youtube.com/watch?v=TuuumQ4hcDg\",\n \"http://www.youtube.com/watch?v=nnFZKnlQlDw\"\n ],\n \"relatedStories\": [],\n \"fb_data\": {\n \"total_engagement_count\": 2422,\n \"total_count_delta\": 41,\n \"delta_period\": 249,\n \"delta_period_unit\": \"m\"\n },\n \"tw_data\": {\n \"tw_count\": 7,\n \"total_count_delta\": 1,\n \"delta_period\": 249,\n \"delta_period_unit\": \"m\"\n },\n \"li_data\": {\n \"li_count\": 0,\n \"total_count_delta\": 0,\n \"delta_period\": 249,\n \"delta_period_unit\": \"m\"\n },\n \"pi_data\": {\n \"pi_count\": 1,\n \"delta_period\": 249,\n \"delta_period_unit\": \"m\"\n },\n \"predicted_interactions\": 2638,\n \"predicted_timestamp\": 1522561756839,\n \"uuid\": \"184c2eb0-343f-11e8-9e4c-83fcdd16cc63\",\n \"publication_timestamp\": 1522430612000,\n \"link\": \"http://bipartisanreport.com/2018/03/30/breaking-fbi-detains-trump-ally-at-airport-donald-feeling-robert-mueller-heat/\",\n \"headline\": \"BREAKING: FBI Detains Trump Ally At Airport - Donald Feeling Robert Mueller Heat\",\n \"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\",\n \"keywords\": \"\",\n \"source\": {\n \"publisher\": \"bipartisanreport.com\",\n \"domain\": \"bipartisanreport.com\",\n \"link\": \"http://bipartisanreport.com\",\n \"country\": \"United States\",\n \"country_code\": \"us\",\n \"language\": \"en\"\n },\n \"image_link\": \"http://cdn.bipartisanreport.com/wordpress/wp-content/uploads/2018/03/935503612.jpg\",\n \"has_video\": true,\n \"nw_score\": 6.6169187100695535,\n \"max_nw_score\": 1029.80745168683,\n \"topics\": [\n {\n \"id\": 2,\n \"name\": \"News\"\n },\n {\n \"id\": 20,\n \"name\": \"Politics\"\n }\n ],\n \"authors\": [\n \"Caleb Newton\"\n ],\n \"entities\": [\n \"Russia\",\n \"House Intelligence Committee\",\n \"Robert Mueller\"\n ]\n }\n ]\n}"
schema:
type: object
properties:
total_match:
type: integer
example: 620
default: 0
articles:
type: array
items:
type: object
properties:
delta_time:
type: integer
example: 249
default: 0
recent_fb_counts:
type: integer
example: 41
default: 0
recent_tw_counts:
type: integer
example: 1
default: 0
videos:
type: array
items:
type: string
example: http://www.youtube.com/watch?v=2vk8T35bbQc
relatedStories:
type: array
fb_data:
type: object
properties:
total_engagement_count:
type: integer
example: 2422
default: 0
total_count_delta:
type: integer
example: 41
default: 0
delta_period:
type: integer
example: 249
default: 0
delta_period_unit:
type: string
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newswhip/refs/heads/main/openapi/newswhip-rankings-api-openapi.yml