1. Home
  2. API
  3. Getting Started
  4. Searching for a company

Searching for a company

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/search

The 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' │
└─────────┴────────────────┴────────────────────────────────┴───────────────────┴────────────────────────────────────────────────────┘
Updated on May 19, 2023
Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support