Powered by Redocly

Repustate (v4)

Download OpenAPI specification:Download

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

There are two API endpoints. For text analytics and search, https://api.repustate.com serves as the primary endpoint.

Repustate IQ API calls should be sent to https://iq.repustate.com.

Make sure you use the correct endpoint depending on the API call you're using.

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.

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 (ISO 639-1) for the language you're interested in. The languages currently supported are:

LANGUAGE CODE
Arabic (العربية) ar
Chinese (中文) zh
Danish (Dansk) da
Dutch (Nederlands) nl
English en
Finnish (Suomalainen) fi
French (Français) fr
German (Deutsch) de
Hebrew (עִברִית) he
Indonesian id
Italian (Italiano) it
Japanese (日本語) ja
Korean (한국어) ko
Norwegian (Norsk) no
Polish (Polski) pl
Portuguese (Português) pt
Russian (русский) ru
Spanish (Español) es
Swedish (Svenska) sv
Turkish (Türk) tr
Thai (ไทย) th
Urdu (اردو) ur
Vietnamese (Tiếng Việt) vi

Authentication

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

Multiple Accounts

Sometimes it's necessary to maintain multiple profiles of sentiment rules, especially if you are an agency or a social media analytics company. You don't want to mix up one set of rules/scores with another. To that end, Repustate supports a means to keep your custom rules and subsequent sentiment analysis separate by use of a custom HTTP header "X-Sub-Account". This way, you still only need one Repustate API key, but can create rules for multiple "sub accounts" that you create and maintain on your end. Here's an example use of this header using cURL:

curl --header "X-Sub-Account: sub-account-1" 
     --data   "text=Score this using my custom rules"
              https://api.repustate.com/v4/{apikey}/score.json

Authentication

ApiKeyAuth

Security Scheme Type API Key
Header parameter name: x-api-key

REPUSTATE-IQ

REPUSTATE-IQ

Get list of existing projects for this API key

Return a list of project IDs for the given API key

Request
Security:
ApiKeyAuth
Responses
200

List existing projects

get/api/project/
Response samples
application/json
{
  • "projects": [
    ]
}

Create a new project in Repustate IQ

This creates a new project in Repustate IQ and makes it available for adding new data immediately

Request
Security:
ApiKeyAuth
Request Body schema: multipart/form-data
name
required
string

The name of the new project

username
required
string

Your Repustate IQ username (email address)

aspect_model
string

The aspect sentiment model to associate with this project. The model must already exist.

Responses
201

Numeric ID of newly created project

post/api/project/
Request samples
curl -H "x-api-key: $apikey" -d "name=My Project&aspect_model=hotel&username=user@example.com" https://iq.repustate.com/api/project/
Response samples
application/json
{
  • "project_id": 2345
}

Get existing data from project

Return JSON serialized objects representing data items added to this project

Request
Security:
ApiKeyAuth
path Parameters
project_id
required
integer

Numeric project ID

query Parameters
search
string

Free text search of the content in your project. Boolean operators (AND, NOT, OR) are supported.

external_id
string

External ID originally set when adding new data item

date_from
string

The earliest date to retrieve data from. YYYY-MM-DD format

date_to
string

The latest date to retrieve data until. YYYY-MM-DD format

sources
string

A comma separated list of source names you want to filter by

metadata_key
string

A single metadata key you want to filter data on. Data items that have this key, regardless of value, will be returned.

metadata
string

A valid JSON string containing 1 or more key/value pairs to be queried against. If multiple key/value pairs are included, this is the equivalent of an "and" operation and a Data item must contain all keys specified and all values must be present as well.

page
integer

The page offset to retrieve data from when paginating through results

page_size
integer

The number of data items to return per page. Default is 10. Maximum is 100.

Responses
200

OK

get/api/data/{project_id}/
Request samples
curl -H "x-api-key: $apikey" https://iq.repustate.com/api/data/{project_id}/?metadata_key=rating
Response samples
application/json
{
  • "total": 1592,
  • "data": [
    ]
}

Delete existing data from project

Delete Data items from a project. Careful, this operation cannot be undone.

Request
Security:
ApiKeyAuth
path Parameters
project_id
required
integer

Numeric project ID

query Parameters
date_from
string

The earliest date to retrieve data from. YYYY-MM-DD format

date_to
string

The latest date to retrieve data until. YYYY-MM-DD format

sources
string

A comma separated list of source names you want to filter by

metadata_key
string

