Getting Started
The AYLIEN Text Analysis API is a package of Natural Language Processing and Machine Learning-powered APIs for analyzing and extracting various kinds of information from textual content.
Here you’ll find everything you need to know about using the Text Analysis API. If you’re a new user, you’ll need to grab an API Key here.
API Keys and Credentials
In order to use the Text Analysis API, you must create an account on our Developer Portal, and obtain an API ID and Key:
Using the API
Once you have your API Key and ID, you can use the Text Analysis API in two ways:
- By sending HTTP
POST
orGET
requests tohttps://api.aylien.com/api/v1
followed by the endpoint name, e.g. for a Concept Extraction call the full URL would behttps://api.aylien.com/api/v1/concepts
. - By using one of our SDKs. If you're using an SDK, skip the following sections and jump straight to Endpoints for examples on how to utilize the API using any of the SDKs.
Authorization
Requests to the API must be authorized by adding the following headers:
X-AYLIEN-TextAPI-Application-Key
must be set to your Application Key.X-AYLIEN-TextAPI-Application-ID
must be set to your Application ID.
GET or POST
Most endpoints support both GET
and POST
methods. If you're dealing with long documents, please consider using POST
.
Maximum Input Size
Maximum Request URI size is 8 kB and the body can't be larger than 6 MB.
JSON or XML
The API returns JSON results by default. You can request results in JSON or XML formats for all of the endpoints. Set Accept
header to text/xml
or application/json
to change the format of your results.
Rate Limits
Based on your subscription plan, your application is subject to daily and per-minute limits. There are three response headers you can use to check your quota allowance, the number of calls remaining on your quota, and the time and date your quota will be reset:
X-RateLimit-Limit
: Daily limit of your current planX-RateLimit-Remaining
: The amount remaining on your daily quotaX-RateLimit-Reset
: When the quotas are reset
Note: If you're using one of our SDKs, you can use the following methods to retrieve the above values:
print client.RateLimits()
puts client.rate_limits
var limits = client.RateLimit
Console.WriteLine("Limit: " + limits["Limit"]);
Console.WriteLine("Remaining: " + limits["Remaining"]);
Console.WriteLine("Reset: " + limits["Reset"]);
textapi.sentiment({'text': 'John is a very good football player', function(err, result, rateLimits) {
console.log(rateLimits);
});
<?php
var_dump($textapi->getRateLimits());
?>
TextAPIClient.RateLimits rateLimits = client.getRateLimits();
System.out.println(rateLimits.getLimit());
System.out.println(rateLimits.getRemaining());
System.out.println(rateLimits.getReset());
fmt.Printf("%v\n", client.RateLimits)
Retrieve your remaining quotas in your application
HTTP Statuses
Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.
In the event of a problem, the status will contain an error code, while the body of the response will usually contain additional information about the problem that was encountered.
In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.
Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.
If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.
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. |
404 | Not Found | The URI requested is invalid or the resource requested, does not exist. |
405 | Method Not Allowed | A request method is not supported for the requested resource. |
410 | Gone | The URI requested is no longer available |
414 | URI Too Long | The URI provided was too long for the server to process. |
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 engineers have been informed. If you continue to have problems, contact [support@aylien.com][4]. |
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. |
Language Support
Text Analysis API supports multiple (human) languages which can be selected using the language
parameter, supported by most of the endpoints. Please refer to the table below for valid language codes:
English | German | French | Italian | Spanish | Portuguese | |
---|---|---|---|---|---|---|
Language codes (language ) |
en |
de |
fr |
it |
es |
pt |
The table below shows currently supported languages across different endpoints of our API.
Endpoint | English | German | French | Italian | Spanish | Portuguese |
---|---|---|---|---|---|---|
Article Extraction | ||||||
Summarization | ||||||
Classification | ||||||
Sentiment Analysis | ||||||
Entity Extraction | ||||||
Concept Extraction | ||||||
Hashtag Suggestion | ||||||
Language Detection |
Miscellaneous Info
Reporting issues
The results you get from the Text Analysis API, like other data-driven systems, are likely to contain errors from time to time. If you notice any systematic or major errors, please report them using this form and we will review them in due course.
Frequently Asked Questions
How do I retrieve my API Key and App ID?
Log in to your Developer Portal using the credentials you used when you registered to use the API.
Which languages are supported by the API?
Please refer to our Language Support section above.
I've registered for the Free plan, is my account restricted in any way?
On the Free plan, you can make up to 1,000 Hits to the API per day for a limited time.
I want to start using the Image Tagging endpoint, how can I enable that feature?
You need to upgrade to a paid plan to start making calls to the Image Tagging endpoint. More information on paid plans can be found here.
How do I check my rate limit?
Please refer to the Rate Limits section.
How do I switch to Tweet mode in Sentiment Analysis?
You can switch to tweet
mode in Sentiment by adding a mode=tweet
parameter to your request.
My results aren't always accurate. Why?
Like any other data-driven system, our API might make mistakes from time to time. Please report errors using this form.
How do I change the format of the results I get from your API?
By default, the API returns JSON results. However, you can request results in JSON or XML formats. Please refer to the Results Format section for more information.
How can I upgrade to a larger plan?
Upgrading to a larger plan is easy. Log in to your Developer Portal, navigate to the Plans section, and choose which plan you wish to upgrade to. Please note that you can only change plans once you’ve entered your credit card details.
How do I log a support query?
You can drop us an email at support@aylien.com or use the chat widget in the bottom right corner of the screen to report any issues you might face.
Can I call the API directly (i.e. without using one of the SDKs)?
Yes! Please refer to Usage.