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.

• Calling the API
• SDKs
• Endpoints
• FAQs

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:

1. By sending HTTP POST or GET requests to https://api.aylien.com/api/v1 followed by the endpoint name, e.g. for a Concept Extraction call the full URL would be https://api.aylien.com/api/v1/concepts.
2. 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 plan
• X-RateLimit-Remaining: The amount remaining on your daily quota
• X-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

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:

The table below shows currently supported languages across different endpoints of our API.

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. All of our Text Analysis API endpoints are available to Free users. However, Image Tagging is only available to paid users.

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.