Google Refine Reconciliation API: version 0.3.1

Introduction

The Google Refine Reconciliation API allows Google Refine users to match company names to legal corporate entities. This is especially useful when you have an exist spreadsheet or dataset featuring lots of companies. Matching (or reconciling) to legal entities allows you to get more information about the companies (for example the registered address or statutory filings), and makes it easier to match with other datasets or exchange with other organisations.

Endpoint

Please note that OpenCorporates' reconciliation endpoint is now https only, and if you have previously used it you will need to update the reconciliation service URLs to be https rather than http (e.g. https://opencorporates.com/reconcile rather than http://opencorporates.com/reconcile)

Setting up Google Refine to match against companies

Start off with following this webcast, which shows you how to install Google Refine and start reconciling companies against the OpenCorporates database. Once you've done that, and understood the basics, you'll want to improve the quality of matching by doing reconciliations restricted to jurisdictions and other attributes. We're planning on doing a screencast on this but this page will give you the information you need to do these. For those familiar with Google Refine, the URL (endpoint) of the OpenCorporates reconciliation service is https://opencorporates.com/reconcile

The scoring system

Google Refine expects the API to return a matching score with each possible result. This is computed by OpenCorporates in the following way: we search all the companies matching the name of the company, doing a certain amount of normalising of the company name, and restricting to jurisdiction if requested. We then compare the possible results against the given term, and calculate the score based on the similarity. We then adjust the score, adjusting it down if the company is inactive, and also if it's a foreign branch of a company. This ensures that home companies, and current companies score more highly.

Restricting to jurisdictions

Many company names are quite common across different locations, and there is the additional problem of foreign branches, which are usually named the same as the home company. To avoid false matches, it's a good idea to limit matches to a given jurisdiction. This is very easy to do with OpenCorporates, as we provide a specific reconciliation URL (or endpoints) for each jurisdiction. This blog post explains it fully, but basically you just add the jurisdiction_code for the jurisdiction to the end of the normal reconciliation URL, e.g. https://opencorporates.com/reconcile/es for Spain, instead of https://opencorporates.com/reconcile

Additional attributes

You can currently submit two additional parameters with each company – the jurisdiction code and a relevant date. The jurisdiction code allows the search to be restricted to a specific jurisdiction which may vary from company to company (e.g. an EU dataset). A submitted date changes the scoring behaviour, meaning that a company will score higher if it was active at that date, and score significantly lower if it didn't yet exist, or was inactive at that date. This is useful if you are matching data from the past, so that you want to match the companies which were relevant to the date of the datapoint.

FAQs

Can I use the Google Refine API without using Google Refine?

Yes. This is what OpenSpending does to match individual transactions to companies. The API is a simple REST api, and is easy to call from within a program

Is the reconciliation data under an open licence?

Yes, it's under the same share-alike attribution Open Database Licence as the rest of OpenCorporates. This means you can reuse the data, even commercially, provided you release the resultant data under the same share-alike attribution licence and, of course, attribute OpenCorporates. That way the open data community benefits from more open data, and OpenCorporates gets due attribution.

My company wants to use this for our proprietary/internal data. Can we get a non-share-alike licence so we don't have to share the results?

Yes. Contact us at sales@opencorporates.com