A single metadata key you want to filter data on. Data items that have this key, regardless of value, will be deleted.

metadata
string

A valid JSON string containing 1 or more key/value pairs to be queried against. If multiple key/value pairs are included, this is the equivalent of an "and" operation and a Data item must contain all keys specified and all values must be present as well.

Responses
200

OK

delete/api/data/{project_id}/
Response samples
application/json
{
  • "total": 1592
}

Add data to an existing project

Add a new data item to an existing project. Data will be added to a queue and analyzed in order they are received. The immediate response value is the task ID for this request. If your project is setup to have a webhook, this task ID will be in the request body of the webhook.

Request
path Parameters
project_id
required
integer

Numeric project ID

Request Body schema: multipart/form-data
text
required
string

The text you want to analyze

lang
string

The language of the text you're analyze. If omitted, Repustate will automatically determine the language

external_id
string

Any string representing an external ID or reference. You can also fetch data by this data after added.

source
required
string

Name of data source for this data item

url
string

The URL this data item can be found at

date
string

The date this data item was published or created. YYYY-MM-DD format.

metadata
string

Additional metadata to store along with text. Keys will be searchable via API and Repustate IQ dashboard. Must be a valid JSON string in key-value pair format

Responses
201

Created

post/api/data/{project_id}/
Request samples
curl -H "x-api-key: $apikey" -d "text=my news story&lang=en&source=nytimes.com&url=nytimes.com/my-story" https://iq.repustate.com/api/data/{project_id}/
Response samples
application/json
{
  • "task_id": "2519ade0-1d78-11ec-9621-0242ac130002"
}

Get metadata keys (or values)

Return list of possible metadata keys. If a specific key is supplied, return the values for that key

Request
Security:
ApiKeyAuth
path Parameters
project_id
required
integer

Numeric project ID

query Parameters
key
string

The specific metadata key you want to retrive values for

Responses
200

OK

get/api/metadata/{project_id}/
Response samples
application/json
{
  • "keys": [
    ]
}

Fetch news, reviews and social media

Retrieve news, reviews or social media data from the specified data source

Request
Security:
ApiKeyAuth
path Parameters
project_id
required
integer

Numeric project ID

Request Body schema: multipart/form-data
search
required
string

The query parameter on which to fetch data from the requested source. Depending on the source, the required search value differs:

amazon: a URL for the product you want to analyze

douyin: a keyword search

google-maps-review: a keyword search for a product, location or place of interest

instagram: either a hashtag, URL to a specific post or a @username for a particular user

news: a keyword search with boolean operators (ANd, OR, NOT) supported

podcasts: a keyword search

reddit: a keyword search as well as boolean operators (AND, OR, NOT)

tiktok: either a hashtag, URL to a specific post or a @username for a particular user

twitter: a keyword search as well as any operators that Twitter supports

youtube: either a keyword search, URL to a specific video or the URL to a channel or playlist

source
required
string

The data source you want to fetch data from. Possible values are: amazon, douyin, google-maps-review, instagram, news, podcasts, reddit, reddit and tiktok, twitter and youtube

Responses
201

Request created

400

Fail (missing arguments)

post/api/project/{project_id}/data-request/
Request samples
curl -H "x-api-key: $apikey" -d "search=pizza&source=douyin" https://iq.repustate.com/api/project/{project_id}/data-request/

SENTIMENT-ANALYSIS

SENTIMENT ANALYSIS

Sentiment

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

A block of text to analyze. The sentiment score will be for the entire block of text.

lang
string

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.

emoji
integer

If you'd like to ignore emoji when calculating sentiment, pass '0' as a value. Any other value or omitting this argument will result in emoji being considered when determining sentiment.

Responses
200

OK

400

error

post/{apikey}/score.json
Request samples
multipart/form-data
text=This is a great day to go for a run
Response samples
application/json
{
  • "score": 0.9229105562880748,
  • "status": "OK"
}

Sentiment (bulk)

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

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
string

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.

emoji
integer

If you'd like to ignore emoji when calculating sentiment, pass '0' as a value. Any other value or omitting this argument will result in emoji being considered when determining sentiment.

Responses
200

OK

400

error

post/{apikey}/bulk-score.json
Request samples
curl -d "text1=This is one block of text&text2=This is another block of text" \
https://api.repustate.com/v4/{apikey}/bulk-score.json
Response samples
application/json
{
  • "status": "OK",
  • "results": {
    }
}

Sentiment (by topic)

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

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.

topics
required
string

