>

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/geo-coordinates
Example Request and Response
GET
https://api.worldnewsapi.com/geo-coordinates?location=Tokyo%2C%20Japan
{
  "latitude": 35.652832,
  "longitude": 139.839478,
  "city": "Tokyo"
}

Why a News API

In today's world, staying informed about current events and news is essential. News is the primary source of information that keeps people updated with the latest happenings around the world. Whether it is politics, business, sports, entertainment, or any other field, news plays a vital role in shaping our understanding of the world. With the rapid advancements in technology, the traditional ways of consuming news have been revolutionized. News APIs are one such technological advancement that has made the process of accessing news much more efficient and effective.

A News API is a web service that allows developers to access and integrate news articles and related data into their applications. These APIs provide developers with a structured and standardized way to access news data from multiple sources, including news organizations, social media, and other online platforms. With the help of a News API, developers can create customized news applications that cater to the specific needs of their users.

One of the main advantages of using a News API is that it allows developers to build interesting and innovative applications that can provide users with personalized news content. For instance, a developer can build a news aggregator app that uses a News API to pull in news from various sources and filter it based on the user's interests. This way, users can get news that is relevant to their interests without having to sift through irrelevant information.

Another example of how a News API can be leveraged is to create a news bot that can provide users with news updates on a specific topic or category. For instance, a developer can create a bot that provides users with the latest news on technology, sports, or politics. This type of application can be particularly useful for busy individuals who don't have the time to keep up with the news on their own.

A News API can also be used to create data visualizations and infographics that provide users with a more engaging and interactive way to consume news. For example, a developer can use a News API to pull in data on global climate change and create a data visualization that shows how temperatures have changed over time. This type of application can be useful for journalists, researchers, and policymakers who need to understand complex data in a more accessible way.

Furthermore, News APIs can also be leveraged to create sentiment analysis tools that analyze the tone and sentiment of news articles. This can be useful for companies and organizations that need to track their brand reputation or monitor public opinion on specific issues. For instance, a company can use a News API to analyze news articles about their brand and track sentiment over time.

In conclusion, News APIs have revolutionized the way news is consumed and accessed by users. With the help of a News API, developers can build customized applications that provide users with personalized news content. These applications can range from news aggregators to data visualizations and sentiment analysis tools. By leveraging a News API, developers can create innovative applications that cater to the specific needs of their users and provide them with a more engaging and interactive way to consume news.

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 Kingdomgb
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.

Tutorial on how to get started with the News API

World News API is an API that gives you access to thousands of news sources in over 50 languages from over 150 countries. The News accessed through the API is semantically tagged, allowing for semantic news search, where features like location extraction, organization extraction, person extraction, news author extraction, and semantic search is also available. This article will look at how you can get the World News API up and running.

Create an Account

To start, visit the World News API website and create an account. Once an account is created, confirming the email address is the next step. This is an important step, as you won't be able to access the API until you've confirmed your email. Simply click on the confirmation link to confirm that your email.

Getting the API Key

Now that your email is verified. Log in to your World News API account and obtain your API key. API key is a unique identifier that allows you to access the API and request news articles.

After you have successfully logged in, perform the following steps to obtain your API.



From your dashboard, click on "Profile". In the "Profile" section, click on "Show/Hide API Key" to show your API key.

Copy the API Key and save it somewhere safer for easier access. Don’t share it with anyone else!

Installing the SDK

After getting the API, the next step would be downloading and installing the SDK.

Download the SDK from the World News API website by navigating to the SDKs page. For this tutorial, we will be using Python.

Extract the downloaded SDK file to a folder on your computer to a suitable location.

Open Command Prompt in administrator mode by right-clicking on the Command Prompt icon and selecting "Run as administrator".

Navigate to the SDK directory using the "cd" command in Command Prompt (cd path/to/sdk_folder).

Execute the following command to install the openapi_client.

python setup.py install


After the installation process is complete, you are all good to go!

ModuleNotFoundError: No module named 'com'

