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 API Endpoints SDKs Common Workflows Building your first searches

Using the Search UI with News API

You can learn how to use the News API in conjunction with the Search UI here.

Testing the News API with Postman

You can learn how to use the News API in conjunction with Postman here.

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