Documentation

Search News

Search and filter news.

{
  "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.

{
  "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.

{
  "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.

Language Codes

Country Codes

Rate Limiting & Quotas

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.