Documentation

Here you have detailed documentation of all available API functions. To get started, you can make the sample request for each endpoint, download an SDK, or run in Postman (see bottom of left navigation).

Search News

Search and filter news.

GET
https://api.worldnewsapi.com/search-news
Example Request and Response
GET
https://api.worldnewsapi.com/search-news?text=tesla
{
  "offset": 0,
  "number": 10,
  "available": 83,
  "news": [
    {
      "id": 28,
      "title": "Tesla to Release a Four-Motor Version of Cybertruck",
      "text": "Tesla CEO Elon Musk has revealed new details about the upcoming Cybertruck electric pickup truck, the mass production of which was delayed until 2023 because of the lack of components and a lot of complex technologies that need to be scaled up. According to Musk, the initial production of the electric pickup truck will begin with a four-motor variant with “independent, ultra fast response torque control of each wheel,” the tweet reads. In response, Twitter users asked if the Cybertruck could turn like a tank. Musk said that thanks to both the rear and front wheel steer, the electric truck will not only be able to turn like a tank, but also drive diagonally like a crab. According to Electrek, this change could be Tesla's reaction to what its competitors do. Since the introduction of Tesla’s novelty, the market for electric pickup trucks has significantly evolved. Currently, one electric pickup on the market can turn like a tank – the Rivian R1T, while GMC's Hummer EV can drive diagonally. Following the announcement of Tesla Cybertruck in 2019, the company announced three configurations of the pickup truck: the entry-level model with one motor, the one with two motors, and the one with three. Rumor has it that the company intends to abandon the single-motor version altogether. In this case, Tesla Cybertruck will be sold with two, three, and four motors. Musk has promised to provide an update on the pickup's roadmap on the next earnings call. The production of Tesla Cybertruck is expected to begin at the end of 2022, and its mass production is slated to start in 2023.",
      "summary": "Tesla CEO Elon Musk has revealed new details about the upcoming Cybertruck electric pickup truck. According to Musk, its initial production will begin with a four-motor variant.",
      "url": "https://internetprotocol.co/hitech/2021/12/07/tesla-to-release-a-four-motor-cybertruck/",
      "image": "https://internetprotocol.co/content/images/2021/12/Tesla-to-Release-a-Four-Motor-Version-of-Cybertruck.png",
      "author": "Kay Lee",
      "language": "en",
      "source_country": "co",
      "sentiment": 0.712523
    },...
  ]
}

Extract News

Extract a news article from a website to a well structure JSON object.

GET
https://api.worldnewsapi.com/extract-news
Example Request and Response
GET
https://api.worldnewsapi.com/extract-news?analyze=true&url=https%3A%2F%2Finternetprotocol.co%2Fhitech%2F2021%2F12%2F07%2Ftesla-to-release-a-four-motor-cybertruck%2F
{
  "title": "Tesla to Release a Four-Motor Version of Cybertruck",
  "text": "Tesla CEO Elon Musk has revealed new details about the upcoming Cybertruck electric pickup truck, the mass production of which was delayed until 2023 because of the lack of components and a lot of complex technologies that need to be scaled up. According to Musk, the initial production of the electric pickup truck will begin with a four-motor variant with “independent, ultra fast response torque control of each wheel,” the tweet reads. In response, Twitter users asked if the Cybertruck could turn like a tank. Musk said that thanks to both the rear and front wheel steer, the electric truck will not only be able to turn like a tank, but also drive diagonally like a crab. According to Electrek, this change could be Tesla's reaction to what its competitors do. Since the introduction of Tesla’s novelty, the market for electric pickup trucks has significantly evolved. Currently, one electric pickup on the market can turn like a tank – the Rivian R1T, while GMC's Hummer EV can drive diagonally. Following the announcement of Tesla Cybertruck in 2019, the company announced three configurations of the pickup truck: the entry-level model with one motor, the one with two motors, and the one with three. Rumor has it that the company intends to abandon the single-motor version altogether. In this case, Tesla Cybertruck will be sold with two, three, and four motors. Musk has promised to provide an update on the pickup's roadmap on the next earnings call. The production of Tesla Cybertruck is expected to begin at the end of 2022, and its mass production is slated to start in 2023.",
  "url": "https://internetprotocol.co/hitech/2021/12/07/tesla-to-release-a-four-motor-cybertruck/",
  "image": "https://internetprotocol.co/content/images/2021/12/Tesla-to-Release-a-Four-Motor-Version-of-Cybertruck.png",
  "author": "Kay Lee",
  "language": "en",
  "source_country": "co",
  "sentiment": 0.712523
}

Get Geo Coordinates

Retrieve the latitude and longitude of a location name. Given this information you can fill the location-filter parameter in the news search endpoint.

GET
https://api.worldnewsapi.com/get-coordinates
Example Request and Response
GET
https://api.worldnewsapi.com/get-coordinates?location=Tokyo%2C%20Japan
{
  "latitude": 35.652832,
  "longitude": 139.839478,
  "city": "Tokyo"
}

Semantic Types

The news search API allows you to filter and search for semantic entities. Entities are concepts that share a specific meaning but can be addressed with different names. For example, the entity "USA" has alternative names such as "US" or "United States of America" but they all refer to the same country.

When filtering for news by a certain entity, you don't have to worry about the synonym to use as the API will normalize it and find all instances of the concept regardless of the synonym you use. For example, it makes no difference whether you search for LOC:USA or LOC:United States of America

The following table shows all supported types with examples of how to use them in the entities filter in the news search endpoint.

Type Code Example
Location LOC LOC:Ireland
Person PER PER:Michael Jordan
Organization ORG ORG:Tesla

Language Codes