Comma separated list of topics that you want to analyze the sentiment for.

lang
string

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.

Responses
200

OK

400

error

post/{apikey}/topic.json
Request samples
curl -d "text=I love the cake, but hated the hats&topics=cake,hats" \
https://api.repustate.com/v4/{apikey}/topic.json
Response samples
application/json
{
  • "status": "OK",
  • "results": [
    ]
}

Chunking with sentiment

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

The block of text to analyze.

lang
string

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.

Responses
200

OK

400

error

post/{apikey}/chunk.json
Request samples
curl -d "text=The service was great, the food was terrible" \
https://api.repustate.com/v4/{apikey}/chunk.json
Response samples
application/json
{
  • "status": "OK",
  • "chunks": [
    ]
}

List sentiment rules

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
lang
string

List the rules created for the given language code. Defaults to "en" (English).

Responses
200

OK

400

error

get/{apikey}/sentiment-rules.json
Request samples
curl https://api.repustate.com/v4/{apikey}/sentiment-rules.json
Response samples
application/json
{
  • "rules": [
    ],
  • "status": "OK"
}

Add sentiment rule

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

The word or phrase that you would like to alter the sentiment for. Use at most 3 words.

lang
string

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.

sentiment
required
any

The sentiment this rule should be interpreted as having. Possible values include 'pos', 'neg', 'neu'.

Enum: "pos" "neg" "neu"
rule_id
string <= 79 characters

Repustate will generate a unique ID for each rule you create. However, if you would like to pass in your own rule ID's, you can via the rule_id argument. Repustate will not ensure uniqueness if you supply your own rule IDs, so please make sure you handle that on your end.

Valid values are any strings less than 80 characters in length.

Responses
200

OK

400

error

post/{apikey}/sentiment-rules.json
Request samples
curl -d "text=that is so sick&sentiment=pos" \
https://api.repustate.com/v4/{apikey}/sentiment-rules.json
Response samples
application/json
{
  • "status": "OK",
  • "rule_id": "afde1234ab"
}

Delete sentiment rule

Delete a sentiment rule that you've previously created.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
lang
required
string

The language this sentiment rule applies to.

rule_id
required
string

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.

Responses
200

OK

delete/{apikey}/sentiment-rules.json
Request samples
curl https://api.repustate.com/v4/{apikey}/sentiment-rules.json -X DELETE -G -d "rule_id=abcde12323&lang=ar"
Response samples
application/json
{
  • "status": "OK"
}

SEMANTIC-ANALYSIS

SEMANTIC ANALYSIS

Named Entity Recognition

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:

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
string

The block of text you'd like to analyze for named entities & themes

lang
string

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.

Responses
200

OK

post/{apikey}/entities.json
Request samples
curl -d "text=Lowry and Siakam combined for 60 points in the Raps 101-85 win over the Cavs on Sunday" \
https://api.repustate.com/v4/{apikey}/entities.json
Response samples
application/json
{
  • "entities": [
    ],
  • "status": "OK",
  • "themes": [
    ]
}

Aspect-based sentiment

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 is a list of pre-built aspect models available for all customers to use:

  • airline
  • apparel
  • banking
  • cpg
  • ecommerce
  • government
  • hotel
  • insurance
  • restaurant
  • retail
  • telecom
  • voice_of_customer
  • voice_of_employee
  • voice_of_patient
Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
string

The text you'd like to analyze

model
required
any

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/models using the API calls below, you can also specify the ID of the model you created.

Enum: "hotel" "airline" "telco" "retail" "restaurant"
lang
string

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.

neutral
string

Show chunks that have neutral sentiment. Any value will do here e.g. neutral=1

context
string

Possible values are positive or negative. When analyzing survey responses, it is sometimes useful to include a value for context so Repustate's sentiment engine knows how to analyze the survey response given the question. If the question is 'How can we improve?' it is reasonable to assume the responses will be negative so set context=negative in the API call.

Responses
200

Each matching category will be a top level key with each matching text chunk a member in a list, along with its sentiment score

400

error

post/{apikey}/aspect.json
Request samples
curl -d "text=I loved the rooms but the coffee could have been better&model=hotel" \
https://api.repustate.com/v4/{apikey}/aspect.json
Response samples
application/json
{
  • "accommodations": [
    ],
  • "food": [
    ],
  • "status": "OK"
}

Classifications

