The Search API provides support for running full-text queries over a dataset. The API supports a flexible search syntax, relevance ranking of results, facetting over search fields, and basic features such as sorting and paging.
Using simple keyword searches, users can perform queries against datasets without having to know the details of their internal structure. Search results can be delivered in a range of formats including simple XML and JSON, as well as RSS 1.0 feeds that contain a rich, structured description of each entity.
Facetting allows the creation of facetted search/browse interfaces that group the results of keyword searches by specific fields.
Overview
Each instance of the Search API supports two types of request. These are performed by addressing specific paths:
/search- a conventional keyword-search based interface for performing queries against text fields in a dataset./facet- a facetted search interface
The parameters and result formats for these sub-endpoints are slightly different. More information on the Facet Search API is provided on a separate page. The remainder of this page discusses use of the search facility specifically.
Quick example
Basic API Reference
Endpoint URL
The base URI of a Reconcilation API will be displayed on the homepage for the API itself. To perform a keyword search using the API, queries should be addressed to the /search sub-path with additional parameters specifying the search terms.
http://api.kasabi.com/dataset/nasa/apis/search/search?apikey=...&query=apolloAuthentication
To access the API will require use of your API key. For more information on Kasabi authentication options read the authentication documentation.
Parameters
The search API requires a query parameter which is used to pass in the search expression, e.g:
http://api.kasabi.com/api/nasa-search/search?apikey=...&query=apolloRead the search syntax guide for a full reference on how to construct valid search expressions.
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 |
|---|---|
| 202 Accepted | Request to update data has been accepted |
| 400 Bad Request | Invalid data, missing or invalid parameters |
| 401 Not Authorized | API key is not authorized to access the data |
Please also review our additional notes on response codes and error reporting.
Response Formats
The results can be returned in a number of different formats including simple XML and JSON formats, as well as richer RSS 1.0 feeds. These can be requested using the usual content negotiation options.
JSON Search Results
An example of the JSON output from the search results is shown below:
{
"head": {
"query":"apollo",
"startIndex":"0",
"totalResults":"10",
"pageSize":"10"
},
"results": [
{
"uri": "http://data.kasabi.com/dataset/nasa/spacecraft/1968-025A",
"title": "Apollo 11",
"score": "1.0"
}
...additional results...
]
}
The JSON object has a head that describes the search itself, i.e. the search term, page size, and overall number of results. The results array returns the URI, relevance score and title for each of the results.
Additional metadata about each resource can be found either by de-referencing the URI directly or, more reliably, by using the Lookup API associated with the dataset being searched.
XML Search Results
An example of the XML output from the search results is shown below:
<?xml version="1.0"?>
<search-results>
<head>
<query>apollo</query>
<startIndex>0</startIndex>
<totalResults>10</totalResults>
<pageSize>10</pageSize>
</head>
<results>
<result>
<uri>http://data.kasabi.com/dataset/nasa/spacecraft/1968-025A</uri>
<title>Apollo 11</title>
<score>1.0</score>
</result>
</results>
</search-results>
The XML format is similar to the JSON output, consisting of a head element that contains metadata about the search itself and result elements that provide basic information about each result.
Additional metadata about each resource can be found either by de-referencing the URI directly or, more reliably, by using the Lookup API associated with the dataset being searched.
RSS 1.0 Search Results
Requesting results as either RDF (application/rdf+xml) or RSS (application/rss+xml) will return an RSS 1.0 feed. The feed includes Open Search extensions for capturing the number of resources and relevance score of the result.
The RSS items in the feed are constructed similarly to the XML and JSON formats, i.e. the identifier for the RSS item is the URI of the resource, and each item will have a suitable title field.
In addition to returning just a ranked list of results, the RDF/RSS output includes a full Concise Bounded Description of each resource. In effect it is the equivalent of fetching the description of each results via the Lookup API. This makes the RSS feed useful in scenarios when a client wants to fetch more data in a single request.
Sorting
By default search results are ordered based on the relevance score for the individual search results. However the ordering of results can be altered using the sort parameter.
The sort parameter accepts a comma-separated list of field names that specify an overall sort order for the results. This allows results to be sorted by a single field, or multiple fields. E.g
http://api.kasabi.com/api/nasa-search/search?apikey=...&query=apollo&sort=nameStandard Search Fields
The following search fields are available as standard across all Search APIs in Kasabi. To perform a fielded search, simply prefix the search term with the name of the field, E.g to search across just the name field (i.e. the FOAF name properties in the dataset, you can issue a request as follows:
http://api.kasabi.com/api/nasa-search/search?apikey=...&query=name:apollo| Field Name | Description | URI | Weight |
|---|---|---|---|
abstract |
Abstract from a wikipedia page | http://dbpedia.org/ontology/abstract |
0.6 |
accountName |
Name of an account, e.g. a twitter handle | http://xmlns.com/foaf/0.1/accountName |
0.9 |
adr |
Address label from a vcard | http://www.w3.org/2006/vcard/ns#adr |
0.5 |
altLabel |
An alternate label for a resource | http://www.w3.org/2004/02/skos/core#altLabel |
0.9 |
changeNote |
Notes describing change(s) to a resource | http://www.w3.org/2004/02/skos/core#changeNote |
0.5 |
comment |
A comment about a resource | http://www.w3.org/2000/01/rdf-schema#comment |
0.6 |
content |
Content of a blog post or tweet | http://rdfs.org/sioc/ns#content |
0.6 |
dcDescription |
Description of a resource | http://purl.org/dc/elements/1.1/description |
0.6 |
dcIdentifier |
Identifier for a resource | http://purl.org/dc/elements/1.1/identifier |
1 |
dcTitle |
Title of the resource. E.g. a book or article | http://purl.org/dc/elements/1.1/title |
1 |
definition |
Description of how a resource is defined | http://www.w3.org/2004/02/skos/core#definition |
0.7 |
description |
Description of a resource using older Dublin Core vocabulary | http://purl.org/dc/terms/description |
0.6 |
editorialNote |
An editorial note | http://www.w3.org/2004/02/skos/core#editorialNote |
0.5 |
example |
Example of using a resource | http://www.w3.org/2004/02/skos/core#example |
0.5 |
familyName |
Family/surname | http://xmlns.com/foaf/0.1/familyName |
1 |
firstName |
First name | http://xmlns.com/foaf/0.1/firstName |
1 |
fn |
Formal name, from a vcard | http://www.w3.org/2006/vcard/ns#fn |
0.9 |
givenName |
Given name | http://xmlns.com/foaf/0.1/givenName |
1 |
hiddenLabel |
A hidden, i.e. indexed but not displayed, label for a resource | http://www.w3.org/2004/02/skos/core#hiddenLabel |
0.8 |
historyNote |
Historical notes about a resource | http://www.w3.org/2004/02/skos/core#historyNote |
0.5 |
identifier |
Identifier for a resource using older Dublin Core vocabulary | http://purl.org/dc/terms/identifier |
1 |
label |
A label for a resource | http://www.w3.org/2000/01/rdf-schema#label |
0.9 |
lastName |
Last name/surname | http://xmlns.com/foaf/0.1/lastName |
1 |
mediumSynopsis |
Medium synopsis of a programme | http://purl.org/ontology/po/medium_synopsis |
0.6 |
name |
Name of a resource, typically a person or organization | http://xmlns.com/foaf/0.1/name |
1 |
nick |
Nick name | http://xmlns.com/foaf/0.1/nick |
0.9 |
notation |
Typically an identifier or other identifying code for the resource | http://www.w3.org/2004/02/skos/core#notation |
1 |
note |
A short note describing a resource | http://www.w3.org/2004/02/skos/core#note |
0.6 |
postCode |
Post code, using Ordnance Survey ontology | http://data.ordnancesurvey.co.uk/ontology/postcode/postcode |
1 |
prefLabel |
Preferred label for a resource | http://www.w3.org/2004/02/skos/core#prefLabel |
1 |
revRating |
Review rating | http://purl.org/stuff/rev#rating |
0.4 |
revText |
Review text | http://purl.org/stuff/rev#text |
0.6 |
revTitle |
Review title | http://purl.org/stuff/rev#title |
1 |
scopeNote |
Describes scope in which the resource, typically a subject category, should be used | http://www.w3.org/2004/02/skos/core#scopeNote |
0.5 |
shortSynopsis |
Short synopsis of a programme | http://purl.org/ontology/po/short_synopsis |
0.8 |
subject |
Subject label for a resource | http://purl.org/dc/elements/1.1/subject |
0.4 |
synopsis |
Synopsis of a programme | http://purl.org/ontology/po/long_synopsis |
0.6 |
title |
Title of the resource using older Dublin Core vocabulary | http://purl.org/dc/terms/title |
1 |
type |
Type of the resource | http://www.w3.org/1999/02/22-rdf-syntax-ns#type |
|
vPostalCode |
Post code from a vcard | http://www.w3.org/2006/vcard/ns#postal-code |
0.5 |
Standard Search Field Weighting
Each of the standard search fields has a weighting applied to them when generating relevance scores for searching. The following table lists the fields in order of their weighting.
