reconciliation

A REST API to handle the reconciliation problem, summed up as "Tell me which freebase topic, if any, some data corresponds to."

The reconciliation service exists to help with the importing and interfacing of larger data sources with Freebase.  The first step in any such process is to figure out how entities in your data match up with the topics in Freebase. Given a name and a freebase type, the service searches and compares these inputs against topics in Freebase, and then provides a list of results and a recommendation for what to do with your entity: automerge, autocreate, or suggest.

When the automerge recommendation is returned, your software can automatically treat the first result returned as though it were the topic you're searching for, loading any data you have on the topic and adding a pointer to it into your data to remember the connection.

The autocreate recommendation indicates that you have an object that isn't in Freebase.  In this case you can automatically create a new Freebase topic and populate it with your data.  

The suggest recommendation indicates that there wasn't a clear match with an existing topic.  In many cases there are a number of reasonably close matches to choose from, and human insight is needed to pick the correct one.

Since the Reconciliation Service places a lot of weight on similarity of names (and aliases), it works best on objects with varied and distinctive names.  It has been tested with names of people, companies, universities, and movies.

API Parameters

Input

To make a reconciliation query, perform a GET request with these parameters:

• name – the name to be searched for
• types – a comma-separated list of expected types
• responseType – optional. If included it must be either 'json' or 'html'.  By default, json results are returned.  The html result will be displayed in the browser, and also provide a minimal user interface to perform additional queries.  Since the main purpose of this service is to provide machine-readable results, the html result option is provided only for convenience while undertaking development and exploration.

Output

The reconciliation service returns a list of results and the suggested next action.  

The list of results consists of an ID that uniquely identifies the topic in Freebase, the name of the topic, and a dictionary of scores.  The results are sorted by their aggregate score, which is made up of a name score and a type score. Though frequently only the first five to ten results are very close to the search, a large list of results is returned to facilitate additional analysis of the results.

The recommendation, as described above, recommends the next action for your software to take:  automatically use the first result, automatically create a new topic, or yield the decision to a human.

Examples

Some examples of the Reconciliation Service can be found under the Weblinks for this topic.

These examples link to the html interface for clarity.  To view the json, omit the responseType parameter.