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/searchThe 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' │ └─────────┴───────────┴──────────────────────────────────────┴─────────────┴─────────────────────────────────────────────────┘