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
Sentiment /score.json

Extract the sentiment from a piece of text. Scores range from -1 (negative) to 1 (positive) with a score of 0 being "neutral". Emoticons, emoji, and internet short forms are given greater weight in the algorithm.

Name Notes
text required A block of text to analyze. The sentiment score will be for the entire block of text.
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.
Name Notes
score A decimal number. Negative numbers mean negative sentiment and positive numbers mean positive. Any score "close" to 0 can be interpreted as being neutral.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "score": 1.0
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.sentiment("This is a great day to go for a run")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.sentiment("This is a great day to go for a run")
                  
curl -d "text=This is a great day to go for a run" \
  https://api.repustate.com/v3/YOUR_API_KEY/score.json

POST
Sentiment (bulk) /bulk-score.json

If you plan on analyzing a large number of text documents then we suggest utilizing our bulk API. With this API call, you can POST up to 500 pieces of text a time when using English and 100 pieces of text at a time for other languages and Repustate will return a JSON list with a score for each block of text.

Name Notes
text required One or more blocks of text. Each argument starting with 'text' will be scored. To help you reconcile scores with blocks of text, Repustate requires that you append some sort of ID to the POST argument. For example, if you had 50 blocks of text, you could enumerate them from 1 to 50 as text1, text2, ..., text50.
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.
chunk If provided (it can be any value, the key "chunk" just has to be appear in the POST somewhere), each result will also have a list of chunks that were extracted from the text.
Name Notes
results A list of scores and id's, one for each block of text POSTed. See below for the format of each item in this list.
result Each score result will consist of a score (decimal number) and an ID (as defined by the original request.) There can be 0 or more results returned.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "results": [
    {
      "score": 1.0, 
      "id": 1
    }, 
    {
      "score": 0.87, 
      "id": 2
    }
  ]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.bulk_sentiment(['This is one block of text', 'This is another block of text'])
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.bulk_sentiment(['This is one block of text', 'This is another block of text'])
                  
curl -d "text1=This is one block of text&text2=This is another block of text" \
  https://api.repustate.com/v3/YOUR_API_KEY/bulk-score.json

POST
Sentiment (by topic) /topic.json

Longer text can sometimes contain multiple topics or ideas. If you want the sentiment as it relates to a particular topic within a block of text, then this API call will scope the sentiment to one (or more) topics.

Name Notes
topics required Comma separated list of topics that you want to analyze the sentiment for.
text required The block or blocks of text you want to analyze sentiment for. If you want to include multiple blocks of text in one API call, enumerate this parameter (e.g. text1, text2, text3) and the response will include a reference to each text block's ID so you can reconcile scores on your end.
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.
Name Notes
results A list of scores, where each topic gets a score for each block of text in your request. Included in the response is the ID of the text block, the score for each topic in that text block, as well as the frequency with which the topic occurred in the block of text.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "results": [
    {
      "topic": "cake", 
      "freq": 1, 
      "score": 0.1136, 
    }, 
    {
      "topic": "hats", 
      "freq": 1, 
      "score": -0.39129,
     }
  ]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.topic_sentiment(text: 'I love the cake, but hated the hats', topics: 'cake,hats')
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.topic_sentiment(text='I love the cake, but hated the hats', topics='cake,hats')
                  
curl -d "text=I love the cake, but hated the hats&topics=cake,hats" \
  https://api.repustate.com/v3/YOUR_API_KEY/topic.json

POST
Chunking with sentiment /chunk.json

Often you might be interested in the individual portions of a document's sentiment, rather than the overall sentiment. Chunking is the process of breaking up a document into its more interesting parts and evaluating the sentiment on it. This API call chunks and returns the sentiment for each chunk.

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.
text The block of text to analyze.
Name Notes
chunks A list of chunks, where each chunk has a score associated with it. If your response type is XML, the scores and chunks come sequentially one after the other.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "chunks": [
    {
      "chunk": "The service was great", 
      "score": 1
    }, 
    {
      "chunk": "the food was terrible", 
      "score": -1
    }
  ]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.chunk("The service was great, the food was terrible")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.chunk("The service was great, the food was terrible")
                  
