After using the Resource Representation documents from the CH-Developer web-pages, they do not match the actual data being returned by the Company-Profile andCompany-Search API calls.
Where can I get up-to-date versions of these to help create my C# classes?
Which specific items do not match?
Hello MAW
First the differences I have found:
- ‘Search’ (all): Items:company_number; not in spec but in response.
- ‘Search’ and ‘Search-Companies’: Items:Matches:address_snippet; in spec but not in response.
- ditto: Etag; in spec but not in response.
- ditto: page-number; not in spec but in response.
Secondly, could we have a bit more info on the search parameters please. - Default values for ‘items-per-page’ and ‘start-index’.
- ‘start-index’: does it start at 0 or 1? and is it a page index or a list index?
- For both ‘times-per-page’ and ‘start-index’, do you clip these value to fit the results, or do you throw an error response?
- Where can I find the ‘api-enumerations’?
Thank you for your time, regards Ken Birch.
I think you can assume that spec is not always up-to-date with what you get back. You’ll likely have to do what we did and fill in the dots between what is listed by Companies House, what you find in the forum and what data you get back.
Start index / items per page:
- Default values for ‘items-per-page’ and ‘start-index’.
Careful - it’s “items_per_page” and “start_index” on both input and output…
You can test what you get back yourself. Like everything I would not rely on it - if it’s important for you then specify it!
- ‘start-index’
Tons of discussion on this, some of which I’ve summarised in the thread below
.
It’s quite simple (aside from a couple of bugs) - it would be helpful if Companies House put this prominently on the documentation e.g. in Overview.
Not quite sure what you mean with:
… ‘times-per-page’ [sic] and ‘start-index’, do you clip these value to fit the results …
Maybe this example will help?
Say I’ve a query that will contain 39 results.
I choose start_index=0 and items_per_page=20.
I call the endpoint and get back:
20 results (I count them!)
Some “total” field ***, here: 39
The items_per_page I passed in: 20. This will remain the same if this is greater than the total items.
The start_index I passed in - 0. This is the case UNLESS this is greater than the number of items - in which case you likely won’t get anything back at all e.g. your json body will be {}.
I can see from my “total” field that I’ve not got the lot yet. Time for another “page”.
I choose start_index=20 and leave items_per_page=20.
I call the endpoint and get back:
19 results (I count them again)
The total field *** (which is still 39)
The items_per_page I passed in: 20
The start_index I passed in: 20.
I don’t get back “items_per_page=19” because there are 19 on this page. I just have to count.
I know I’m done because I have received 20 + 19 = 39. Yes, you have to keep track of that yourself.
If you don’t pass in items_per_page then yes, Companies House will choose some default (and return that with the results). Again I would not take this as a guarantee. Check what you requested against what you got back each time and don’t assume because you requested 20 / 100 / 1000 you will get them (and get them every time going forward)!
*** There is a total field for most (but not all!) endpoints you can work through like this. Unfortunately I think the name of it is also not consistent on every endpoint so always check!