/v1/aggregation Request Parameters
Request Params
Key | Datatype | Required | Description |
---|---|---|---|
q | string | REQUIRED |
STRING
String to search for. Has to be URL-encoded
> - Advanced q
(See examples for advanced explanation):
>> - Use AND
, OR
and NOT
(also written &&
, ||
and !
) for a more advanced search.
>> - Boolean operators
> Use +
before a string token that must appear in searched field(s)
> Use -
before a string token that must not appear in searched field(s)
> - Grouping
>> (apple AND microsoft) OR (tesla AND amazon)
>> apple AND (microsoft OR tesla OR amazon)
> - Wildcards
>> Use *
to match any string in any quantity.
>> Use ?
to match any string exactly once
> - Regular Expressions
>> Check the syntax
> - Use double quotes for exact match. ("\"Elon Musk\""
) If using exact match only, do not specify any lang
> Important: make sure your q
parameter is URL-encoded
> Reserved Characters:
>> The reserved characters are: + - = && || > < ! ( ) { } ^ " ~ * ? : \ /
> If you are not looking for a specific word, but you would like to discover news based on certain filter, you can use q="\*"
|
| lang
| string | | OPTIONAL
STRING
Specifies the language of the search. Allowed values are:
af
, ar
, bg
, bn
, ca
, cn
, cs
, cy
, da
, de
, el
, en
, es
, et
, fa
, fi
, fr
, gu
, he
, hi
, hr
, hu
, id
, it
, ja
, kn
, ko
, lt
, lv
, mk
, ml
, mr
, ne
, nl
, no
, pa
, pl
,pt
, ro
, ru
, sk
, sl
, so
, sq
, sv
, sw
, ta
, te
, th
, tl
, tr
, tw
, uk
, ur
, vi
.
Specifying the language will make your search more relevant
|
| from
| string | | OPTIONAL
STRING
From which point in time to start the search. No specific format is required. E.g. (2020/05/01
, 2020-05-01
,2020-05-01 12:54:14
, 2020-05-01 4:15am
, yesterday 2:02 am
, 2020/05/01 12:55 EST
) Default timezone is UTC. Defaults to one week ago at midnight UTC. |
| to
| string | | OPTIONAL
STRING
Until which point in time to search for. Default timezone is UTC |
| search_in
| string | | OPTIONAL
STRING
by default, we search what you specified in q
in both title
and summary
of the article. However, you can limit this to either title
or summary
|
| country
| string | | OPTIONAL
STRING
The country to which you want to narrow your search. This parameter is [experimental]. We advise you to use it in conjunction with the lang
parameter. Accepts any ISO 3166-1 alpha-2 codes |
| topic
| string | | OPTIONAL
STRING
The topic to which you want to restrict the articles of your choice. This parameter is [experimental]. Accepted values are news
, sport
, tech
, world
, finance
, politics
, business
, economics
, entertainment
news
usually means a general news feed (main headlines of a website).
> Important: this parameter is [experimental]. Not all news articles are assigned with a topic
, therefore, we cannot guarantee that 100% of topics talking about technology will be assigned a tech
label.
> One topic at a time, for example topic=sport
|
| sources
| string | | OPTIONAL
STRING
One or more news resources to filter your search. It should be the normal form of the URL, for example, nytimes.com, theguardian.com
> Comma separated string, for example sources=nytimes.com,cnn.com,wsj.com
|
| not_sources
| string | | OPTIONAL
STRING
One or more sources to be excluded from the search.
> Comma separated string, for example not_sources=nytimes.com,cnn.com,wsj.com
|
| ranked_only
| string | | OPTIONAL
STRING
Limit the search only for the sources which are in top 1 million online websites. Defaults to True
(False
if you want to turn it off). Unranked sources are assigned a rank that equals to 999999
|
| from_rank
| number | | OPTIONAL
INTEGER
Lowest boundary of the rank of news website to filter by. Important: lower rank means that a source is more popular |
| to_rank
| number | | OPTIONAL
INTEGER
Upper boundary of the rank of news website to filter by |
| agg_by
| string | | OPTIONAL
STRING
Options:
> day
— default option. Aggregate results by day. No more than 100 days
> hour
— Aggregate results by hour. No more than 100 hours |
HEADERS
Key | Datatype | Required | Description |
---|---|---|---|
x-rapidapi-key | string | REQUIRED |
STRING
Your API key |
| Content-Type
| string | | OPTIONAL
STRING
Output as JSON |
RESPONSES
status: OK
{"status":"ok","aggregation":[{"key_as_string":"2020-05-31","doc_count":20},{"key_as_string":"2020-05-30","doc_count":16},{"key_as_string":"2020-05-29","doc_count":31},{"key_as_string":"2020-05-28","doc_count":29},{"key_as_string":"2020-05-27","doc_count":31},{"key_as_string":"2020-05-26","doc_count":33},{"key_as_string":"2020-05-25","doc_count":19},{"key_as_string":"2020-05-24","doc_count":5},{"key_as_string":"2020-05-23","doc_count":11},{"key_as_string":"2020-05-22","doc_count":26},{"key_as_string":"2020-05-21","doc_count":32},{"key_as_string":"2020-05-20","doc_count":35},{"key_as_string":"2020-05-19","doc_count":32},{"key_as_string":"2020-05-18","doc_count":22},{"key_as_string":"2020-05-17","doc_count":14},{"key_as_string":"2020-05-16","doc_count":4},{"key_as_string":"2020-05-15","doc_count":2}],"user_input":{"q":"Trump","search_in":"summary_en","lang":"en","country":"US","from":"2020-05-01 00:00:00","to":"2020-06-01 00:00:00","ranked_only":"False","from_rank":1,"to_rank":100000,"sources":["cnn.com","usatoday.com"],"not_sources":["buzzfeed.com"],"topic":"news"}}