curl -d "text=The service was great, the food was terrible" \
  https://api.repustate.com/v3/YOUR_API_KEY/chunk.json

POST
Add Custom Sentiment Rule /sentiment-rules.json

If you'd like to add a custom rule for sentiment to either override how Repustate treats some words or to create domain specific language, this API call will do that for you. Remember to commit your changes using the commit API call or else your changes won't appear.

Name Notes
text required The word or phrase that you would like to alter the sentiment for. Use at most 3 words.
sentiment required The sentiment this rule should be interpreted as having. Possible values include 'pos', 'neg', 'neu'.
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.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
    "status":"OK", 
    "rule_id":"afde1234ab"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.add_sentiment_rule(text: "that is so sick", sentiment: "pos")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.add_sentiment_rule("that is so sick", "pos")
                  
curl -d "text=that is so sick&sentiment=pos" \
  https://api.repustate.com/v3/YOUR_API_KEY/sentiment-rules.json

GET
List sentiment rules /sentiment-rules.json

List the custom sentiment rules you have created in a given language. Make note of the rule_id that is returned in the response, you'll need it if you want to delete a rule at a later point.

This call does not take any arguments.
Name Notes
rules A list of the rules you have created. Each rule will contain the original text, the sentiment you defined for this rule and the rule's unique ID.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
   "status":"OK", 
   "rules":[
        "text":"love", 
        "sentiment":"neg",
        "rule_id":"abcdef12321"
    ]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.list_sentiment_rules
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.list_sentiment_rules()
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/sentiment-rules.json
                        

DELETE
Delete sentiment rule /sentiment-rules.json

Delete a sentiment rule that you've previously created. You'll have to commit your changes using the commit sentiment rules API call after deleting the rule.

Name Notes
rule_id required The ID of the rule you'd like to delete. To obtain rule ID's, you'll have to first make a call to list all rules you've created.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{"status":"OK"}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
rules = client.list_sentiment_rules
rule_id = rules[0]['rule_id']
client.delete_sentiment_rule(rule_id)
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
rules = client.list_sentiment_rules()
rule_id = rules[0]['rule_id']
client.delete_sentiment_rule(rule_id)
                  
curl -X DELETE -d "rule_id=abcde12323" \
  https://api.repustate.com/v3/YOUR_API_KEY/sentiment-rules.json

PUT
Commit sentiment rules /sentiment-rules.json

Any rules you've created using the "Add sentiment rule" API call (or simiarly, any rules deleted via the API) won't be in effect until this API call is made. This call tells Repustate to update the language models associated with your API key. You only need to call it once after you've added/edited/deleted all of your rules.

This call does not take any arguments.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{"status":"OK"}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.commit_sentiment_rules
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.commit_sentiment_rules()
                  
curl -X PUT \
  https://api.repustate.com/v3/YOUR_API_KEY/sentiment-rules.json

POST
Named entity recognition /entities.json

Repustate will classify people, places, brands, companies, stock symbols and more into one of over 500 entity classifications. Which entity classification is used for a given term is based on the context surrounding the term and the overall theme of the text. The complete list of possible categories for a given term is available here..
** Please note that not all categories are supported for each language. **

When using the this API call, Repustate will classify text as belonging to one or more from the following list of themes:

art automotive books
business education fashion
finance food government
energy health law
military movies music
promotion real estate religion
science social media space
sports technology travel
tv video games weather
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.
text The block of text you'd like to analyze for named entities. If this isn't specified, you must specify a URL then.
url The URL of a web page you'd like to analyze for named entities. If this isn't specified, you must specify a block of 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.
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'.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
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 automically 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 If your response type is JSON, each matching category will be a top level key with each matching text chunk a member in a list, along with its sentiment score. If your response type is XML, each matching category is a to level node where each chunk and its score are enclosed within an "element" tag i.e. you can have more than one element tag appearing in the document.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "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

GET
Clean HTML /clean-html.json

