API Reference: version 0.2

Note this should be read in conjunction with the introduction to the OpenCorporates REST API, which covers optional authentication and versioning. The example urls given here will omit the versioning for simplicity (and will therefore always use the current API version).

Universal attributes/objects

Response

As of version 0.2 there are two parts to the response: the data that comprises the results, and this is wrapped inside a results object/tag; and meta data, including the api version that was used (useful if none was explicitly requested). XML responses are wrapped in a 'Response' root object.

Response format

All objects are returned as JSON (or JSONP if a callback is requested) by default. We also (as of version 0.2) can return XML if preferred. Simply add format=xml as a query parameter, e.g.

http://api.opencorporates.com/v0.2/companies/gb/00102498?format=xml
or
http://api.opencorporates.com/v0.2/companies/search?q=barclays+bank&format=xml>

The OpenCorporates source object

At OpenCorporates we're obsessive about provenance of data, and so we always make it clear when information came from (and when it was retrieved). So the detailed responses all include the provenance of the data as a source object, consisting of the following:

retrieved_ata timestamp of when the information was retrieved from the source, or the data was created.
source_typethis is either 'user' if the information was contributed by a user, or 'external' if the information was obtained from an external source.
urlwhere the information was retrieved from. This may be the URL of a specific datum, or the download URL of a data_dump, or if this is not available the URL of the publisher. If the information was user-contributed it will be the OpenCorporates url of the user.
publisherIf the information came from an external source, this is the original publisher of the information; if the information was user-contributed, this will be the user's name.
termsif we are aware that the external publisher of the data has applied an explicit licence to the data (e.g. in the UK it is often Crown Copyright, or sometimes the Open Government Licence). A Null value for this does *not* imply there is no underlying licence.

OpenCorporates URL

