Description
The OpenCorporates company search endpoint (GET companies/search) allows for the searching of our data set. Returning a list of possible matches for the search criteria presented.
GET companies/searchThe following examples demonstrate how to call an authenticated company search method using the basic query parameters.
Further API documentation can be found here.
Examples
These examples call the companies/search endpoint providing a basic search query using the q parameter to target the search, whilst also supplying the api_token via a URL parameter. The cURL example returns verbose JSON direct from the API response to the command line, whereas the NodeJS example uses a built-int console.table function to display the results.
curl "https://api.opencorporates.com/v0.4/companies/search?q=OpenCorporates&api_token=xxxxxxxxxx"
// Requires
const OCUtils = require('./ocutil.js'); // OC Utilities
const jp = require('jsonpath'); // JSONPath
const { exit } = require('process');
// Set http request options
const options = {
hostname: 'api.opencorporates.com',
port: 443,
path: '/v0.4/companies/search',
method: 'GET',
headers : {'Content-Type' : 'application/json'}
};
// Check our command line has enough information to continue
var requiredCommandLineArguments = ["q", "api_token" ];
//If not, explain what is needed on the command line
if(!OCUtils.isCommandLineComplete(requiredCommandLineArguments)){
console.log("Required Arguments:")
console.log("--api_token your API Token")
console.log("--q the company to query e.g. 'OpenCorporates'")
console.log("");
console.log("Example: node search.js --api_token xxxxxxxxxxxxx --q \"OpenCorporates\"");
console.log("")
process.exit(1);
}else{
// Fetch the command line arguments
var commandLineArguments = OCUtils.getCommandLineArguments(requiredCommandLineArguments);
// Append command line arguments as URL parameters onto the request URL
options.path = OCUtils.addURLParameter(options.path, "q", commandLineArguments.get("q"), true);
options.path = OCUtils.addURLParameter(options.path, "api_token", commandLineArguments.get("api_token"), false);
// Little bit of debug to explain what we have called.
console.log("Searching for: '%s'", commandLineArguments.get("q"));
console.log("Using API Key: %s", commandLineArguments.get("api_token"));
console.log("Request URL: %s%s%s", (options["port"] == 443 ? "https://":"http://"), options["hostname"], options["path"], );
// Make the request to the OC endpoint to search companies
OCUtils.makeOCRequest(options, function(statusCode, payload){
//Use JSONPath to pull each of the companies.
var companies = jp.query(payload, "$.results.companies..company");
console.log("");
// Print (as a table) the companies array from the response
console.table(companies, ["company_number", "name", "jurisdiction_code", "opencorporates_url"]);
console.log("");
});
}
Results
Note some results have been removed from the response to (hopefully) make them clearer.
The cURL response has had items removed to make the response easier to understand, the structure of the response follows the same pattern however. The NodeJS example uses console.table to display the companies list and extract illustrative fields. Both are powered using the same response from the API.
{
"api_version": "0.4",
"results": {
"companies": [
{ "... omitted for brevity ..."},
{ "... omitted for brevity ..."},
{ "... omitted for brevity ..."},
{
"company": {
"name": "OPENCORPORATES LTD",
"company_number": "07444723",
"jurisdiction_code": "gb",
"incorporation_date": "2010-11-18",
"dissolution_date": null,
"company_type": "Private Limited Company",
"registry_url": "https://beta.companieshouse.gov.uk/company/07444723",
"branch": null,
"branch_status": null,
"inactive": false,
"current_status": "Active",
"created_at": "2010-12-18T01:35:14+00:00",
"updated_at": "2023-03-18T10:58:57+00:00",
"retrieved_at": "2023-03-18T10:58:55+00:00",
"opencorporates_url": "https://opencorporates.com/companies/gb/07444723",
"previous_names": [
{
"company_name": "CHRINON LTD",
"start_date": "2010-11-18",
"end_date": "2018-05-21"
}
],
"source": {
"publisher": "UK Companies House",
"url": "http://xmlgw.companieshouse.gov.uk/",
"terms": "UK Crown Copyright",
"retrieved_at": "2023-03-18T10:58:55+00:00"
},
"registered_address": {
"street_address": "Aston House\nCornwall Avenue",
"locality": "London",
"region": null,
"postal_code": "N3 1LF",
"country": "United Kingdom"
},
"registered_address_in_full": "Aston House\nCornwall Avenue, London, N3 1LF",
"industry_codes": [
],
"restricted_for_marketing": null,
"native_company_number": null
}
},
{ "... omitted for brevity ..."},
],
"page": 1,
"per_page": 30,
"total_pages": 1,
"total_count": 5
}
}
demo@oc % node company_search.js --api_token xxxxxxxxxxx --q "OpenCorporates" Searching for: 'OpenCorporates' Using API Key: xxxxxxxxxxx Request URL: https://api.opencorporates.com/v0.4/companies/search?q=OpenCorporates&api_token= xxxxxxxxxxx ┌─────────┬────────────────┬────────────────────────────────┬───────────────────┬────────────────────────────────────────────────────┐ │ (index) │ company_number │ name │ jurisdiction_code │ opencorporates_url │ ├─────────┼────────────────┼────────────────────────────────┼───────────────────┼────────────────────────────────────────────────────┤ │ 0 │ '11220640' │ 'CHRINON NEWCO 1 LTD' │ 'gb' │ 'https://opencorporates.com/companies/gb/11220640' │ │ 1 │ '11268479' │ 'OPENCORPORATES HOLDING LTD' │ 'gb' │ 'https://opencorporates.com/companies/gb/11268479' │ │ 2 │ '11220648' │ 'OPENCORPORATES IP LTD' │ 'gb' │ 'https://opencorporates.com/companies/gb/11220648' │ │ 3 │ '07444723' │ 'OPENCORPORATES LTD' │ 'gb' │ 'https://opencorporates.com/companies/gb/07444723' │ │ 4 │ '11329152' │ 'OPENCORPORATES TRUST LIMITED' │ 'gb' │ 'https://opencorporates.com/companies/gb/11329152' │ └─────────┴────────────────┴────────────────────────────────┴───────────────────┴────────────────────────────────────────────────────┘