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

Code Text Description
200 OK Success!
400 Bad Request The server cannot or will not process the request due to an apparent client error.
401 Unauthorized Authentication credentials were missing or incorrect.
403 Forbidden Your plan does not have access to the feature you requested, which means your request can't be fulfilled. More details about the missing feature are provided in the response message.
404 Not Found The URI requested is invalid or the resource requested, such as a story, does not exist.
405 Method Not Allowed A request method is not supported for the requested resource.
414 URI Too Long The URI provided was too long for the server to process. The maximum request URI size is 2 kB.
422 Unprocessable Entity The request was invalid or cannot be otherwise served.
429 Too Many Requests Usage limits are exceeded.
500 Internal Server Error An unexpected error has occurred and our engineers have been informed. If you continue to have problems, contact support@aylien.com.
503 Service Unavailable The server is currently unavailable (because it is overloaded or down for maintenance).
504 Gateway Timeout The server could not get a response in time, probably because the web page is blocked or behind a paywall.

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.

Query URL-Encoded Query
published_at.start=NOW-30DAYS&categories.id[]=IAB1-5&entities.body.links.dbpedia[]=http://dbpedia.org/resource/Star_Wars&categories.taxonomy=iab-qag published_at.start=NOW-30DAYS&categories.id%5B%5D=IAB1-5&entities.body.links.dbpedia%5B%5D=http%3A%2F%2Fdbpedia.org%2Fresource%2FStar_Wars&categories.taxonomy=iab-qag
title=Trump OR Sanders&entities.title.text[]=election title=Trump+OR+Sanders&entities.title.text%5B%5D=election
title=Ireland&published_at.end=NOW-2MONTHS/DAY title=Ireland&published_at.end=NOW-2MONTHS%2FDAY

Language Support

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

English (en) German (de) French (fr) Italian (it)
Spanish (es) Portuguese (pt) Russian (ru) Dutch (nl)
Arabic (ar) Turkish (tr) Chinese (traditional) (zh-tw) Chinese (simplified) (zh-cn)
Swedish (sv) Danish (da) Finnish (fi) Farsi (fa)

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.

Feature Original Text Analyzed Translated Text Analyzed
Clusters en All Other Languages
Topic Categories en All Other Languages
Entities en All Other Languages
Sentiment (body) en, es, de All Other Languages
Extracted Keywords en, es, de, it, fr, pt All Other Languages
Hashtags en, es, de, it, fr, pt All Other Languages
Word, Character, and Paragraph Counts en, es, de, it, fr, pt All Other Languages

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:

Opening the import dialog

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.

Generate the 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.

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:

Configuring your request

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