Getting Started

The AYLIEN News API is the most powerful way of sourcing, searching, and syndicating enriched news content. Here you’ll find everything you need to know about using the News API.

Calling the API

GET or POST

In addition to using the SDKs, you can call the API directly by sending HTTP POST or GET requests to https://api.aylien.com/news/, followed by the endpoint name. All endpoints support the GET method, while only the /coverages and /related_stories endpoints support both GET and POST methods. If you're dealing with long text, please consider using POST.

Authorization

Requests to the API are authorized by adding an App ID and App Key to the headers of the call. You receive these credentials when you sign up.

• X-AYLIEN-NewsAPI-Application-ID must be set to your Application ID.
• X-AYLIEN-NewsAPI-Application-Key must be set to your Application Key.

Error Codes & Responses

Rate Limits

Rate limiting of the API is primarily considered on a per-application basis — or, more accurately, per application ID you control.

Hits

Each endpoint is subject to a rate limit of 60 hits per minute and 3 hits per second.

Story Volumes

When an application exceeds the rate limit for a given API endpoint, the AYLIEN News API will return an HTTP 429 "Too Many Requests" response code.

Checking your remaining story volume

There are three response headers you can use to check your quota allowance, the number of hits remaining on your quota, and the time and date your quota will be reset:

• X-RateLimit-Limit : The number of allowed requests in the current period
• X-RateLimit-Remaining : The number of remaining requests in the current period
• X-RateLimit-Reset : The remaining window before the rate limit resets in UTC epoch seconds

Licensed content

Customers with access to our licensed content will be able to retrieve stories from our licensed sources. The license_type field (a field in the stories endpoint response) indicates whether an article has come from a licensed source or if it is a web-sourced article.

Sample license_type flag output

"license_type": 0 # indicates the story is from the group of web-based sources
"license_type": 1 # indicates the story is from the group of licensed sources

URL Encoding

Remember to URL-encode your query. The following examples show how queries can be properly encoded.

Language Support

Our API supports multiple (human) languages, that can be selected using the language[] parameter.

Some of our features are added to the story objects after the text is analyzed in the original language, while other features are added after the text has been translated to English. The table below lists the langauge used for analysis for each feature.

Testing the News API with Postman

If you are looking for a quick and straightforward way of testing the News API and familiarizing yourself with its various endpoints and parameters, you may want to consider our Postman integration (in addition to our Interactive Documentation and our Query Builder).

Postman is a suite of tools for testing, building and documenting APIs which can be downloaded for free from here.

Once you've downloaded and installed Postman, follow the steps below to get up and running with the News API:

Step 1

Before starting, make sure you have created a News API account and have access to your App ID and Key. Click here to create a free account.

Step 2

Open Postman, and click on the Import button on the top left corner:

Step 3

In the Import dialog, click on the Import From Link button and paste the following URL into the input box, and click Import.

https://docs.aylien.com/yaml_files/api.yaml

Step 4

You will need to generate the Postman collection from the input yaml file you have imported. To do this, name your collection and click Generate Collection.

Once the schema is imported, you should be able to see a new collection on the left hand side.

Adding your API credentials

Once your schema is imported, the first step is to add your App ID and Key. Click on the List Stories endpoint in your collection, then click on Headers. This will reveal two fields (X-AYLIEN-NewsAPI-Application-ID and X-AYLIEN-NewsAPI-Application-Key) where you can add your credentials.

Step 5

After you've added your credentials, you'll need to replace the placeholder {{baseUrl}} text with https://api.aylien.com/news.

Now can configure your request and set its parameters by clicking on Params. Doing so reveals all the available parameters for any endpoint, allowing you to view or edit any of the parameters:

Once you're finished, click on Send to submit the request and retrieve the results in JSON format in the box below.