List all classifications and their related default themes for the current version of the API

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/classifications.json
Request samples
curl https://api.repustate.com/v4/{apikey}/classifications.json
Response samples
application/json
{
  • "Event.activity": [ ],
  • "Event.airplane_crash": [
    ],
  • "Event.award": [ ],
  • "Event.coup": [
    ],
  • "Event.crime": [
    ],
  • "Event.financial": [
    ],
  • "Event.genocide": [
    ],
  • "Event.government_policy": [
    ],
  • "Event.massacre": [ ],
  • "Event.military_operation": [
    ],
  • "Event.social": [ ],
  • "Event.sport": [
    ],
  • "Event.sports": [
    ],
  • "Event.terrorist_attack": [
    ],
  • "Event.trade_show": [ ],
  • "Event.trial": [
    ],
  • "Event.war": [
    ],
  • "Health.artery": [
    ],
  • "Health.bone": [
    ],
  • "Health.disease": [
    ],
  • "Health.disorder": [
    ],
  • "Health.enzyme": [
    ],
  • "Health.muscle": [
    ],
  • "Health.organ": [
    ],
  • "Health.pharmaceutical": [
    ],
  • "Health.surgery": [
    ],
  • "Health.symptom": [
    ],
  • "Health.vitamin": [
    ],
  • "Location.airport": [ ],
  • "Location.borough": [ ],
  • "Location.bridge": [ ],
  • "Location.building": [ ],
  • "Location.canyon": [ ],
  • "Location.city": [ ],
  • "Location.city_area": [ ],
  • "Location.continent": [ ],
  • "Location.convention_centre": [ ],
  • "Location.country": [ ],
  • "Location.county": [ ],
  • "Location.desert": [ ],
  • "Location.direction": [ ],
  • "Location.government_residence": [
    ],
  • "Location.highway": [ ],
  • "Location.lake": [ ],
  • "Location.language": [ ],
  • "Location.lighthouse": [ ],
  • "Location.mountain": [ ],
  • "Location.mountain_range": [ ],
  • "Location.museum_or_gallery": [
    ],
  • "Location.neighborhood": [ ],
  • "Location.ocean": [ ],
  • "Location.park": [ ],
  • "Location.power_station": [
    ],
  • "Location.prison": [
    ],
  • "Location.public_space": [ ],
  • "Location.region": [ ],
  • "Location.religious_site": [
    ],
  • "Location.river": [ ],
  • "Location.sea": [ ],
  • "Location.stadium": [
    ],
  • "Location.state_or_province": [ ],
  • "Location.statue": [ ],
  • "Location.train_station": [
    ],
  • "Location.transit_line": [
    ],
  • "Location.university": [
    ],
  • "Location.waterfall": [ ],
  • "Number.financials": [
    ],
  • "Number.math_constant": [
    ],
  • "Org.broadcaster": [ ],
  • "Org.business": [
    ],
  • "Org.central_bank": [
    ],
  • "Org.college_sports_team": [
    ],
  • "Org.government_agency": [
    ],
  • "Org.government_committee": [
    ],
  • "Org.government_legislature": [
    ],
  • "Org.hackers": [
    ],
  • "Org.hospital": [
    ],
  • "Org.ideology": [
    ],
  • "Org.intelligence_agency": [
    ],
  • "Org.junior_hockey_team": [
    ],
  • "Org.militants": [
    ],
  • "Org.military": [
    ],
  • "Org.minor_league_baseball_team": [
    ],
  • "Org.music_group": [
    ],
  • "Org.news_agency": [ ],
  • "Org.newspaper": [ ],
  • "Org.nonprofit": [ ],
  • "Org.online_news": [ ],
  • "Org.political_party": [
    ],
  • "Org.pro_baseball_team": [
    ],
  • "Org.pro_basketball_team": [
    ],
  • "Org.pro_football_team": [
    ],
  • "Org.pro_hockey_team": [
    ],
  • "Org.pro_rugby_team": [
    ],
  • "Org.pro_soccer_team": [
    ],
  • "Org.radio_station": [
    ],
  • "Org.religion": [
    ],
  • "Org.sports_league": [
    ],
  • "Org.stock_exchange": [
    ],
  • "Org.stock_index": [
    ],
  • "Org.transit_authority": [ ],
  • "Org.transit_system": [ ],
  • "Person.academic": [ ],
  • "Person.actor": [
    ],
  • "Person.artist": [
    ],
  • "Person.author": [
    ],
  • "Person.broadcaster": [ ],
  • "Person.businessman": [
    ],
  • "Person.comedian": [
    ],
  • "Person.computer_scientist": [
    ],
  • "Person.criminal": [
    ],
  • "Person.director": [
    ],
  • "Person.economist": [
    ],
  • "Person.fictional_character": [
    ],
  • "Person.first_lady": [
    ],
  • "Person.first_nations": [ ],
  • "Person.government_employee": [
    ],
  • "Person.hacker": [
    ],
  • "Person.head_of_state_title": [
    ],
  • "Person.journalist": [ ],
  • "Person.judge": [
    ],
  • "Person.lawyer": [
    ],
  • "Person.military_personnel": [
    ],
  • "Person.military_rank": [
    ],
  • "Person.model": [ ],
  • "Person.music_group": [
    ],
  • "Person.musician": [
    ],
  • "Person.nationality": [ ],
  • "Person.philanthropist": [ ],
  • "Person.philosopher": [
    ],
  • "Person.physician": [
    ],
  • "Person.playwright": [
    ],
  • "Person.poet": [
    ],
  • "Person.politician": [
    ],
  • "Person.pro_athlete": [
    ],
  • "Person.radio_host": [
    ],
  • "Person.relationship": [ ],
  • "Person.religious_figure": [
    ],
  • "Person.religious_follower": [
    ],
  • "Person.religious_founder": [
    ],
  • "Person.royalty": [
    ],
  • "Person.scientist": [
    ],
  • "Person.software_engineer": [
    ],
  • "Person.sports_coach": [
    ],
  • "Person.sports_position": [
    ],
  • "Person.surgeon": [
    ],
  • "Person.terrorist": [
    ],
  • "Person.tv_presenter": [ ],
  • "Person.us_president": [
    ],
  • "Person.whistleblower": [ ],
  • "Person.world_leader": [
    ],
  • "Product.airplane": [ ],
  • "Product.album": [
    ],
  • "Product.automobile": [
    ],
  • "Product.beer": [
    ],
  • "Product.book": [
    ],
  • "Product.cargo_ship": [
    ],
  • "Product.coffee": [
    ],
  • "Product.commodity": [
    ],
  • "Product.cryptocurrency": [
    ],
  • "Product.currency": [
    ],
  • "Product.digital_media_player": [
    ],
  • "Product.financial": [
    ],
  • "Product.food": [
    ],
  • "Product.headphones": [
    ],
  • "Product.laundry_detergent": [ ],
  • "Product.magazine": [ ],
  • "Product.military_ship": [
    ],
  • "Product.mobile_phone": [
    ],
  • "Product.movie": [
    ],
  • "Product.music_genre": [
    ],
  • "Product.musical_instrument": [
    ],
  • "Product.pipeline_system": [
    ],
  • "Product.podcast": [ ],
  • "Product.smartphone": [
    ],
  • "Product.soft_drink": [
    ],
  • "Product.tablet": [
    ],
  • "Product.tea": [
    ],
  • "Product.tv_episode": [
    ],
  • "Product.tv_show": [
    ],
  • "Product.video_game": [
    ],
  • "Product.video_game_console": [
    ],
  • "Product.weapon": [
    ],
  • "Product.wine": [
    ],
  • "Science.amphibian": [
    ],
  • "Science.bird": [
    ],
  • "Science.chemical_compound": [
    ],
  • "Science.chemical_element": [
    ],
  • "Science.fish": [
    ],
  • "Science.galaxy": [
    ],
  • "Science.insect": [
    ],
  • "Science.mammal": [
    ],
  • "Science.planet": [
    ],
  • "Science.plant": [
    ],
  • "Science.reptile": [
    ],
  • "Science.star": [
    ],
  • "Technology.algorithm": [
    ],
  • "Technology.component": [
    ],
  • "Technology.cpu_architecture": [
    ],
  • "Technology.cpu_extensions": [
    ],
  • "Technology.file_format": [
    ],
  • "Technology.infotainment": [
    ],
  • "Technology.mobile_interface": [
    ],
  • "Technology.network": [
    ],
  • "Technology.operating_system": [
    ],
  • "Technology.programming_language": [
    ],
  • "Technology.social_network": [
    ],
  • "Technology.software": [
    ],
  • "Technology.software_development_process": [
    ],
  • "Technology.software_license": [
    ],
  • "Technology.streaming_service": [
    ],
  • "Technology.typeface": [
    ],
  • "Time.day": [ ],
  • "Time.holiday": [ ],
  • "Time.month": [ ],
  • "Time.season": [ ],
  • "status": "OK"
}

