Please note: Deep Search is currently only available to select customers.

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.

Authentication

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

Search /search.json
GET

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.

Name Notes
index required The index you'd like to query.
q required Your properly formatted Deep Search query. The query must conform to the Deep Search Query Language (DSQL) specification.
cursor If specified, results will be returned indexed in at the cursor value. Use this to paginate through your search results.
since Queries will only return documents inserted since a particular time. Format is seconds since epoch.
until Queries will only return documents inserted prior to a particular time. Format is seconds since epoch.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
matches The documents that matched your search query.
total The total number of matching documents.
next_cursor To enable pagination of results, the value of next_cursor can be passed to subsequent requests to get the next page of matching documents.
prev_cursor To enable pagination of results, the value of prev_cursor can be passed to subsequent requests to get the previous page of matching documents.
{
    "status":"OK",
    "matches":[ ... ],
    "next_cursor":2132130912301
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.search(index:"my-index", query:"Person.politician.gender:M")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.search(index="my-index", query="Person.politician.gender:M")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search.json?query=Person.politician.gender:M&index=my-index
                        

Add document /search.json
PUT

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

Name Notes
index required The index to which you'd like to add a new document. Index names can be any string no longer than 40 characters.
title required The title of your document
text required The body of the document you want to index.
lang The language your document is in. If left blank, English (en) is assumed.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
docid The document ID for your newly added document.
{
    "status":"OK",
    "docid":"efda129281fdaecbbb10"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.add_document(index:"my-index", title:"my title", text:"my new document", lang:"en")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.add_document(index="my-index", title="my title", text="my new document", lang="en")
                  
curl -X PUT -d "index=my-index&title=my title&text=my new document&lang=en" \
  https://api.repustate.com/v4/YOUR_API_KEY/search.json

Delete document /search.json
DELETE

Delete a document from your Deep Search Index

Name Notes
docId required The document ID of the document you'd like to delete.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
    "status":"OK"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.delete_document(docId:"23213")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.delete_document(docId="23213")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search.json-X DELETE -G -d "docId=21345"
                        

Delete index /search.json
DELETE

Delete the specified Deep Search Index

Name Notes
index required The index you'd like to delete. This operation cannot be undone.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
    "status":"OK"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.delete_index(index:"my-index")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.delete_index(index="my-index")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search.json -X DELETE -G -d "index=my-index"
                        

List search classifications /search-classifications.json
GET

List all possible classifications that Deep Search can return

This call does not take any arguments.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
classifications The full list of classifications that Deep Search can identify
{
    "status":"OK",
    "classifications":["Location.country", "Location.citytown", "Location.continent", "Location.region", "Location.tourist_attraction" ...] 
}
require "repustate"

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

client = Client(api_key='YOUR_API_KEY', version='v4')
client.search_classifications()
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search-classifications.json
                        

List search metadata /search-metadata.json
GET

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

Name Notes
classification required The classification you want to list metadata for.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
metadata A listing of all metadata for the given entities.
{
    "status":"OK",
    "metadata":["Location.country.areaKm","Location.country.population", "Location.country.GDP"]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.metadata("Location.country")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.metadata("Location.country")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search-metadata.json?classification=Location.country
                        

Add custom entity /custom-entities.json
PUT

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.

Name Notes
title required The name of your entity. This will be the value returned as the "full_title" attribute in any call to entities.json
body required This text describes your entity. The more relevant and longer the text, the better, as this helps Deep Search disambiguate your entity in the event that it identifies two or more similarly named entities. Keywords that accurately describe your entity should be included as part of the description.
classifications required 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.
lang The language model this entity should be added to. Default value is English (en)
aliases A comma separated list of alternate names or spellings that this entity should go by. For example, if the entity was Frank Sinatra, an alias would be "Old Blue Eyes". Other common uses are alternate spellings, and Twitter usernames.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
  "status":"OK"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.add_entity(title:"My Custom Entity", body:"This is my custom entity", classifications:["Person.politician"])
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.add_entity(title="My Custom Entity", body="This is my custom entity", classifications=["Person.politician"])
                  
curl -d "title=My Custom Entity&body=This is my custom entity&classifications[]=Person.politician" \
  https://api.repustate.com/v4/YOUR_API_KEY/custom-entities.json

List custom entities /custom-entities.json
GET

List all of the custom entities you have defined.

Name Notes
lang The language model for which you'd like to list the custom entities you've added. Default value is English (en)
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
entities A list of the entities you've created
{
"entities":["Custom Entity 1", "Custom Entity 2"]
}
require "repustate"

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

client = Client(api_key='YOUR_API_KEY', version='v4')
client.list_custom_entities()
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/custom-entities.json
                        

Delete custom entity /custom-entities.json
DELETE

Deletes a custom entity you previously added.

Name Notes
title required The title of the entity you previously added and now wish to delete
lang The language model this entity should be removed from. Default value is English (en)
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{"status":"OK"}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.delete_custom_entity(title="My Custom Entity")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.delete_custom_entity(title="My Custom Entity")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/custom-entities.json-X DELETE -d "title=My Custom Entity"
                        

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.