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/v3

Rate Limiting

There are no limits to the number of calls you can make per minute/hour/day etc. however all accounts are subject to monthly limits according to the plan you signed up for. In the event that you exceed your monthly quota, you will receive an HTTP 429 response on all subsequent API calls.

Client Libraries

We've got client libraries to help you out. Download a Repustate client to get started.

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.
query required Your properly formatted Deep Search query.
cursor If specified, results will be returned indexed in at the cursor value. Use this to paginate through your search results.
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='v3')
client.search(index="my-index", query="Person.politician.gender:M")
                  
curl https://api.repustate.com/v3/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.
text required The actual document you want to index.
docid If specified, your new document will be assigned this document ID. Otherwise, document IDs are autogenerated by Deep Search.
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. Document IDs can be any string no longer than 40 characters.
{
    "status":"OK",
    "docid":"efda129281fdaecbbb10"
}
require "repustate"

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

client = Client(api_key='YOUR_API_KEY', version='v3')
client.add_document(index="my-index", docid="my-document-id", text="my new document")
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/search.json-d "index=my-index&docid=my-document&text=my new document"
                        

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:"my-document")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v3')
client.delete_document(docid="my-document")
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/search.json -X DELETE -G -d "docid=my-document"
                        

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='v3')
client.delete_index(index="my-index")
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/search.json -X DELETE -G -d "index=my-index"
                        

Similar documents /similar.json
POST

Given a block of text, returns the documents most similar semantically, ranked in order of similarity. At most, 100 documents are returned in a single request.

Name Notes
index required The index you'd like to search against for similar documents.
text required The block of text you'd like to find similar documents for.
cursor If specified, results will be returned indexed in at the cursor value. Use this to paginate through your search results.
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 are most similar to the supplied block of text, from a semantic point of view. Documents are listed in order of similarity.
total The total number of documents that Deep Search considers similar.
next_cursor When more than 100 documents are deemed to be similar, use this value for subsequent requests to fetch the next 100 documents.
{
    "status":"OK",
    "matches":[...],
    "next_cursor":912321321323
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.similar(text:"Find me documents similar to me.", index:"my-index")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v3')
client.similar(text="Find me documents similar to me.", index="my-index")
                  
curl -d "text=Find me documents similar to me.&index=my-index" \
  https://api.repustate.com/v3/YOUR_API_KEY/similar.json

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='v3')
client.search_classifications()
                  
curl https://api.repustate.com/v3/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='v3')
client.metadata("Location.country")
                  
curl https://api.repustate.com/v3/YOUR_API_KEY/search-metadata.json?classification=Location.country