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 periodX-RateLimit-Remaining
: The number of remaining requests in the current periodX-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:
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.