Language Code (ISO 6391)
Afaraa
Amharicam
Arabicar
Bengalibn
Bosnianbs
Bulgarianbg
Burmesemy
Chinesezh
Croatianhr
Czechcs
Danishda
Dutchnl
Englishen
Estonianet
Finnishfi
Frenchfr
Germande
Greekel
Hebrewhe
Hindihi
Hungarianhu
Icelandicis
Indonesianid
Italianit
Japaneseja
Koreanko
Laolo
Latvianlv
Lithuanianlt
Macedonianmk
Malayms
Maltesemt
Marathimr
Māorimi
Nepaline
Norwegiannb
Norwegianno
Persianfa
Polishpl
Portuguesept
Romanianro
Russianru
Serbiansr
Sinhalesesi
Slovaksk
Slovenesl
Somaliso
Spanishes
Swedishsv
Tajiktg
Tamilta
Telugute
Thaith
Ukrainianuk
Urduur
Vietnamesevi

Country Codes

Country Code (ISO 3166)
Afghanistanaf
Albaniaal
Algeriadz
American Samoaas
Anguillaai
Australiaau
Austriaat
Bahamasbs
Bahrainbh
Bangladeshbd
Barbadosbb
Belarusby
Belgiumbe
Belizebz
Beninbj
Bermudabm
Bhutanbt
Bosnia And Herzegovinaba
Bouvet Islandbv
Brazilbr
British Indian Ocean Territoryio
Brunei Darussalambn
Bulgariabg
Burkina Fasobf
Burundibi
Cambodiakh
Camerooncm
Canadaca
Cape Verdecv
Central African Republiccf
Chilecl
Chinacn
Colombiaco
Comoroskm
Congo, Democratic Republic Of Thecd
Congo, Republic Of Thecg
Costa Ricacr
Cote D'ivoireci
Croatiahr
Cubacu
Cypruscy
Czech Republiccz
Denmarkdk
Djiboutidj
Dominican Republicdo
Ecuadorec
Egypteg
El Salvadorsv
Eritreaer
Ethiopiaet
Europeeu
Fijifj
Finlandfi
Francefr
French Guianagf
French Polynesiapf
Gambiagm
Germanyde
Ghanagh
Greecegr
Guatemalagt
Guineagn
Guyanagy
Hondurashn
Hong Konghk
Hungaryhu
Icelandis
Indiain
Indonesiaid
Iranir
Iraqiq
Irelandie
Israelil
Italyit
Japanjp
Jordanjo
Kazakhstankz
Kenyake
Kuwaitkw
Laosla
Latvialv
Lebanonlb
Lesothols
Liberialr
Liechtensteinli
Lithuanialt
Luxembourglu
Macedoniamk
Madagascarmg
Malawimw
Malaysiamy
Maldivesmv
Maliml
Maltamt
Mauritaniamr
Mauritiusmu
Mexicomx
Micronesia, Federated States Offm
Moldovamd
Monacomc
Montenegrome
Montserratms
Moroccoma
Myanmarmm
Namibiana
Nepalnp
Netherlandsnl
New Zealandnz
Nigerne
Nigeriang
North Koreakp
Norwayno
Omanom
Pakistanpk
Palestinian Territoryps
Paraguaypy
Perupe
Philippinesph
Polandpl
Portugalpt
Qatarqa
Romaniaro
Russiaru
Rwandarw
Saint Kitts And Neviskn
Saint Vincent And The Grenadinesvc
San Marinosm
Saudi Arabiasa
Senegalsn
Serbiars
Seychellessc
Sierra Leonesl
Singaporesg
Slovakiask
Sloveniasi
Solomon Islandssb
Somaliaso
South Africaza
South Koreakr
Spaines
Sri Lankalk
Surinamesr
Swazilandsz
Swedense
Switzerlandch
Syriasy
Taiwantw
Tajikistantj
Thailandth
Timor-lestetl
Togotg
Tongato
Trinidad And Tobagott
Tuvalutv
Ugandaug
United Arab Emiratesae
United Kingdomuk
United States Of Americaus
Uruguayuy
Uzbekistanuz
Vanuatuvu
Zambiazm

Rate Limiting & Quotas

Each API plan comes with a daily quota of points. Every API call you make costs a certain amount of points. Usually, every request is
1 point
and
0.01 points
per result returned, but there are many exceptions. At the bottom of each endpoint description you will find information about the number of points required for that endpoint.

When you are on the free plan and your daily quota is used up, the API will respond with the error code 402 and no more calls can be made until your quota resets.

You have complete control over your quota by looking at your console dashboard and checking the API response headers that appear with every answer from the API. These response headers are:

  • X-API-Quota-Request: The number of points used by the request.
  • X-API-Quota-Used: The number of points used in total today. This number resets to zero at midnight UTC (click here to compare to your local time zone).
  • X-API-Quota-Left: The number of points left today (depends on your plan).

Rate Limiting

There is a limit of how many requests you can make per second. The limits depend on the plan you are on. If you try making more requests you will receive a 429 error.

  • Free: 60 requests in 1 minute
  • Reporter: 2 requests per second
  • Journalist: 10 requests per second
  • Editor: 20 requests per second

Authentication

To use the API you need an API key. You can get a free one by simply signing up here.

Once you have your API key, you have to put it in the request URL for every request you make like so ?api-key=YOUR-API-KEY.

Attention: Only the first query parameter is prefixed with a ? (question mark), all subsequent ones will be prefixed with a & (ampersand). That is how URLs work and nothing related to our API. Here's a full example with two parameters api-key and text: https://api.worldnewsapi.com/search-news?api-key=YOUR-API-KEY&text=tesla.

Alternatively, you can put the API key in the request header as x-api-key.