The Basics

If you're comfortable with using the Twitter or Facebook API, then this will be a cinch. 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.

Endpoints

API calls are made to either http://api.repustate.com/ OR if you want to keep your data away from prying eyes, https://api.repustate.com/

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 montly amount, you will receive an HTTP 429 response on all subsequent API calls.

Client Libraries

We've got client libraries to help you out. Head over to our Bit Bucket repo.

Multiple languages

Some of the API calls below can be operated on 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. Below are the currently supported languages:

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

Lastly, if you see something wrong or would like us to add or improve things, please let us know.

Sample call

Here's an example of an API call. Each API call requires that you pass in a version number, your API key and specify a format for the response. In this example below, our API key is "demokey" and we're using version 3 (v3) of the API

curl -d "text=I love Repustate!" http://api.repustate.com/v3/API_KEY/score.json

NB: "demokey" is just a sample API key. You should replace it with your actual key which will look something like this: 05b0cb45065491ed795fbf14ac18a94d06353d2a

Authentication

There is no explicit authentication mechanism, you just include your API key in each and every call to the API.

Sentiment - POST

Repustate's sentiment analysis allows you to determine the sentiment (how people "feel" about a particular topic) from any data source you have access to. Like most of Repustate's API calls, you have a choice of how to specify your arguments. You can supply one of a block of text, a single URL, or a list of URLs.

Arguments:

Name Required? Notes
text No A block of text to analyze. The sentiment score will be for the entire block of text.
lang No 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.

Note that one of text or url must be included, but not both. If both are included, the text value will be used.

Response:

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).
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.

Usage:

curl -d "text=I love you Repustate" http://api.repustate.com/v3/API_KEY/score.json

Here is a sample response:

    {
  "status": "OK", 
  "score": 1.0
}
                        

Sentiment (bulk) - POST

If you plan on analyzing a large number of text documents (i.e you already have the text and you're not relying on Repustate to grab the content via a URL) 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.

Arguments:

Name Required? Notes
text Yes 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 No 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 No 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.

All languages can be analyzed in bulk however non-english languages are limited to 100 pieces of text at a time, for now.

When enumerating blocks of text, please start from 1 (e.g text1, text2, ... , textN)

Response:

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).
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.

Usage:

curl -d "text1=first block of text&text2=second block of text" http://api.repustate.com/v3/API_KEY/bulk-score.json

Here is a sample response:

    {
  "status": "OK", 
  "results": [
    {
      "score": 1.0, 
      "id": 1
    }, 
    {
      "score": 0.87, 
      "id": 2
    }
  ]
}
                        

Sentiment (by topic) - POST

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.

Arguments:

Name Required? Notes
topics Yes Comma separated list of topics that you want to analyze the sentiment for.
text Yes 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 No The language to analyze the text in. Default is 'en' (English).

Response:

status The status of your request, OK or Fail if there was an error.
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.

Usage:

curl -d "topics=Obama,cake&text=President Obama was very happy to announce new legislation today. Obama was greeted with a round of applause, but the cake they served afterwards was horrible and left everybody running for the exits." https://api.repustate.com/v3/YOUR_API_KEY/topic.json

Here is a sample response:

    {
  "status": "OK", 
  "results": [
    {
      "topic": "Obama", 
      "freq": 2, 
      "score": 0.1136, 
      "id": "text1"
    }, 
    {
      "topic": "cake", 
      "freq": 2, 
      "score": -0.39129, 
      "id": "text1"
    }
  ]
}
                        

Chunking with sentiment - POST

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.

Arguments:

Name Required? Notes
lang No The language of your text. English ('en') is the default and does not need to be specified.
text No The block of text to analyze.

Note that one of text or url must be included, but not both. If both are included, the text value will be used.

Response:

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).
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.

Usage:

curl -d "text=The food was great, but the service was terrible." http://api.repustate.com/v3/API_KEY/chunk.json

Here is a sample response:

    {
  "status": "OK", 
  "chunks": [
    {
      "chunk": "The service was great", 
      "score": 1
    }, 
    {
      "chunk": "the food was terrible", 
      "score": -1
    }
  ]
}
                        