All objects are returned with their OpenCorporates URL. This has two benefits: it makes it easy to get the api URL for the given object, by just prefixing the url with 'api.' (e.g. from

https://opencorporates.com/companies/gb/00102498
to
http://api.opencorporates.com/companies/gb/00102498
, and it allows the OpenCorporates URL for the object to be linked to, as attribution (remember, OpenCorporates' rights to the data are under the share-alike attribution Open Database Licence).

Method calls

GET versions

Description: This returns the current version of the API and supported versions. If a specific version has been requested it also returns the requested version.

Example:

http://api.opencorporates.com/v0.2/versions

GET companies/:jurisdiction_code/:company_number

Description: This returns the core data for the given company. The jurisdiction code is the code for the jurisdiction which registered the company. If this is a country it is simply the two-letter ISO code for that country, e.g. Spain = es, United Kingdom = gb. If this is a state or province it is an underscore version of the ISO 3166-2 code for the jurisdiction, eg. Michigan in the US is us_mi.

Included in the response will be the core data on the company (incorporation date, company type, registered address, etc), a summary of other data held on the company (e.g. trademarks, payments from government, other addresses), including the most recently added data, and the most recent statutory filings. If you don't need the filings and the other data, or believe there are not likely to be such results, you can pass sparse=true as a query parameter, and this will be both quicker, and potentially a considerably smaller response.

Note: We very very occasionally temporarily redact information on a company to allow the official record to be changed (see OpenCorporates Temporary Redaction for details). In this case, an error message with a 503 HTTP response code will be returned.

Example:

http://api.opencorporates.com/v0.2/companies/gb/00102498
http://api.opencorporates.com/v0.2/companies/gb/00102498?sparse=true

GET companies/search

Description: This returns a collection of companies whose name matches the given search term (submitted as :q in the query parameters). It's important to note that the search is deliberately quite loose, requiring the returned companies to have all the searched-for words (in any order), but allowing other words to be present too (so 'Bank Barclays' is the same as 'Barclays Bank').

The search is case-insensitive and returns companies with previous names matching the term as well as current name, and some normalisation of the company names is done, removing non-text characters (e.g. dashes, parentheses, commas), common 'stop words' (e.g. 'the', 'of'), and normalising common company types (e.g. Corp, Inc, Ltd, PLC) so that both the short and long versions can be used.

The companies can be restricted to a given jurisdiction by passing the :jurisdiction_code query parameter, and other filters are also allowed (such as restricting to company type). The best way to understand these is to experiment with the main OpenCorporates web site and use the filters on the right-hand-side of the search results page.

The companies are returned in alphabetic order by default but you can return ordered by score (as ranked by our Solr search index) by passing the order=score query parameter. The response is paginated, and by default 30 filings are returned, together with the current page number, and total number of pages. This can be increased (to up to 100) by supplying a :per_page query parameter, and the page number is specified with the :page query parameter.

Example:

http://api.opencorporates.com/v0.2/companies/search?q=barclays+bank
http://api.opencorporates.com/v0.2/companies/search?q=barclays&per_page=50&page=2
http://api.opencorporates.com/v0.2/companies/search?q=barclays+bank&jurisdiction_code=gb
http://api.opencorporates.com/v0.2/companies/search?q=barclays+bank&jurisdiction_code=gb&current_status=Active
http://api.opencorporates.com/v0.2/companies/search?q=bank+of+scotland
http://api.opencorporates.com/v0.2/companies/search?q=bank+of+scotland&order=score

GET companies/:jurisdiction_code/:company_number/filings

Description: This returns the statutory filings for the given company. Each filing will be returned with the date of filing, the OpenCorporates id and url for the filing, and one or many of the following

:uidthe id given to the filing by the company registry
:titlethis is either the given title of the filing, or the filing_type, or a generic field containing a human-friendly version of the date. This means that every filing can be relied upon to have a filing_title
:descriptionthe given description of the filing
:urlthe url of the filing. This may be a url of an HTML page, or of the document itself, for those more enlightened jurisdictions which make this available without charge
:filing_type_namea human-readable name of the type of filing. This might have been computed from the filing_code
:filing_codethe code given by the company registry to this type of filing

The response is paginated, and by default 30 filings are returned, together with the current page number, and total number of pages. This can be increased (to up to 100) by supplying a :per_page query parameter, and the page number is specified with the :page query parameter.

Example:

http://api.opencorporates.com/v0.2/companies/gb/00102498/filings
http://api.opencorporates.com/v0.2/companies/gb/00102498/filings?page=2

GET officers/search

Description: This returns a collection of officers whose name matches the given search term (submitted as :q in the query parameters). It's important to note that the search is deliberately quite loose, requiring the returned officers to have all the searched-for words (in any order), but allowing other words to be present too (so 'John Smith' is the same as 'Smith John').

The search is case-insensitive.

The officers can be restricted to a given jurisdiction by passing the :jurisdiction_code query parameter.

The officers are returned in alphabetic order by default but you can return ordered by score (as ranked by our Solr search index) by passing the order=score query parameter. The response is paginated, and by default 30 officers are returned, together with the current page number, and total number of pages. This can be increased (to up to 100) by supplying a :per_page query parameter, and the page number is specified with the :page query parameter.

Example:

http://api.opencorporates.com/v0.2/officers/search?q=john+smith
http://api.opencorporates.com/v0.2/officers/search?q=john+smiths&perpage=50&page=2
http://api.opencorporates.com/v0.2/officers/search?q=john+smith&jurisdictioncode=gb
http://api.opencorporates.com/v0.2/officers/search?q=john+smith&order=score

GET officers/:id

Description: This returns information on a particular officer (a director or an agent for a company). Each officer will be returned with the name of the officer, the OpenCorporates id and url for the officer, the company it relates to, and one or more of the following:

:positionthe position held (e.g. director, secretary, CEO)
:uidthe id given to the officer by the company registry
:startdatethis is date on which the officership started
:enddatethis is date on which the officership ended

GET companies/:jurisdiction_code/:company_number/data

Description: This returns the data held for the given company. In OpenCorporates a datum is a piece of information derived from a public record, or contributed by a user. Examples are a website, sales tax number, address, or entry in an official register (e.g. the UK Charity Register or US SEC register). Each datum will be returned with the OpenCorporates id, the OpenCorporates URL for the datum, timestamps indicating when they were created/updated and the following:

:idthe id given to the filing by the company registry
:titlethis is the title of the datum as displayed on OpenCorporates. It is computed internally depending on the data_type
:descriptionthe given description of the datum as displayed on OpenCorporates. It is computed internally depending on the data_type. Together with the title this makes it easy to display a useful summary of the datum
:data_typethis is a string value denoting the type of data, e.g. 'CompanyAddress', 'OfficialRegisterEntry'

The response is paginated, and by default 30 companies are returned, together with the current page number, and total number of pages. This can be increased (to up to 100) by supplying a :per_page query parameter, and the page number is specified with the :page query parameter.

Example:

http://api.opencorporates.com/v0.2/companies/gb/00102498/data

GET corporate_groupings/:name

Description: This returns information on a given CorporateGrouping. A CorporateGrouping is a user-curated collection of companies that belong to some human-understand concept of a corporation (which maps to the Wikipedia article about that corporation). See (http://blog.opencorporates.com/2011/06/01/introducing-corporategroupings-where-fuzzy-concepts-meet-legal-entities/). The name of the CorporateGrouping is case-insensitive Included in the response will be core information for the CorporateGrouping (:name, :wikipedia_url, :companies_count), together an array of membership of the CorporateGrouping (each membership will contain a company and an OpenCorporates Source Object), and an array of the users that are curating this CorporateGrouping

Example:

http://api.opencorporates.com/v0.2/corporate_groupings/capita

GET corporate_groupings/search

Description: This returns a collection of corporate_groupings whose name matches the given search term (submitted as :q in the query parameters). The search is case-insensitive, and is a stem-search, that is it searches for corporate_groupings whose name begins with the given characters.

The response is paginated, and by default 30 companies are returned, together with the current page number, and total number of pages. This can be increased (to up to 100) by supplying a :per_page query parameter, and the page number is specified with the :page query parameter.

Example:

http://api.opencorporates.com/v0.2/corporategroupings/search?q=bar
http://api.opencorporates.com/v0.2/corporategroupings/search?q=ba&per_page=50&page=2

GET filings/:id

Description: This returns information on a statutory filing for the a company. Each filing will be returned with the date of filing, the OpenCorporates id and url for the filing, the company it relates to, and one or many of the following

:uidthe id given to the filing by the company registry
:titlethis is either the given title of the filing, or the filing_type, or a generic field containing a human-friendly version of the date. This means that every filing can be relied upon to have a filing_title
:descriptionthe given description of the filing
:urlthe url of the filing. This may be a url of an HTML page, or of the document itself, for those more enlightened jurisdictions which make this available without charge
:filing_type_namea human-readable name of the type of filing. This might have been computed from the filing_code
:filing_codethe code given by the company registry to this type of filing

GET data/:id

Description: This returns information on a given datum. In OpenCorporates a datum is a piece of information derived from a public record, or contributed by a user. Examples are a website, sales tax number, address, or entry in an official register (e.g. the UK Charity Register or US SEC register). Note that a datum can relate to more than one company (e.g. an official notice of a merger between two companies), and so an array of companies is returned, each including the company name, jurisdiction_code, company_number and OpenCorporates url.

The datum will also return the data_type, title, and description, as described in GET companies/:jurisdiction_code/:company_number/data above. In addition the detailed attributes of the datum are returned as 'attributes' – these vary depending on the data_type.

Finally the source of the data will be returned as an OpenCorporates source object

Example:

http://api.opencorporates.com/v0.2/data/2601371