Text similarity

Calculate the semantic similarity, between 0 and 1, of two pieces of text in any language. Subject matter, entities, sentiment and entity metadata all play a factor in computing the semantic similarity

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text1
string

One of the blocks of text you'd like to compare for semantic similarity

text2
string

The other block of text you'd like to compare for semantic similarity

lang1
string

The two letter code of the language of the text in text1. If omitted, english is assumed.

lang2
string

The two letter code of the language of the text in text2. If omitted, english is assumed.

Responses
200

OK

post/{apikey}/similar.json
Request samples
curl -d "text1=Lowry and Siakam combined for 60 points in the Raps 101-85 win over the Cavs on Sunday&text2=LeBron James is excited about playing with Anthony Davis this year." \
https://api.repustate.com/v4/{apikey}/similar.json
Response samples
application/json
{
  • "score": 0,
  • "status": "OK"
}

OTHER

OTHER

List label filters

List all labels you've defined so far.

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/filter-rules.json
Request samples
curl https://api.repustate.com/v4/{apikey}/filter-rules.json
Response samples
application/json
{
  • "status": "OK",
  • "labels": [
    ]
}

Add label filter

Repustate can automatically assign labels to the text you analyze. Labels are defined as a mix of boolean operators, keyword matching, and a proximity operator. The following operators are allowed:

  • AND
  • OR (a blank space between terms is an implicit OR)
  • NOT
  • NEAR/N (proximity operator, meaning two terms must appear within N tokens of one another)
  • ~ (tilde, meaning exact match, other matching is case-insensitive)
  • * (wildcard matching for suffixes)

