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

REPUSTATE-IQ

Get list of existing projects for this API key

Return a list of project IDs for the given API key

SecurityApiKeyAuth

Responses

200

List existing projects

get/api/project/

Response samples

application/json

{"projects": [{"name": "My Project",
"aspect_model": "hotel",
"id": 2345
}
]
}

Create a new project in Repustate IQ

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

SecurityApiKeyAuth

Request

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

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

SecurityApiKeyAuth

Request

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

get/api/data/{project_id}/

Request samples

CURL

curl -H "x-api-key: $apikey" https://iq.repustate.com/api/data/{project_id}/?metadata_key=rating

Response samples

application/json

{"total": 1592,
"data": [{"text": "I loved their coffee",
"url": "https://example.com",
"date_created": "2021-01-01",
"source": "News",
"sentiment": 0.975,
"language": "en",
"aspects": [{"label": "food",
"sentiment": 0.9775,
"chunk": "I loved their coffee",
"topic": "coffee",
"sentiment_text": "loved"
}
],
"entities": [{"title": "Coffee",
"classifications": "Product.drink"
},
{"title": "Love",
"classifications": "Person.emotion"
}
]
}
]
}

Delete existing data from project

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

SecurityApiKeyAuth

Request

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

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

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

SecurityApiKeyAuth

Request

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

get/api/metadata/{project_id}/

Response samples

application/json

{"keys": ["rating",
"age",
"gender",
"budget"
]
}

Fetch news, reviews and social media

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

SecurityApiKeyAuth

Request

path Parameters

project_id

required

integer

Numeric project ID

