Different structure being returned compared to the documentation


Looking at the chargeDetails resource - Companies House Public Data API: chargeDetails

Why am I getting an object and not an array of objects for keys such as classification, links, particulars etc

Is the documentation wrong, or does the API return an object when there is only one item?

Thanks in advance

Indeed - if you’re using the Public Data API (as the choice of documentation you link to would indicate) the specification doesn’t match what you get back. (This isn’t the only place either - this forum has a good coverage now if you run into any issues.)

You can see a discussion of this (with examples of what you should see) in the thread below. Note that in that thread Philip believed you might get either an array OR an object here. I have not found that to be the case. Philip’s belief apparently comes from experiences where this did occur but in a different endpoint in the streaming API rather than the main API. I can’t speak about the streaming API but - in our experience of this endpoint, so far! - it looks to me a simple case of the documentation and implementation not matching rather than the data sometimes being in one form, sometimes in another.

In general it pays to always validate data from Companies House:

  • The structure.
  • The content.
  • Just because the data you’ve seen so far always fits one pattern doesn’t mean that the entire dataset follows it. The dataset covers some rather dissimilar legal entities and spans a very long period (as these things go).
  • Beware that Companies House sometimes change things… (law changes)
  • …and the public themselves enter data there with very little - if any - validation!

This is another documented example where the endpoints return data in a structure that is not consistent with the specification.

This has nothing to do with legal changes or disparate data entered by users, it simply is a bug (as I have pointed out previously).

I agree.

Maybe I should have written the last suggestion better (for this specific case) as: "do read the documentation and/or Swagger / OpenAPI specification but beware it’s not always correct or comprehensive. Be sure to test and validate what you get back. If things are not as you expect try searching this forum. Often other users will have recorded the issue you experienced here. You may find documentation of what actually occurs, suggested work-arounds and / or examples end-point calls and matching responses.

Good luck.