Reconciliation API

Every dataset in Kasabi supports a common Reconciliation API. This is a simple JSON API used to match simple textual labels or identifiers against a dataset in order to find matching URIs. E.g. resolving the phrase "Apollo 11" to the identifier for a spacecraft in the NASA dataset.

The Reconciliation API conforms to the open protocol defined for the Google Refine data wrangling tool. This means that any of the datasets in Kasabi can be used as a reconciliation target withing Google Refine. This combines the power of the Google Refine tool with the power of Kasabi as a data hosting and manipulation platform.

The Reconciliation API implements the complete Reconciliation API, apart from a few limitations noted below. This means that the API is suitable for use not just within Google Refine but also as a general purpose data linking tool.

For a more detailed description of the API, consult the Reconciliation API documentation

Current Limitations

The Kasabi implementation of the Reconciliation API is currently limited in the following ways:

• The Reconciliation API allows identifiers for items, types and properties to be arbitrary strings. However in Kasabi these must all be URIs, such that the API can be mapped to the RDF model.
• The Reconciliation API allows matching based on either the name or the identifier for a property. However only property identifiers (URIs) are supported.

Using a Reconciliation API within Google Refine

Assuming you have followed the Getting Started guide for Google Refine, you can use a Kasabi Reconciliation API within the tool as follows:

1. Choose the Column containing values to be reconciled. From the drop down menu next to the column name, choose "Reconcile -> Start Reconciling..."
2. The Google Refine reconciliation dialog will open.
3. From within the dialog choose click the "Add Standard Service" button and enter the URL of the Reconciliation Service along with your API key (see below) into the dialog
4. Select the service from the left hand menu. And wait as Google Refines samples the Kasabi dataset for relevant types
5. Optionally select a type to limit the Reconciliation requests and click the "Start Reconciling" button.

This process is the standard way to add a Reconciliation Service within Google Refine. The only Kasabi specific feature is the use of an API key with the Reconciliation API.

If you are using, e.g. a Reconciliation API with a base URI of http://api.kasabi.com/dataset/nasa/apis/reconciliation then enter the following as the URL of the API in Google Refine:

http://api.kasabi.com/dataset/nasa/apis/reconciliation?apikey=...

Basic API Reference

Endpoint URL

The base URI of a Reconcilation API will be displayed on the homepage for the API itself.

Authentication

To access the API will require use of your API key. For more information on Kasabi authentication options read the authentication documentation.

Request Methods

Both GET and POST requests are supported.

Parameters

The API accepts either a query parameter for performing single reconciliation query or a queries parameter for performing several reconciliations in a single request.

As noted in the Reconciliation API documentation the query parameter can either be a simple query term to reconcile or a URL encoded JSON object. The JSON object form allows more specification of how the reconcilation should be carried out.

An example of a JSON query object:

{
    "query" : "Apollo 11",
    "limit" : 3,
    "type" : "http://purl.org/net/schemas/space/Mission",
    "type_strict" : "any",
}

The queries parameter must always be a URL encoded JSON object.

HTTP Response Codes

Clients should be prepared to receive any valid HTTP response code. The following table lists the most frequently used codes

Please also review our additional notes on response codes and error reporting.

Response Formats

The reconcilation API only supports JSON output. The returned JSON structures conforms to that required by Google Refine:

{
  "result": [ 
   {
      "id": "http:\/\/data.kasabi.com\/dataset\/nasa\/mission\/apollo-11",
      "name": "Apollo 11",
      "type": ["http:\/\/purl.org\/net\/schemas\/space\/Mission"],
      "score": "1.0",
      "match": true
   }
  ]
}

The result array contains the results of the reconcilation request. The URI (id), name (name) and RDF type (type) of each entity is returned, along with a confidence score for the match.

View the results of attempting to reconcile the text "Apollo 11" as against the Missions resources in the NASA dataset: Results.