Search company officers - maximum 200 results returned

[jan_franke]

Hello everyone, I’ve written some code in R to search for officer objects corresponding to a list of names. For very common names the below call returns a lot of results, but increasing items_per_page= above 200 doesn’t seem to return more than 200 results. Is there any way to return more than 200 results in a call like this?

 fh_url <- modify_url("https://api.companieshouse.gov.uk/search/officers", query=list(q=.x))
  res <- GET(paste0(fh_url, "&items_per_page=200"), authenticate(key, ""))
  jsonlite::fromJSON(content(res, "text",encoding = "utf-8"), flatten = TRUE)

I am wrapping this in a map() call against a character vector containing names for persons of interest, so .x here is the current position in the character vector.

I hold dates of birth for the officers I am trying to identify and could make my initial get request more specific, but as per the API documentation there doesn’t seem to be a straightforward way to add dob as a match criterion to a search company officers requests.

Is there an undocumented way that dob can be added as a search criterion to make the results of this query more specific for very common officer names?

I’d be grateful for any help.

Jan

[voracityemail]

Couple of points on the number returned:

1. It doesn’t look like your code is sending the start_index parameter (https://developer.companieshouse.gov.uk/api/docs/search/officers/officersearch.html). The search endpoint is “paged” e.g. you can call and get a fraction of the results set back. You also get the total number of results in the set (total_results). If you didn’t get all the results at once, to get the next “page” you call again with start_index set to the next position.
2. For these “paged” endpoints there may be limits on items_per_page - if you go above a certain limit you don’t get any more results back. I don’t assume I will get back the number I request and always check… Then adjust the next call accordingly. e.g. first call with items_per_page=200&start_index=0 - if you got back 50 results (and the total_results field indicated there were more) the next call might be items_per_page=200&start_index=50
3. For the search endpoints there are maximum limits anyway e.g. see:

Search company officers returns HTTP 416 when start_index over 300

The following reqest to search company officers returns response with HTTP status 416 (Request Range Not Satisfiable). GET /search/officers?q=John+Smith&items_per_page=100&start_index=301 The same request with start_index <= 300 works fine. This seems to have changed recently as we used to paginate further than this in the past (last used a few weeks ago). Is this a known issue? It causes problems for us as when searching for a common name (like John Smith) we often need to paginate furth…

On the DOB, I don’t think there is ATM, see:

Https://api.companieshouse.gov.uk/search/officers query ability improvement request

Hi Mark, what is the correct manner to past the month/year into the 'q' of the query string to bring back matching results? That is my objective, I'm not interesting in results that do not contain this information, as I need as small a result set as possible.

…Nor was there in 2017 (but there are some undocumented address search facilities):

Searching by multiple fields e.g. name AND address

@MArkWilliams Is there such a feature to search an officer by name and date_of_birth? I tried using the field in a similar way, i.e. Name Surname date_of_birth:"1988,8" and it did not work. I also tried dob as keyword, or "7,1988"

[MArkWilliams]

We also produce a bulk officer product that may be interest to you.
Please let me know if you would like to be contacted about that.

[jan_franke]

Thanks both for your responses. I will try to paginate using the start index parameter, this might help getting more than 200 results as you suggest. You seem to say that there is a maximum of 100*300 results that can be returned in this way, which should be fine for my purposes.

@MArkWilliams : I’d be interested to get more detail on the bulk officer product, yes. Thank you.

[MArkWilliams]

Someone from our customer care team will contact you.

[jan_franke]

@MArkWilliams - I haven’t heard anything on the bulk officer product - I’d be keen to discuss this with your customer team. On a slightly different note, is there a similar product for companies which I could use to filter companies e.g. by post code and SIC Code?

[MArkWilliams]

you should have been contacted 2 months ago.
I will check with customer care and get back to you.