This API call will extract out the most important part of a web page, removing all tags and any common header or footer content. For those familiar withReadability.js, this API call replicates Readability's functionality.
If the article has a main image, the URL to this image will also be returned.

Name Notes
url required Any valid URL that has been url encoded ("escaped"). If the URL specified is a URL-shortened one (e.g. bit.ly), Repustate will follow the redirects properly until the final page is found.
Name Notes
text The most important text extracted from the URL
image The URL to the "main" image, if it exists, for this web page.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "text": "I'm clean HTML without all of the clutter of tags."
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.clean_html("http://www.example.com")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.clean_html("http://www.example.com")
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/clean-html.json?url=http%3A%2F%2Fwww.example.com
                        

POST
Part-of-speech tagging /pos.json

Get access to Repustate's all purpose part-of-speech tagger in the language of your choice. This API call returns the entire text block tagged with the part of speech for each word.
The list of possible tags and their meaning for ALL languages is below:

NN: noun
ADJ: adjective
VB: verb
ADV: adverb
CONJ: conjunction
PREP: preposition
ART: article
PP: pronoun
POSS: possessive noun
PUNC: punctuation

Name Notes
text required The text you would like to tag.
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.
Name Notes
tags A list of hashes, with a key 'tag' and a key 'word', representing the part-of-speech tag for the given word, respectively.
text The original text that was analyzed
language The language of the text.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "text": "Let me see the part of speech tags for this sentence!", 
  "language": "en", 
  "tags": [
    {
      "tag": "VB", 
      "word": "let"
    }, 
    {
      "tag": "PP", 
      "word": "me"
    }, 
    {
      "tag": "VB", 
      "word": "see"
    }, 
    {
      "tag": "ART", 
      "word": "the"
    }, 
    {
      "tag": "NN", 
      "word": "part"
    }, 
    {
      "tag": "PREP", 
      "word": "of"
    }, 
    {
      "tag": "NN", 
      "word": "speech"
    }, 
    {
      "tag": "NN", 
      "word": "tag"
    }, 
    {
      "tag": "PREP", 
      "word": "for"
    }, 
    {
      "tag": "ART", 
      "word": "this"
    }, 
    {
      "tag": "NN", 
      "word": "sentence"
    }, 
    {
      "tag": "PUNC", 
      "word": "!"
    }
  ]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.pos_tags("Let me see the part of speech tags for this sentence!")
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.pos_tags("Let me see the part of speech tags for this sentence!")
                  
curl -d "text=Let me see the part of speech tags for this sentence!" \
  https://api.repustate.com/v3/YOUR_API_KEY/pos.json

POST
Language detection /detect-language.json

Given a piece of text (or a URL to a website), this API call will determine the language of the text in question. The response will contain a two letter code representing the language identified. Possible languages are:

English (en)
French (fr)
German (de)
Spanish (es)
Dutch (nl)
Chinese (zh)
Arabic (ar)
Russian (ru)
Italian (it)
Polish (pl)

If a language cannot be accurately detected, an empty string will be returned as the language code.

Name Notes
text The block of text you'd like to analyze.
Name Notes
text The text that was analyzed.
language Two letter code representing the language identified.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status": "OK", 
  "language": "ar"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.detect_language('أنا أحب أن تأكل البيتزا مع أصدقائي')
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.detect_language("أنا أحب أن تأكل البيتزا مع أصدقائي")
                  
curl -d "text=أنا أحب أن تأكل البيتزا مع أصدقائي" \
  https://api.repustate.com/v3/YOUR_API_KEY/detect-language.json

GET
Usage /usage.json

Retrieve your API usage for the current billing period.

This call does not take any arguments.
Name Notes
calls_used The total API calls that have been used this billing period
max_calls_allowed The maximum number of API calls your account is entitled to for the current billing period.
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "max_calls_allowed": 4000000, 
  "status": "OK", 
  "calls_used": 761099
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.usage
                    
from repustate import Repustate

client = Repustate(api_key='YOUR_API_KEY', version='v3')
client.usage()
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/usage.json