Zero, one, or more label filters can be returned for a given piece of text.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

These are the rules that determine whether or not a block of text should be assigned a particular label.

label
required
string

The value you'd like to assign to the rule you define below. This label is what Repustate returns when applying filters to text.

Responses
200

OK

post/{apikey}/filter-rules.json
Request samples
curl -d "text=hockey AND basketball&label=sports" \
https://api.repustate.com/v4/{apikey}/filter-rules.json
Response samples
application/json
{
  • "status": "OK"
}

Delete label filter

Deletes a previously created label filter.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
label
required
string

The value of the label you'd like to remove.

Responses
200

OK

400

error

delete/{apikey}/filter-rules.json
Request samples
curl https://api.repustate.com/v4/{apikey}/filter-rules.json -X DELETE -G -d "label=mylabel"
Response samples
application/json
{
  • "status": "OK"
}

Clean text

Get clean text from a remote source via its URL

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
url
required
string

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

Responses
200

OK

get/{apikey}/clean-html.json
Request samples
curl "https://api.repustate.com/v4/repustatedemopage/clean-html.json?url=http%3A%2F%2Fwww.example.com"
Response samples
application/json
{
  • "image": "",
  • "status": "OK",
  • "text": " Example Domain This domain is established to be used for illustrative examples in documents. You may use this domain in examples without prior coordination or asking for permission.\n More information...\n",
  • "title": "Example Domain",
  • "url": "http://www.example.com"
}

Clean text (HTML/PDF)

Get clean text from a HTML or PDF source

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
html
string

Raw HTML content that needs to be cleaned up

pdf
string

PDF content that you want cleaned up to show just the text

Responses
200

OK

400

error

post/{apikey}/clean-html.json
Request samples
curl -X "POST" "https://api.repustate.com/v4/{apikey}/clean-html.json" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "html=<html><head><title>Example Domain</title><meta charset=\"utf-8\" /><meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" /><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" /><style type=\"text/css\">body {background-color: #f0f0f2;margin: 0;padding: 0;font-family: \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;}div {width: 600px;margin: 5em auto;padding: 50px;background-color: #fff;border-radius: 1em;}a:link, a:visited {color: #38488f;text-decoration: none;}@media (max-width: 700px) {body {background-color: #fff;}div {width: auto;margin: 0 auto;border-radius: 0;padding: 1em;}}</style> </head><body><div><h1>Example Domain</h1><p>This domain is established to be used for illustrative examples in documents. You may use thisdomain in examples without prior coordination or asking for permission.</p><p><a href=\"http://www.iana.org/domains/example\">More information...</a></p></div></body></html>"
Response samples
application/json
{
  • "image": "",
  • "status": "OK",
  • "text": " Example Domain This domain is established to be used for illustrative examples in documents. You may use thisdomain in examples without prior coordination or asking for permission.\nMore information...\n",
  • "title": "Example Domain",
  • "url": ""
}

