REST API introduction: version 0.3.1

Introduction

The OpenCorporates REST API is a simple but powerful API for retrieving information from the OpenCorporates database. Many of the pages on OpenCorporates have links to the corresponding data url on the API system, and in fact, some of the pages on OpenCorporates actually make use of the API.

The API does not, for the most part, require authentication. However, to ensure a good service for all users we do restrict the number of API calls that can be made by an individual IP address, and these limits are considerably higher for authenticated users.

Detailed information on the various API requests and responses are in the API Reference section.

Endpoint

The endpoint is api.opencorporates.com. We currently support both http and https, but are likely to move to https only in the near future, so all users are suggested to use the secure endpoint

Best practices

We advise the following best practices for using the OpenCorporates API: * Always use the most up-to-date version, and set the version in your requests (that way if the default version changes your code will still work) * Use the https endpoint - this may become mandatory in the future, and ensures that your API key won't be stolen * Use the #account_status call to keep an eye on your daily/monthly usage to ensure you don't run out of API calls

Example Request/Response

The API by default returns JSON, a lightweight but powerful way of representing data that is natively understood by Javascript (and therefore perfect for widgets, etc), with excellent libraries for all programming languages. It's also fairly easy to understand for humans.

For example the response to https://api.opencorporates.com/companies/nl/17087985 is

{
    "api_version":"0.2",
    "results":
    {
        "company":
        {
            "name":"Bover B.V.",
            "company_number":"17087985",
            "jurisdiction_code":"nl",
            "incorporation_date":null,
            "dissolution_date":null,
            "company_type":"Besloten Vennootschap",
            "registry_url":"https://server.db.kvk.nl/TST-BIN/FU/TSWS001@?BUTT=17087985",
            "branch_status":null,
            "inactive":false,
            "current_status":"Active",
            "created_at":"2011-01-12T21:50:57+00:00",
            "updated_at":"2012-02-02T10:36:46+00:00",
            "retrieved_at":"2011-08-25T14:37:37+01:00",
            "opencorporates_url":"https://opencorporates.com/companies/nl/17087985",
            "previous_names":null,
            "source":
            {
                "publisher":"OpenKVK.nl",
                "url":"https://www.openkvk.nl/17087985",
                "retrieved_at":"2011-08-25T14:37:37+01:00"
            },
            "corporate_groupings":
            [
            ],
            "data":
            {
                "most_recent":
                [
                    {
                        "datum":
                        {
                            "id":2457732,
                            "title":"SEC Edgar entry",
                            "data_type":"OfficialRegisterEntry",
                            "description":"register id: 1434782",
                            "opencorporates_url":"https://opencorporates.com/data/2457732"
                        }
                    },
                    {
                        "datum":
                        {
                            "id":2457731,
                            "title":"Company Address",
                            "data_type":"CompanyAddress",
                            "description":"BOKSHEIDE 20,
                             EERSEL P7 5521 PM",
                            "opencorporates_url":"https://opencorporates.com/data/2457731"
                        }
                    }
                ],
                "total_count":2,
                "url":"https://opencorporates.com/companies/nl/17087985/data"
            },
            "filings":
            [
            ],
            "officers":
            [
            ]
        }
    }
}

JSONP Callbacks

JSONP callbacks are supported on all requests, allowing you to incorporate the data in Ajax requests. Simply add callback=[yourcallbackname] to the request URL, e.g. https://api.opencorporates.com/companies/gb/00102498?callback=foobar

Optional Authentication

Authentication is through a simple API token at present (see API accounts, below), and this should be submitted with each request in the query parameters. This token is available from your account page on OpenCorporates (see below). Please keep your API key safe.

The unauthenticated version of the GET request to get information on BP PLC, for example is:

https://api.opencorporates.com/companies/gb/00102498
The authenticated version is:
https://api.opencorporates.com/companies/gb/00102498?api_token=ab123cd45
where ab123cd45 is the value of your token.

API accounts

No API key is required to use the OpenCorporates API, but having one will considerably increase usage limits (use without a key is primarily to allow web widgets to be built or to try out the API before getting a token).

API accounts are free if you are going to be using the data in an open data project or product, i.e. the product or database in which the data is incorporated is also be released under an open licence (specifically share-alike attribution, with attribution to OpenCorporates as detailed at the OpenCorporates licence page).

We also have paid-for API Accounts, which remove the OpenCorporates share-alike restrictions (on the rights acquired by OpenCorporates in assembling and cleaning up the data, particularly database rights).

To get an API key (or token) simply follow the instructions at our new API Account page.

Stability/Versioning

The OpenCorporates API uses a versioning system. This means that when we introduce changes to the API we can change the version number, so that queries to the previous version will still behave in the same way. If you supply a version number to the API that version will be used, provided it is still supported. If no version number is supplied, the current version will be used. See Versions for details of changes and current version. The v0.1 form of the GET request to get information on BP PLC, for example is: https://api.opencorporates.com/v0.1/companies/gb/00102498 The unversioned form is: https://api.opencorporates.com/companies/gb/00102498

Error/HTTP response codes

  • 200 OK: Success!
  • 304 Not Modified: There was no new data to return.
  • 400 Bad Request: The request was invalid. An accompanying error message will explain why.
  • 401 Unauthorized: Authentication credentials were incorrect.
  • 403 Forbidden: The request is understood, but it has been refused. This is the status code will be returned during rate limiting
  • 404 Not Found: The URI requested is invalid or the resource requested, such as a company, does not exists.
  • 406 Not Acceptable: Returned by the Search API when an invalid format is specified in the request.
  • 500 Internal Server Error: Something is broken. Please contact us if the situation continues and your request is valid
  • 502 Bad Gateway: OpenCorporates is down or being upgraded.
  • 503 Service Unavailable: The OpenCorporates servers are up, but overloaded with requests. This is also the response code returned if a company's details have been temporarily redacted