Companies house charge api

API Question
#1

Hi,

We have a question relating to Companies House Public Data API specifically
GET https://api.company-information.service.gov.uk/company/{company_number}/charges.

Your documentation seems to say that particulars property is returned as a list, however, it seems that it is returned as a single json entity.

If you call the above api with a company number 10724707 the particulars element is returned as below.“particulars”: {
“contains_negative_pledge”: true,
“contains_fixed_charge”: true,
“description”: “Flat B123, 1A test road, London, T12 123.“,
“type”: “brief-description”
}

So two questions:

  1. Is the api documentation not up to date or could you explain what is the expected return type of particulars property?
  2. If is supposed to just a single particulars, could the particulars.type be anything other than brief-description?

Kind regards,
June

Different structure being returned compared to the documentation
#2

This is common with the companies house API’s. Whenever an object is defined as a list (or array), the CH API’s ONLY return it as a JSON encoded list if more than one value exists, otherwise it just returns the object without encoding it as a list / array.

I am by no means saying this is correct, but have raised many such contradictions between the spec & the returned data but have been met with silence.

#3

I agree that there are many exceptions and plenty of undocumented things but I don’t recall this particular issue (e.g. if you get one, it’s an object, if you get more than one, you get an array of objects) in the CH API (non-streaming - I’m not familiar with the streaming side). Do you have more info / examples?

The chargeList documentation definitely has some mistakes / inconsistencies. I think the “array” part of the documentation is incorrect in several places. I guess there could be some genuine oddity - for example maybe these suddenly become arrays where you have more than 1 person entitled but there are two people entitled in /company/SC100764/charges/9vFxc01YEwJI1I3wnrwz9Slb5zE (see in the web interface) and that’s not the case there. So I think this is just a mistake in the documentation. I’m not Companies House though! My own notes on this below - if these are incorrect / unclear please let me know!

Example companies with charges to check:
SC256721
03959649
03142135
SC118434
SC100764

In general the chargeList documentation is not great e.g. has errors and lacks clarity

Documentation for chargeList endpoint
https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/charges/list

(The Swagger / Openapi documentation also has a separate issue - the main Swagger/OpenAPi document currently (09/12/201) has all links to sub-documents pointing to a local IP address so you need to correct the host to get there:
https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/charges.json#/chargeList
)

Missing:
The main documentation misses that you can pass in items_per_page and start_index. These are noted in the Swagger/OpenAPI docs.
The main documentation is missing the 404 error code.

chargeList resource
Main documentation: Companies House Public Data API: chargeList

Typo:
Both main documentation (in the chargeList resource docs) AND the Swagger/OpenAPI docs have a typo:

“unfiletered_count” - should read “unfiltered_count”

Inconsistency:
This mostly follows the Companies House “paged data” format:
You can pass in an items_per_page and start_item. The start_item parameter starts from 0 - it should be a multiple of items_per_page. There were bugs around items_per_page being 1 so maybe avoid that (can’t remember if just in search endpoints or generally).
You’re returned an object with a parameter list with array of all objects, and some “counts”.
In this case:

  • The start_index or items_per_page are not returned (e.g. no members in response) despite being able to specify these.
  • You have several “counts” - but the main one is “total_count” rather than the “total_results” that you see elsewhere. (I think this is the same as Filing history).

Logically missing:
Doesn’t provide count of unsatisfied charges - you have to calculate that from unfiltered_count - satisfied_count - part_satisfied_count

Possible inconsistency
The “enum constants” provide a way to look up text. The “scottish_alterations” member (also incorrectly listed in docs as an array of objects - it’s a simple object) is slightly different - there are three boolean flags for “Scottish alterations” so you have to map these to the text yourself:

has_alterations_to_order
has_alterations_to_prohibitions
has_restricting_provisions

Incorrect (typos)?
The documentation (both main and Swagger/OpenAPI) lists several members as an array of objects when what you actually get returned is a single simple object:

  • classification
  • links
  • particulars
  • secured_details
  • scottish_alterations
  • transactions.links

Other notes:
You may want to further process the title.

1 Like
#4

The prime example is what the OP provided - the particulars are returned as an object rather than an array of objects (both your linked specs confirm it is an array of objects)

As for my comment of this being common, clearly it is an issue with the none streaming ch API’s and not simply a typo (though I haven’t extensively worked on the none streaming ch API’s)

PS: I am pretty confident that if there is more than one object, then the response will have an object array (as happens with the streaming API’s).