Add Custom Sentiment Rule - POST

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.

Arguments:

Name Required? Notes
text Yes The word or phrase that you would like to alter the sentiment for. Use at most 3 words.
sentiment Yes The sentiment this rule should be interpreted as having. Possible values include 'pos', 'neg', 'neu'.
lang No Two letter language code of the language this new rule applies to. The default is English ('en').

When submitting new definitions, restrict it to at most 3 words. Anything longer will not work.

Response:

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).

Usage:

curl -d "text=love&sentiment=neg" "https://api.repustate.com/v3/API_KEY/sentiment-rules.json

Here is a sample response:

    {"status":"OK"}
                        

List sentiment rules - GET

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.

Arguments:

Name Required? Notes

Response:

status The status of your request, either OK or FAIL.
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.

Usage:

curl https://api.repustate.com/v3/API_KEY/sentiment-rules.json?lang=en

Here is a sample response:

    {"status":"OK", "rules":["text":"love", "sentiment":"neg", "rule_id":"abcdef12321321312"]}
                        

Delete sentiment rule - DELETE

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.

Arguments:

Name Required? Notes
rule_id Yes 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.

Response:

status The status of your request, either OK or FAIL.

Usage:

curl -X DELETE -d "rule_id=1234567abcdef123123" https://api.repustate.com/v3/YOUR_API_KEY/sentiment-rules.json

Here is a sample response:

    {"status":"OK"}
                        

Commit sentiment rules - PUT

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.

Arguments:

Name Required? Notes

Response:

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).

Usage:

curl -X PUT "https://api.repustate.com/v3/API_KEY/sentiment-rules.json"

Here is a sample response:

    {"status":"OK"}
                        

Clean HTML - GET

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 with Readability.js, this API call replicates Readability's functionality.

If the article has a main image, the URL to this image will also be returned.

Arguments:

Name Required? Notes
url Yes 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.

* Please note:  This call doesn't work very well on home pages e.g. cnn.com, ebay.com, nytimes.com. Its intended use is for single article pages.

Response:

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).
text The most important text extracted from the URL
image The URL to the "main" image, if it exists, for this web page.

Usage:

Here is a sample response:

    {
  "status": "OK", 
  "text": "I'm clean HTML without all of the clutter of tags."
}
                        

POS tagging - POST

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 

Arguments:

Name Required? Notes
text Yes The text you would like to tag.
lang No The language code for the language your text is in. If omitted, English is assumed.

While the tags can be more specific (different verb tenses etc.) we have simplified the list of possible tags and collapsed all possible tags into the minimal set required.

Response:

tags A list of hashes, with a key 'tag' and a key 'word', representing the part-of-speech tag for the given word, respectively.
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).
text The original text that was analyzed
language The language of the text.

Usage:

curl -d "text=Let me see the part of speech tags for this sentence!" http://api.repustate.com/v3/API_KEY/pos.json

Here is a sample response:

    {
  "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": "!"
    }
  ]
}
                        

Language detection - POST,GET

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.

Arguments:

Name Required? Notes
text No The block of text you'd like to analyze.

Response:

status OK of Fail.
text The text that was analyzed.
language Two letter code representing the language identified.

Usage:

http://api.repustate.com/v3/YOUR_API_KEY/detect-language.json?url=http://tcrn.ch/aav9Ty

Here is a sample response:

    {
  "status": "OK", 
  "text": "The service was great, but the food was terrible.", 
  "language": "en"
}
                        

Usage - GET

Retrieve your API usage for the current billing period.

Arguments:

Name Required? Notes

Response:

calls_used The total API calls that have been used this billing period
status The status of this API call, or an error if something went wrong.
max_calls_allowed The maximum number of API calls your account is entitled to for the current billing period.

Usage:

curl http://api.repustate.com/v3/YOUR_API_KEY/usage.json

Here is a sample response:

    {
  "max_calls_allowed": 4000000, 
  "status": "OK", 
  "calls_used": 761099
}