Search API
Perform a free-text search against the text fields indexed in a dataset. Useful when you want to quickly query a dataset but don't know, or need to know its structure.
Table of contents
Endpoint URL
Login to test this query using our experimental API explorer
Authentication
You will need your API key in order to authenticate to this API. You have two options for authentication:
- By URL Parameter -- add a
apikeyparameter to your request URL, with your key as the value - By Request Header -- add a custom HTTP header called
X_KASABI_APIKEYto your HTTP request, with your key as the value
For more information on Kasabi authentication options read the authentication documentation. Your API key will need to be authorized to use this service.
Parameters
Search API requests vary depending on whether the client is performing a keyword search or a facetted search. This functionality is exposed from two sub-paths:
/search- Perform a keyword text search./facet- Perform a facetted search.
While both forms of request accept a standard query parameter, the additional request parameters vary depending on whether a text search or a facetted query is being performed. These are outlined below.
Keyword Search Parameters
The parameters for a keyword search (/search) are as follows:
| Parameter Name | Parameter Value(s) | Required? | Notes |
|---|---|---|---|
| query | Any valid search query. | Yes | Read the search syntax documentation for details. |
| max | Positive integer, up to a maximum of 100 | No | Specify maximum number of results to be returned. The default is 10, and there is a fixed maximum of 100 results for a single page. |
| offset | Positive integer | No | Specify an offset into search results. Use with max to implement paging. |
| sort | Comma-separated list of field names | No | Specifies a sort order for the search. Append :d to a field name to sort in descending order. See documentation on sorting search results. |
output | Short name for desired response format | No | Supports selecting response format using url parameter rather than HTTP Accept header. |
Facet Parameters
The parameters for a keyword search (/facet) are as follows:
| Parameter Name | Parameter Value(s) | Required? | Notes |
|---|---|---|---|
| query | Any valid search query. | Yes | Read the search syntax documentation for details. |
| fields | A comma-separated list of field names to group on. | Yes | Read the Search API documentation for a list of field names. |
| top | Maximum number of facets to return | No | Defaults to 10 |
output | Short name for desired response format | No | Supports selecting response format using url parameter rather than HTTP Accept header. |
HTTP Response Codes
Clients should be prepared to receive any valid HTTP response code. The following table lists the most frequently used codes
| Code | Meaning |
|---|---|
200 OK | Successful Request |
400 Bad Request | Missing or malformed SPARQL query |
401 Not Authorized | API key is not authorized to access the data |
Please also review our additional notes on response codes.
Response Formats
The Search API response formats vary depending on whether a text search or a facetted query is being performed. However both support both XML and JSON
Keyword Search Formats
The response formats for a keyword search (/search) are as follows:
| Response Format | Accept header | output parameter | Notes |
|---|---|---|---|
| application/rss | application/rss | rss (or xml) | Return results as RSS 1.0 |
| application/json | - | json | Return RSS 1.0 results serialized as RDF/JSON |
Facet Formats
The response formats for a facet search (/facet) are as follows:
| Response Format | Accept header | output parameter | Notes |
|---|---|---|---|
| application/xml | application/xml | xml | Return results as XML. Read the Facet documentation for details. |
| application/json | application/json | json | Return results as JSON. Read the Facet documentation for details. |