#5

I was referencing the Companies House Public Data API not the streaming API because that’s what the OP mentioned.

In this case - unless you or anyone else has any evidence to the contrary (and please post if you have) …
…It looks like there are several errors in both the older documentation and the Swagger / OpenAPI spec for this endpoint.

Again - as far as I can remember - this isn’t an “issue” - just incorrect documentation. In the non-streaming API I don’t remember any fields which sometimes contain an array of objects and sometimes contain a single “bare” object. The data is consistent but the documentation is wrong. Please do provide examples where the data you receive is not in the format I’ve described if you know of any as we will need to go back and check we handle them correctly! I know you’re (mostly) using the streaming API. That may be more or less closely related to the Companies House Public Data API (no idea as I don’t know the streaming one). Companies House have a raft of “similar but different” presentations of what may be the same underlying data set - I’m not certain even of that.

Back to the OP: so answer to Q.1 is:

The API documentation / Swagger spec has several mistakes (see my last post) and the type should be as if those mentioned are not arrays, but objects (e.g. the objects that the docs / spec says are returned within the arrays). So (to spell it out) particulars is returned much like it says in the documentation but as a single object:

"particulars" :
{
                    "chargor_acting_as_bare_trustee": "boolean",
                    "contains_fixed_charge": "boolean",
                    "contains_floating_charge": "boolean",
                    "contains_negative_pledge": "boolean",
                    "description": "string",
                    "floating_charge_covers_all": "boolean",
                    "type": "string"
                }

And Q2 (which I missed) “could the particulars.type be anything other than brief-description?”:

As far as I’m aware this is as it says in the documentation (see above). If you scroll down the documentation you’ll see it has possible values (per the enum constants) of:

  • short-particulars
  • charged-property-description
  • charged-property-or-undertaking-description
  • brief-description

I don’t have examples of any variants nor what you’d see in other fields for different values of “type” but if you do some searching you may find these.

Good luck.

#6

This is the bug / error / exception that the OP encountered. My point is pretty simple. It is a bug if the spec says it is an array but the endpoint produces an object.

I have encountered many of these types of spec / data inconsistencies in the streaming API s (where elements morph from objects to arrays and vice versa) that I am sure this occurs in the ch none streaming API’s too, as demonstrated by OP.

PS: I initially took your view that this type of thing was a typo in the spec, then I encountered the reverse of the very same element - I resorted to dynamic de-serialisation + checking types before evaluating.

#7

Not being from Companies House myself, just another punter… I’ll not debate the semantics. The spec and what you get don’t match - that’s true.

Beyond that what I was trying to understand is if the values being returned in this specific endpoint were inconsistent - not just that they don’t match the spec (which we’ve established). An example of an inconsistency would be that you might find that for some company numbers (or some charges within a chargeResource) you get an array of objects returned for particulars whereas the usual behaviour is that you just get a single object. Or even worse it could be that for the same input sometimes you get one, sometimes the other. I was asking you because it sounded like you had specific examples for this endpoint of that kind of issue.

As far as I can see here that’s not the case. The OP isn’t reporting that - they’re just querying why what they got doesn’t match the docs / spec.

A counter-example would be enough to report this to CH / show we have to handle both cases. If you have one - for this specific endpoint (or the analog in the Streaming API - if there is one) please post the details. Then everyone can benefit. Because as you point out we’ll likely need to work around it at least in the short term. The examples I’ve posted don’t show this (or at least not the last time I queried them… :wink:)

I’m aware there are several other points where the documentation / spec doesn’t match what you actually get returned. I’ve reported a few in the past. We also took a “explore the data and see what we get” approach when developing and we also do value / type checking (and logging - to pick up things that change or new ones that appear over time).

As regards the various APIs / CH data as a whole there certainly are what I’d call bugs e.g. the code clearly isn’t behaving as it should. There are also what appear to be “data issues” e.g. inconsistencies / values which shouldn’t be possible in the data. (We’ve reported those as well). The last point is not surprising - it’s a giant public-access data set (in fact public input - with minimal “moderation”) covering more than a century!

#8

This is a topic someone else started, but I added a list of items that I found for the filling history endpoint. And yes, some are specified as strings (as OP in thread states) but actually sometimes return arrays, but also string (this depends on the number of items). Easiest case in mind is for sic_codes - a company can have one or many - when one, live / production endpoint returns string, when many, it returns an array. I am sure this is what OP here is witnessing too.