Now an error that may occur (rarely) later on saying that a module is missing. Let’s see how we can fix that in case we encounter it when we try to fetch news using the API.

The error may look like as follows:

The fix for this problem is relatively simple, simple follow the steps mentioned below:

  1. Open the SDK folder which you extracted.
  2. Navigate to the directory named "openapi_client".
  3. Find a folder named "com" in the directory.
  4. Copy the folder named "com".
  5. Paste it in the directory where you are executing your query from (i.e. in the same folder from where you are executing the news query). And that's it! The error will be gone now.

Making Your first Request

Now that the "openapi_client" and "worldnewsapi" has been successfully installed, let’s test it out to see if we can successfully fetch some news.

Let's go through the code step by step to see what is really happening.

import openapi_client
from pprint import pprint
from com.worldnewsapi import news_api

In the snippet above, we are importing the necessary libraries.

  1. openapi_client - Base library for communication with servers.
  2. pprint - For pretting printing.
  3. com.worldnewsapi - Our API for fetching news.
configuration = openapi_client.Configuration(
    host = "https://api.worldnewsapi.com"
)

In the snippet above, we are setting the host for the openapi client to communicate with. In case the host is not provided, it will default to "https://api.worldnewsapi.com".

configuration.api_key['apiKey'] = "your_api_key"

To ensure that we can properly get authenticated with the server and communicate, we need to set an API key. As explained at the start of this article, you can get an API key after logging into your account.

with openapi_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = news_api.NewsApi(api_client)
url = "https://www.bbc.com/news/world-us-canada-59340789" # str | The url of the news.
analyze = True # bool | Whether to analyze the news (extract entities etc.) (default to False)

try:
    # Extract News
    api_response = api_instance.extract_news(url, analyze)
    pprint(api_response)
except openapi_client.ApiException as e:
    print("Exception when calling NewsApi->extract_news: %s\n" % e)

The above snippet is where most of the heavy lifting is done, the following operations are performed here:

  1. A context with an instance of API client is created.
  2. Instance of API class is created.
  3. Url of a news article is provided.
  4. To extract entities and perform additional analysis, "analyze" is set to true.
  5. Finally, the news is extracted using the "extract_news" method.

Calling "extract_news" consumes 1 point, if "analyze" is set to be true, 2 additional points are consumed. In the demonstrated example, a total of 3 points (1 for extract news, 2 for setting analyze to true) will be consumed. More on points later on.

Once executed, you will get output as follows:



Since the reply is in JSON format, it is easy to filter data, useful especially when skimming through the data.

api_response = api_instance.extract_news(url, analyze)
pprint("Title: " + api_response['title'])
pprint("Author: " + api_response['author'])
pprint("Url: " + api_response['url'])
pprint("Text: " + api_response['text'])

Which would give the output as:


Full Code

Putting it all together, the final code is as follows:

import openapi_client
from pprint import pprint
from com.worldnewsapi import news_api


# Defining the host is optional and defaults to https://api.worldnewsapi.com
# See configuration.py for a list of all supported configuration parameters.
configuration = openapi_client.Configuration(
    host = "https://api.worldnewsapi.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: apiKey
configuration.api_key['apiKey'] = 'your_api_key'

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['apiKey'] = 'Bearer'

# Enter a context with an instance of the API client
with openapi_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = news_api.NewsApi(api_client)
    url = "https://www.bbc.com/news/world-us-canada-59340789" # str | The url of the news.
    analyze = True # bool | Whether to analyze the news (extract entities etc.) (default to False)

    try:
        # Extract News
        api_response = api_instance.extract_news(url, analyze)
        pprint(api_response)
    except openapi_client.ApiException as e:
        print("Exception when calling NewsApi->extract_news: %s\n" % e)

World News API provides a very accessible and convenient way to news from all over the world. It provides you with news from more than 50 languages from 150+ countries. One of the best things about the API is that it is semantically tagged - meaning you can filter news based on sentiment and find the exact set of news you are looking for. Easily, Efficiently and Effortlessly.

Happy coding.