Apply filters

Apply the filter rules you've created to the supplied text block. Zero, one or more labels may be returned. For each label returned, we also show a list of (start, end) pairs designating where in the text the label was matched against.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

The block of text you'd like to analyze.

Responses
200

OK

post/{apikey}/filter.json
Request samples
curl -d "text=I love to play hockey" \
https://api.repustate.com/v4/{apikey}/filter.json
Response samples
application/json
{
  • "status": "OK",
  • "myFilterID": [
    ]
}

Part-of-speech tagging

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
Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

The block of text to analyze.

lang
string

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.

Responses
200

OK

post/{apikey}/pos.json
Request samples
curl -d "text=Let me see the part of speech tags for this sentence!" \
https://api.repustate.com/v4/{apikey}/pos.json
Response samples
application/json
{
  • "status": "OK",
  • "text": "Let me see the part of speech tags for this sentence!",
  • "language": "en",
  • "tags": [
    ]
}

Language detection

Given a piece of text , this API call will determine the language of the text in question. The response will contain a two letter code (ISO 639-1) representing the language identified. If a language cannot be accurately detected, an empty string will be returned as the language code.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
text
required
string

The block of text you'd like to analyze.

Responses
200

OK

post/{apikey}/detect-language.json
Request samples
curl -d "text=أنا أحب أن تأكل البيتزا مع أصدقائي" \
https://api.repustate.com/v4/{apikey}/detect-language.json
Response samples
application/json
{
  • "status": "OK",
  • "language": "ar"
}

Usage

Retrieve your API usage for the current billing period.

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/usage.json
Request samples
curl https://api.repustate.com/v4/{apikey}/usage.json
Response samples
application/json
{
  • "max_calls_allowed": 4000000,
  • "status": "OK",
  • "calls_used": 761099
}

List subaccounts

List all subaccounts created under the given API key

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/subaccounts.json
Request samples
curl https://api.repustate.com/v4/{apikey}/subaccounts.json
Response samples
application/json
{
  • "status": "OK",
  • "subaccounts": [
    ]
}

Last updated rule

Return the time stamp (in seconds since Jan 1, 1970) that a custom sentiment rule or filter rule was added.

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/last-updated-rule.json
Request samples
curl https://api.repustate.com/v4/{apikey}/last-updated-rule.json
Response samples
application/json
{
  • "status": "OK",
  • "sentiment": 1516912486821,
  • "filter": 151691248623
}

DEEP-SEARCH-API

Deep Search Overview

Repustate's Deep Search 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/v4

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.

Search

Search the specified Deep Search index for matching documents. Up to 100 documents are returned in one call, but search supports pagination via a cursor request argument.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
index
required
string

The index you'd like to query.

q
required
string

Your properly formatted Deep Search query. The query must conform to the Deep Search Query Language (DSQL) specification.

page
integer

Indicates which page to return results from. The offset is effective pagesize * page

pagesize
integer

The number of documents to return per request.

Responses
200

OK

400

error

get/{apikey}/search.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search.json?q=Person.politician.gender:M&index=my-index
Response samples
application/json
{
  • "matches": [
    ],
  • "next": 0,
  • "prev": 0,
  • "status": "OK",
  • "total": 1
}

Add document

Add a new document to a Deep Search index. If the index doesn't exist, it will be created.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
otherid
string

The custom id for this document

url
string

The URL for this document

index
required
string <= 40 characters

The index to which you'd like to add a new document. Index names can be any string no longer than 40 characters.

title
string

The title of your document

text
required
string

The body of the document you want to index.

store
boolean

Indicated whether or not to store the text in the backend after processing. Defaults to true. Supply '0' to disable storing

lang
string

The language your document is in. If left blank, English (en) is assumed.

Responses
200

OK

put/{apikey}/search.json
Request samples
curl -X PUT -d "index=my-index&title=my title&text=my new document with George Bush Sr. as the male politician&lang=en" \
https://api.repustate.com/v4/{apikey}/search.json
Response samples
application/json
{
  • "entities": {
    },
  • "lang": "en",
  • "sentiment": "neu",
  • "status": "OK",
  • "themes": "politics"
}

Delete document OR Index

Delete a document from your Deep Search Index

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
id
required
string

The document ID of the document you'd like to delete. It cannot be used in conjuction with index parameter

index
required
string

The index you'd like to delete. This operation cannot be undone. It cannot be used in conjuction with id parameter

