1. Home
  2. Searching for an officer

Searching for an officer

Description

The OpenCorporates officer search endpoint (GET officers/search) allows for the searching of our officers within our data set. Returning a list of possible matches that meet the search criteria.

GET officers/search

The following examples demonstrate how to call an authenticated officers search method using the basic query parameters.

Further API documentation can be found here.

Examples

These examples call the officers/search endpoint providing a basic search query using the q parameter to provide the basic search string.

The cURL example returns a verbose JSON direct from the API, where as the NodeJS example uses console.table to make the results more consumable.

curl "https://api.opencorporates.com/v0.4/officers/search?q=Christopher%20Taggart&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/officers/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 officer to query e.g. 'Christoper Taggart'")
    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 officers
    OCUtils.makeOCRequest(options, function(statusCode, payload){
        //Use JSONPath to pull each of the officers.
        var officers = jp.query(payload, "$.results.officers..officer");    
        console.log("");
        // Print (as a table) the officers array from the response
        console.table(officers, ["id", "name", "position", "opencorporates_url"]);
        console.log("");
    });
}

Results

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 officers list and extract illustrative fields.
Both are powered using the same response from the API. 

Note the examples have used jurisdiction_code set to 'gb' to restrict the search further.
oc@demo % curl "https://api.opencorporates.com/v0.4/officers/search?q=Christopher%20Taggart&api_token=xxxxxxxxxx&jurisdiction_code=gb"
{
  "api_version": "0.4",
  "results": {
    "page": 1,
    "per_page": 30,
    "total_pages": 2,
    "total_count": 31,
    "officers": [
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {
        "officer": {
          "id": 280995341,
          "uid": null,
          "name": "CHRISTOPHER TAGGART",
          "jurisdiction_code": "gb",
          "position": "director",
          "retrieved_at": "2023-04-04T00:00:00+00:00",
          "opencorporates_url": "https://opencorporates.com/officers/280995341",
          "start_date": "2018-03-21",
          "end_date": null,
          "occupation": "DIRECTOR",
          "current_status": null,
          "inactive": null,
          "address": "ASTON HOUSE CORNWALL AVENUE, LONDON, N3 1LF, UNITED KINGDOM",
          "nationality": "BRITISH",
          "date_of_birth": null,
          "company": {
            "name": "OPENCORPORATES HOLDING LTD",
            "jurisdiction_code": "gb",
            "company_number": "11268479",
            "opencorporates_url": "https://opencorporates.com/companies/gb/11268479"
          }
        }
      },
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...},
      {... result ommited for brevity ...}
    ]
  }
}
node officer_search.js --api_token xxxxxxxxxx --q "Christopher Taggart"
Searching for: 'Christopher Taggart'
Using API Key: xxxxxxxxxx
Request URL: https://api.opencorporates.com/v0.4/officers/search?q=Christopher%20Taggart&api_token=xxxxxxxxxx&jurisdiction_code=gb

┌─────────┬───────────┬──────────────────────────────────────┬─────────────┬─────────────────────────────────────────────────┐
│ (index) │    id     │                 name                 │  position   │               opencorporates_url                │
├─────────┼───────────┼──────────────────────────────────────┼─────────────┼─────────────────────────────────────────────────┤
│    0    │ 38894849  │      'CHRISTOPHER IAIN TAGGART'      │ 'director'  │ 'https://opencorporates.com/officers/38894849'  │
│    1    │ 193079181 │  'CHRISTOPHER JEREMY PAUL TAGGART'   │ 'secretary' │ 'https://opencorporates.com/officers/193079181' │
│    2    │ 207018312 │    'CHRISTOPHER MATTHEW TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/207018312' │
│    3    │ 38472095  │    'CHRISTOPHER MATTHEW TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/38472095'  │
│    4    │ 194962890 │    'CHRISTOPHER MATTHEW TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/194962890' │
│    5    │ 275613776 │    'CHRISTOPHER MATTHEW TAGGART'     │ 'secretary' │ 'https://opencorporates.com/officers/275613776' │
│    6    │ 204697168 │    'CHRISTOPHER MICHAEL TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/204697168' │
│    7    │ 209230620 │    'CHRISTOPHER MICHAEL TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/209230620' │
│    8    │ 202975447 │    'CHRISTOPHER MICHAEL TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/202975447' │
│    9    │ 202975096 │    'CHRISTOPHER MICHAEL TAGGART'     │ 'secretary' │ 'https://opencorporates.com/officers/202975096' │
│   10    │ 201075395 │    'CHRISTOPHER MICHAEL TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/201075395' │
│   11    │ 213891291 │    'CHRISTOPHER MICHAEL TAGGART'     │ 'secretary' │ 'https://opencorporates.com/officers/213891291' │
│   12    │ 35435248  │    'CHRISTOPHER MICHAEL TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/35435248'  │
│   13    │ 37758628  │    'CHRISTOPHER MICHAEL TAGGART'     │ 'secretary' │ 'https://opencorporates.com/officers/37758628'  │
│   14    │ 35451889  │ "CHRISTOPHER PETER TAGGART O'CONNOR" │ 'director'  │ 'https://opencorporates.com/officers/35451889'  │
│   15    │ 37238276  │ "CHRISTOPHER PETER TAGGART O'CONNOR" │ 'director'  │ 'https://opencorporates.com/officers/37238276'  │
│   16    │ 183449773 │ "CHRISTOPHER PETER TAGGART O'CONNOR" │ 'director'  │ 'https://opencorporates.com/officers/183449773' │
│   17    │ 278319472 │        'CHRISTOPHER TAGGART'         │ 'director'  │ 'https://opencorporates.com/officers/278319472' │
│   18    │ 188272485 │        'CHRISTOPHER TAGGART'         │ 'director'  │ 'https://opencorporates.com/officers/188272485' │
│   19    │ 206814999 │        'CHRISTOPHER TAGGART'         │ 'director'  │ 'https://opencorporates.com/officers/206814999' │
│   20    │ 278319459 │        'CHRISTOPHER TAGGART'         │ 'director'  │ 'https://opencorporates.com/officers/278319459' │
│   21    │ 287678970 │        'CHRISTOPHER TAGGART'         │ 'director'  │ 'https://opencorporates.com/officers/287678970' │
│   22    │ 280995341 │        'CHRISTOPHER TAGGART'         │ 'director'  │ 'https://opencorporates.com/officers/280995341' │
│   23    │ 214385607 │    'CHRISTOPHER TERENCE TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/214385607' │
│   24    │ 191204755 │    'MATTHEW CHRISTOPHER TAGGART'     │ 'director'  │ 'https://opencorporates.com/officers/191204755' │
│   25    │ 212965668 │  'ROBERT JOHN CHRISTOPHER TAGGART'   │ 'director'  │ 'https://opencorporates.com/officers/212965668' │
│   26    │ 212592810 │  'ROBERT JOHN CHRISTOPHER TAGGART'   │ 'director'  │ 'https://opencorporates.com/officers/212592810' │
│   27    │ 211781417 │  'ROBERT JOHN CHRISTOPHER TAGGART'   │ 'director'  │ 'https://opencorporates.com/officers/211781417' │
│   28    │ 355369442 │     'SCOTT CHRISTOPHER TAGGART'      │ 'director'  │ 'https://opencorporates.com/officers/355369442' │
│   29    │ 261470779 │      'SEAN CHRISTOPHER TAGGART'      │ 'director'  │ 'https://opencorporates.com/officers/261470779' │
└─────────┴───────────┴──────────────────────────────────────┴─────────────┴─────────────────────────────────────────────────┘
Updated on June 2, 2023
Was this article helpful?
Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support