Request Body schema: application/json

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 `glassdoor`: the URL for the company's profile `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 `opentable`: the URL for the restaurant's profile `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 `yelp`: the URL for the business' profile `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`, `glassdoor`, `google-maps-review`, `instagram`, `news`, `opentable`, `podcasts`, `reddit`, `reddit` and `tiktok`, `twitter`, `youtube` and `yelp`
doCreateSchedule	boolean Set this value to 1 if you want to repeatedly request this data source, adding only new data each time.
scheduleFrequency	integer A number indicating how often you'd like to repeate the scheduled retrieval of this data source. Must be used in combination with `schedulePeriod`
schedulePeriod	string The units for the `scheduleFrequency`. Possible values are `days` or `weeks`.
scheduleDatetime	string The date you'd like the schedule begin. Must be at least today's date. Format must be YYYY-MM-DDTHH:MM+0000 where YYYY is the year, MM is the two digit month, DD is the two digit day, HH is the two digit hour (24 hour time), MM is the two digit minutes. All times are relative to GMT time.

Responses

201

Request created

400

Fail (missing arguments)

post/api/project/{project_id}/data-request/

Request samples

Payload
CURL

application/json

{"search": "string",
"source": "string",
"doCreateSchedule": true,
"scheduleFrequency": 0,
"schedulePeriod": "string",
"scheduleDatetime": "string"
}

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

400

error

post/{apikey}/score.json

Request samples

Payload
CURL

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

400

error

post/{apikey}/bulk-score.json

Request samples

CURL

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": {"text1": 0.923,
"text2": -0.371
}
}

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

400

error

post/{apikey}/topic.json

Request samples

CURL

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": [{"topic": "cake",
"freq": 1,
"score": 0.1136
},
{"topic": "hats",
"freq": 1,
"score": -0.39129
}
]
}

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

400

error

post/{apikey}/chunk.json

Request samples

CURL

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": [{"chunk": "The service was great",
"score": 1
},
{"chunk": "the food was terrible",
"score": -1
}
]
}

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

400

error

get/{apikey}/sentiment-rules.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/sentiment-rules.json

Response samples

application/json

{"rules": [{"rule_id": "f48dd58369252ba986d64a03b93c4609fe10a9e0",
"sentiment": "pos",
"text": "niceeeeee"
},
{"rule_id": "83e254bf0cdc61f56a85b7c5bc00b7af603e706f",
"sentiment": "neg",
"text": "that is so sick"
}
],
"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

400

error

post/{apikey}/sentiment-rules.json

Request samples

CURL

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

delete/{apikey}/sentiment-rules.json

Request samples

CURL

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

post/{apikey}/entities.json

Request samples

CURL

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": [{"classifications": ["Org.pro_basketball_team"
],
"title": "Toronto Raptors",
"positions": [{"end": 51,
"start": 47
}
]
},
{"classifications": ["Org.pro_basketball_team"
],
"title": "Cleveland Cavaliers",
"positions": [{"end": 76,
"start": 72
}
]
},
{"classifications": ["Time.day"
],
"title": "Sunday",
"positions": [{"end": 86,
"start": 80
}
]
},
{"classifications": ["Person.pro_athlete"
],
"title": "Pascal Siakam",
"positions": [{"end": 16,
"start": 10
}
]
},
{"classifications": ["Person.pro_athlete"
],
"title": "Kyle Lowry",
"positions": [{"end": 5,
"start": 0
}
]
}
],
"status": "OK",
"themes": ["sports"
]
}

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

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": [{"chunk": "I loved the rooms",
"score": 0.975,
"sentiment_topic": "rooms",
"sentiment_text": ["loved"
]
}
],
"food": [{"chunk": "but the coffee could have been better",
"score": -0.9575054935196873,
"sentiment_topic": "coffee",
"sentiment_text": ["better"
]
}
],
"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

get/{apikey}/classifications.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/classifications.json

Response samples

application/json

{"Event.activity": [ ],
"Event.airplane_crash": ["politics"
],
"Event.award": [ ],
"Event.coup": ["military",
"politics"
],
"Event.crime": ["law"
],
"Event.financial": ["finance"
],
"Event.genocide": ["military",
"politics"
],
"Event.government_policy": ["politics"
],
"Event.massacre": [ ],
"Event.military_operation": ["military"
],
"Event.social": [ ],
"Event.sport": ["sports"
],
"Event.sports": ["sports"
],
"Event.terrorist_attack": ["military",
"politics"
],
"Event.trade_show": [ ],
"Event.trial": ["law"
],
"Event.war": ["military"
],
"Health.artery": ["health"
],
"Health.bone": ["health"
],
"Health.disease": ["health"
],
"Health.disorder": ["health"
],
"Health.enzyme": ["health",
"science"
],
"Health.muscle": ["health"
],
"Health.organ": ["health"
],
"Health.pharmaceutical": ["health"
],
"Health.surgery": ["health"
],
"Health.symptom": ["health"
],
"Health.vitamin": ["health"
],
"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": ["politics"
],
"Location.highway": [ ],
"Location.lake": [ ],
"Location.language": [ ],
"Location.lighthouse": [ ],
"Location.mountain": [ ],
"Location.mountain_range": [ ],
"Location.museum_or_gallery": ["arts"
],
"Location.neighborhood": [ ],
"Location.ocean": [ ],
"Location.park": [ ],
"Location.power_station": ["energy"
],
"Location.prison": ["law"
],
"Location.public_space": [ ],
"Location.region": [ ],
"Location.religious_site": ["religion"
],
"Location.river": [ ],
"Location.sea": [ ],
"Location.stadium": ["sports"
],
"Location.state_or_province": [ ],
"Location.statue": [ ],
"Location.train_station": ["transportation"
],
"Location.transit_line": ["transportation"
],
"Location.university": ["education"
],
"Location.waterfall": [ ],
"Number.financials": ["finance"
],
"Number.math_constant": ["science"
],
"Org.broadcaster": [ ],
"Org.business": ["business",
"finance"
],
"Org.central_bank": ["finance"
],
"Org.college_sports_team": ["sports"
],
"Org.government_agency": ["politics"
],
"Org.government_committee": ["politics"
],
"Org.government_legislature": ["politics"
],
"Org.hackers": ["technology"
],
"Org.hospital": ["health"
],
"Org.ideology": ["politics"
],
"Org.intelligence_agency": ["military"
],
"Org.junior_hockey_team": ["sports"
],
"Org.militants": ["military",
"politics"
],
"Org.military": ["military"
],
"Org.minor_league_baseball_team": ["sports"
],
"Org.music_group": ["arts"
],
"Org.news_agency": [ ],
"Org.newspaper": [ ],
"Org.nonprofit": [ ],
"Org.online_news": [ ],
"Org.political_party": ["politics"
],
"Org.pro_baseball_team": ["sports"
],
"Org.pro_basketball_team": ["sports"
],
"Org.pro_football_team": ["sports"
],
"Org.pro_hockey_team": ["sports"
],
"Org.pro_rugby_team": ["sports"
],
"Org.pro_soccer_team": ["sports"
],
"Org.radio_station": ["music"
],
"Org.religion": ["religion"
],
"Org.sports_league": ["sports"
],
"Org.stock_exchange": ["finance"
],
"Org.stock_index": ["finance"
],
"Org.transit_authority": [ ],
"Org.transit_system": [ ],
"Person.academic": [ ],
"Person.actor": ["entertainment",
"arts"
],
"Person.artist": ["arts"
],
"Person.author": ["arts"
],
"Person.broadcaster": [ ],
"Person.businessman": ["business"
],
"Person.comedian": ["entertainment"
],
"Person.computer_scientist": ["technology"
],
"Person.criminal": ["law"
],
"Person.director": ["entertainment",
"arts"
],
"Person.economist": ["business"
],
"Person.fictional_character": ["arts"
],
"Person.first_lady": ["politics"
],
"Person.first_nations": [ ],
"Person.government_employee": ["politics"
],
"Person.hacker": ["technology"
],
"Person.head_of_state_title": ["politics",
"business"
],
"Person.journalist": [ ],
"Person.judge": ["law"
],
"Person.lawyer": ["law"
],
"Person.military_personnel": ["military"
],
"Person.military_rank": ["military"
],
"Person.model": [ ],
"Person.music_group": ["arts"
],
"Person.musician": ["arts"
],
"Person.nationality": [ ],
"Person.philanthropist": [ ],
"Person.philosopher": ["arts"
],
"Person.physician": ["health"
],
"Person.playwright": ["arts"
],
"Person.poet": ["arts"
],
"Person.politician": ["politics"
],
"Person.pro_athlete": ["sports"
],
"Person.radio_host": ["entertainment"
],
"Person.relationship": [ ],
"Person.religious_figure": ["religion"
],
"Person.religious_follower": ["religion"
],
"Person.religious_founder": ["religion"
],
"Person.royalty": ["politics"
],
"Person.scientist": ["science"
],
"Person.software_engineer": ["technology"
],
"Person.sports_coach": ["sports"
],
"Person.sports_position": ["sports"
],
"Person.surgeon": ["health"
],
"Person.terrorist": ["military",
"politics"
],
"Person.tv_presenter": [ ],
"Person.us_president": ["politics"
],
"Person.whistleblower": [ ],
"Person.world_leader": ["politics"
],
"Product.airplane": [ ],
"Product.album": ["entertainment",
"arts"
],
"Product.automobile": ["automotive"
],
"Product.beer": ["food"
],
"Product.book": ["arts"
],
"Product.cargo_ship": ["business"
],
"Product.coffee": ["food"
],
"Product.commodity": ["finance"
],
"Product.cryptocurrency": ["technology",
"finance"
],
"Product.currency": ["finance"
],
"Product.digital_media_player": ["technology"
],
"Product.financial": ["finance"
],
"Product.food": ["food"
],
"Product.headphones": ["music"
],
"Product.laundry_detergent": [ ],
"Product.magazine": [ ],
"Product.military_ship": ["military"
],
"Product.mobile_phone": ["technology"
],
"Product.movie": ["entertainment",
"arts"
],
"Product.music_genre": ["arts"
],
"Product.musical_instrument": ["arts"
],
"Product.pipeline_system": ["energy"
],
"Product.podcast": [ ],
"Product.smartphone": ["technology"
],
"Product.soft_drink": ["food"
],
"Product.tablet": ["technology"
],
"Product.tea": ["food"
],
"Product.tv_episode": ["entertainment"
],
"Product.tv_show": ["entertainment"
],
"Product.video_game": ["technology"
],
"Product.video_game_console": ["technology"
],
"Product.weapon": ["military"
],
"Product.wine": ["food"
],
"Science.amphibian": ["science"
],
"Science.bird": ["science"
],
"Science.chemical_compound": ["science"
],
"Science.chemical_element": ["science"
],
"Science.fish": ["science"
],
"Science.galaxy": ["science"
],
"Science.insect": ["science"
],
"Science.mammal": ["science",
"sports"
],
"Science.planet": ["science"
],
"Science.plant": ["science"
],
"Science.reptile": ["science"
],
"Science.star": ["science"
],
"Technology.algorithm": ["technology"
],
"Technology.component": ["technology"
],
"Technology.cpu_architecture": ["technology"
],
"Technology.cpu_extensions": ["technology"
],
"Technology.file_format": ["technology"
],
"Technology.infotainment": ["technology",
"automotive"
],
"Technology.mobile_interface": ["technology"
],
"Technology.network": ["technology"
],
"Technology.operating_system": ["technology"
],
"Technology.programming_language": ["technology"
],
"Technology.social_network": ["technology"
],
"Technology.software": ["technology"
],
"Technology.software_development_process": ["technology"
],
"Technology.software_license": ["technology"
],
"Technology.streaming_service": ["music",
"technology"
],
"Technology.typeface": ["technology"
],
"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

post/{apikey}/similar.json

Request samples

CURL

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

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

get/{apikey}/filter-rules.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/filter-rules.json

Response samples

application/json

{"status": "OK",
"labels": ["rule1",
"rule2",
"rule3"
]
}

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

post/{apikey}/filter-rules.json

Request samples

CURL

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

400

error

delete/{apikey}/filter-rules.json

Request samples

CURL

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

get/{apikey}/clean-html.json

Request samples

CURL

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

400

error

post/{apikey}/clean-html.json

Request samples

CURL

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

post/{apikey}/filter.json

Request samples

CURL

curl -d "text=I love to play hockey" \
https://api.repustate.com/v4/{apikey}/filter.json

Response samples

application/json

{"status": "OK",
"myFilterID": [[1,
10
],
[19,
26
]
]
}

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

post/{apikey}/pos.json

Request samples

CURL

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": [{"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

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

post/{apikey}/detect-language.json

Request samples

CURL

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

get/{apikey}/usage.json

Request samples

CURL

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

get/{apikey}/subaccounts.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/subaccounts.json

Response samples

application/json

{"status": "OK",
"subaccounts": ["account1",
"account2",
"account3"
]
}

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

get/{apikey}/last-updated-rule.json

Request samples

CURL

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

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

400

error

get/{apikey}/search.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/search.json?q=Person.politician.gender:M&index=my-index

Response samples

application/json

{"matches": [{"id": 2,
"title": "my document title",
"text": "my new document with George Bush Sr. as the male politician",
"lang": "en",
"otherid": "my_optional_custom_id",
"entities": {"classifications": ["Person.us_president",
"Person.politician",
"Person.military_personnel",
"Person.businessman",
"Person.government_employee"
],
"title": "George H. W. Bush",
"positions": [{"end": 36,
"start": 21
}
]
}
}
],
"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

put/{apikey}/search.json

Request samples

CURL

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": {"classifications": ["Person.us_president",
"Person.politician",
"Person.military_personnel",
"Person.businessman",
"Person.government_employee"
],
"title": "George H. W. Bush",
"positions": [{"end": 36,
"start": 21
}
]
},
"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

delete/{apikey}/search.json

Request samples

CURL - doc
CURL - index

curl https://api.repustate.com/v4/{apikey}/search.json -X DELETE -G -d "id=21345"

Response samples

application/json

{"status": "OK"
}

Search by semantic similarity

Search the specified Deep Search index for documents that are semantically similar to the document submitted. 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.
text required	string The text document you want to find semantically similar results for.

Responses

200

400

error

get/{apikey}/search-similar.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/search-similar.json?index=my-index&text=I like to eat pizza and pasta

Response samples

application/json

{"matches": [{"id": 2,
"title": "my document title",
"text": "my new document with George Bush Sr. as the male politician",
"lang": "en",
"otherid": "my_optional_custom_id",
"entities": {"classifications": ["Person.us_president",
"Person.politician",
"Person.military_personnel",
"Person.businessman",
"Person.government_employee"
],
"title": "George H. W. Bush",
"positions": [{"end": 36,
"start": 21
}
]
}
}
],
"next": 0,
"prev": 0,
"status": "OK",
"total": 1
}

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

get/{apikey}/search-classifications.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/search-classifications.json

Response samples

application/json

{"status": "OK",
"classifications": ["Location.country",
"Location.citytown",
"Location.continent",
"Location.region",
"Location.tourist_attraction"
]
}

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

get/{apikey}/search-metadata.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/search-metadata.json?classification=Location.country

Response samples

application/json

{"status": "OK",
"metadata": ["Location.country.areaKm",
"Location.country.population",
"Location.country.GDP"
]
}

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

get/{apikey}/custom-entities.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/custom-entities.json

Response samples

application/json

{"entities": ["Custom Entity 1",
"Custom Entity 2"
],
"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

put/{apikey}/custom-entities.json

Request samples

CURL

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

delete/{apikey}/custom-entities.json

Request samples

CURL

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

get/{apikey}/custom-aliases.json

Request samples

CURL

curl https://api.repustate.com/v4/{apikey}/custom-aliases.json?title=My+Custom+Entity&lang=en

Response samples

application/json

{"entities": ["Alias 1",
"Alias 2",
"Alias 3"
],
"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

put/{apikey}/custom-aliases.json

Request samples

CURL

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

delete/{apikey}/custom-aliases.json

Request samples

CURL

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"
}

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>

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.