Responses
200

OK

delete/{apikey}/search.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search.json -X DELETE -G -d "id=21345"
Response samples
application/json
{
  • "status": "OK"
}

List search classifications

List all possible classifications that Deep Search can return

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/search-classifications.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search-classifications.json
Response samples
application/json
{
  • "status": "OK",
  • "classifications": [
    ]
}

List search metadata

For a given Deep Search classification, show all possible metadata properties that be searched against.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
classification
required
string

The classification you want to list metadata for.

Responses
200

OK

get/{apikey}/search-metadata.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search-metadata.json?classification=Location.country
Response samples
application/json
{
  • "status": "OK",
  • "metadata": [
    ]
}

List custom entities

List all of the custom entities you have defined.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
lang
string

The language model for which you'd like to list the custom entities you've added. Default value is English (en)

Responses
200

OK

get/{apikey}/custom-entities.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-entities.json
Response samples
application/json
{
  • "entities": [
    ],
  • "status": "OK"
}

Add custom entity

You can add your own entities to be recognized by Deep Search. These entities will be localized to your account only and no one else can see or access them.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
title
required
string

The canonical name for your new entity

lang
required
string

The language model to add this new entity to

classifications
required
Array of strings

A comma separated list of classifications you'd like to associate with your entity. The classifications must be from the list of already defined Deep Search classifications.

Responses
200

OK

put/{apikey}/custom-entities.json
Request samples
curl -d "title=My Custom Entity&body=This is my custom entity&classifications[]=Person.politician" \
https://api.repustate.com/v4/{apikey}/custom-entities.json
Response samples
application/json
{
  • "status": "OK"
}

Delete custom entity

Deletes a custom entity you previously added.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
lang
string

The language model this entity should be removed from. Default value is English (en)

title
required
string

The title of the entity you previously added and now wish to delete

Responses
200

OK

delete/{apikey}/custom-entities.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-entities.json -X DELETE -d "title=My Custom Entity"
Response samples
application/json
{
  • "status": "OK"
}

List custom aliases

List all of the aliases defined for a custom entity you previously added

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
title
string

The title of the entity whose aliases you want to list

lang
string

The language model whose entities you wish to list

Responses
200

OK

get/{apikey}/custom-aliases.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-aliases.json?title=My+Custom+Entity&lang=en
Response samples
application/json
{
  • "entities": [
    ],
  • "status": "OK"
}

Add custom alias

Add an alias to a previously added entity. This could be their Twitter handle, a translation in another language etc.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
title
required
string

The name of your entity. It must already exist for the given language model

alias
required
string

The alias you want to add as another way of referring to this entity

lang
required
string

The language model to add this alias to

Responses
200

OK

put/{apikey}/custom-aliases.json
Request samples
curl -d "title=My Entity&alias=Alias 1&lang=en"
https://api.repustate.com/v4/{apikey}/custom-aliases.json
Response samples
application/json
{
  • "status": "OK"
}

Delete custom alias

Deletes a custom alias from one of your custom entities

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
alias
string

The alias you'd like to remove. It will be removed from all language models it appears in

lang
string

The language model to remove the alias from

Responses
200

OK

delete/{apikey}/custom-aliases.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-aliases.json -X DELETE -d "alias=My Alias&title=My Entity"
Response samples
application/json
{
  • "status": "OK"
}

DEEP-SEARCH-WIDGET

Add Deep Search to your website

Repustate provides a very simple way to embed a search bar anywhere on your website to allow you to let your customers (or internal users) the ability to search any of your Deep Search indexes.

Step 1. The basic HTML required

At a bare minimum, you'll have to create an element (likely a div) to contain the Deep Search search bar widget as well as import the Deep Search Javascript file. Below is a minimal example of what's needed:

<html>
    <head>
       <script type="text/javascript" src="https://path/to/deepsearch.js.min"></script>
   </head>
   <body>
       <div id="ds-container"></div>
   </body>
</html>

Step 2. Configure the search widget

Now let's create the widget itself. This code should be placed right before the closing body tag. Remember to put your API key and your Deep Search index in place of the variable names below.

const el = document.getElementById("ds-container");
const options = {
    "pagesize":30
};
const searchbar = new DeepSearch(el, YOUR_API_KEY, YOUR_INDEX, options);

That's it!

This will create a fully functional Deep Search widget on your website or in your web application. To read more about customizing the behaviour of your search widget and how to do more complex actions like pagination and rendering results, read the JS SDK docs.