Overview

Repustate's API is a simple RESTful API. All responses are in JSON format. Pay special attention to which HTTP verb is required. Successful responses return an HTTP status code of 200. Incorrect or missing arguments will result in status code 400.

Endpoint

The API endpoint is located at https://api.repustate.com/v3

Rate Limiting

There are no limits to the number of calls you can make per minute/hour/day etc. however all accounts are subject to monthly limits according to the plan you signed up for. In the event that you exceed your monthly quota, you will receive an HTTP 429 response on all subsequent API calls.

Client Libraries

We've got client libraries to help you out. Download a Repustate client to get started.

Multiple languages

Most API calls can be used with multiple languages, not just in English. To specify another language, you have to provide the two letter code for the language you're interested in. The languages currently supported are:

Language Code Notes
English en Default
Arabic ar
Chinese zh
German de
French fr
Spanish es
Italian it
Russian ru
Polish pl

Authentication

There is no explicit authentication mechanism. You simply include your API key in each API request.

POST
Named entity recognition /entities.json

Entities are people, places, business, brands, and ideas that are notable. Repustate will identify any and all in your text and will return them categorized. The full list of possible themes for a block of text are below:

Name Notes
lang The two letter code of the language you want to analyze the sentiment in. The default is English (en); you do not need to specify anything if you're just scoring English text.
ignore_text Specify any value for this key to indicate you don't want the original text back in the response. The default is to include the original text.
text The block of text you'd like to analyze for named entities.
Name Notes
entities All relevant entities in your text, given the context and subject matter. You will get a list of entities along with the category they belong to.
expansions If a named entity is contained in your text and Repustate has extrapolated what that entity might be, you will see the expansion here. For example, if the term 'Obama' appeared by itself, then Repustate must expand it to 'Barack Obama'.
themes If any themes are present in your text, they will be listed here in order of relevance.
{
  "status": "OK", 
  "entities": [
    {"United States": "location.country"}, 
    {"president": "government.position"}, 
    {"Obama": "government.us_presidents"}
  ], 
  "expansions": [{
    "Obama": "Barack Obama"
  }], 
  "themes": [
    "government"
  ], 
  "text": "Obama is the president of the United States."
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.entities("Obama is the president of the United States")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.entities("Obama is the president of the United States")
                  
curl -d "text=Obama is the president of the United States"\
   https://api.repustate.com/v3/YOUR_API_KEY/entities.json

POST
Categorizations /categorize.json

Sometimes sentiment alone isn't enough - you want to know which aspects of a particular subject carry sentiment. For example, if you're a hotel, you might be interested in knowing people's opinions on your staff, as well as your amenities and the food offerings.
This API call automatically categorizes text according to industry-specific categories. Below you'll find information on which industry verticals are supported as well as the categories for each:

hotel
food, price, location, accommodations, amenities, staff

airline
price, staff, in-flight, loyalty

restaurant
price, food, staff, location, atmosphere, events

telecom
price, service, products, staff

Name Notes
niche required The group of categories you're interested in using. Options are one of: hotel, airline, telco, retail, restaurant. If you have created your own rules/niches using the API calls below, you can also specify the ID of the niche you created.
lang The two letter code of the language you want to analyze the sentiment in. The default is English (en); you do not need to specify anything if you're just scoring English text.
text The text you'd like to analyze
Name Notes
categories Each matching category will be a top level key with each matching text chunk a member in a list, along with its sentiment score.
{
  "food": [
    {
      "chunk": "the coffee could have been better", 
      "score": -0.20655
    }
  ], 
  "accommodations": [
    {
      "chunk": "I loved the rooms", 
      "score": 0.25819
    }
  ]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.categorize(text:"I loved the rooms but the coffee could have been better", niche:"hotel")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.categorize(text="I loved the rooms but the coffee could have been better", niche="hotel")
                  
curl -d "text=I loved the rooms but the coffee could have been better&niche=hotel"\
   https://api.repustate.com/v3/YOUR_API_KEY/categorize.json