How to create my first Rest/API to integrate all search features

API Question
#1

I am extremely overwhelmed with so much information and trying to figure it out on my own. Therefore |I am going to try to get help and see how i can make it happen.

I am trying to use the REST/API feature to add the companies search to my WordPress website.

I have already created the API key and now have to connect it to my WordPress website.

Please advise how to engage the information as i am not sure what else to do

#2

Welcome.

I recommend you take your time. This API is pretty simple as they go, but it has numerous quirks *.

If you’re using WordPress presumably you are comfortable doing some PHP programming? If not then skip to the end.

Initially I would not try to get things running in PHP - instead I’d:

a) Work out what pages (links) you would go through and what information you’d enter to get the information using Companies House search site online. The API basically mirrors the design of that (indeed some of the URLs are almost identical).

b) Then work through making the requests to the API using something very basic / simple and interactive like the curl command - so you can see exactly what information you’re sending and what you get back.

If you didn’t already I would start by reading Companies House’s own documentation. First the introduction (alas this quite isn’t as clear / up to date as it might be) and then the API documentation. Beware that the latter may not be quite correct.

Perhaps also look at the unofficial documentation complied here.

If you have specific queries try searching this forum (use the magnifying glass icon, usually at the top right of the site). If after that you’re stuck, try posting a specific query (saying what you tried, what you were expecting, what happened etc. - more information is better but do not post your API Key or other secrets here!)

Finally: there are some companies available who will provide services around Companies House, or programmers who can help for a fee.

Good luck

  • I can’t think of any public API I’ve used which doesn’t have quirks, was completely documented, or that didn’t have differences between documentation and the actual API (or at the very least a confusing mix of out-of-date and current documentation…)
#3

Thank you so much for your response. I will look into the information shared.

I am capable in PHP - and want to work on the wordpress side - i still have not been able to connect and get a response from the API - but i am working on it.

#4

Can’t connect and get a response from the API?
You’ll get some response though not necessarily anything in the http body (check the returned http response code, or if using curl - again recommended - turn on verbose with the -v flag).

Common problems involve the initial CH setup:

  • not choosing “live” when you register you app. Short - just use live ones.
  • not registering your IP address or host name / not registering the correct IP address (e.g. if you’re on some hosting service this may be variable).
  • using a local host e.g. on a development workstation without the workaround for your IP address (search the forum for “localhost workaround” or see the thread below:

).

Common problems authenticating:

  • misunderstanding the http Basic standard, or how the API key relates to the http username and password (it’s the username, and the password is empty / blank), or how your library / client / tool implements this.

Other quirks:

  • currently some - but not all - Companies House API URLs will not work if there is a trailing slash “/” at the end of the URL.

Of course PHP has a wrapper around curl (with its own quirks). Then there’s the popular PSR-7 standard for http libraries e.g. Guzzle. Unfortunately the Companies House OpenAPI specification needs some manual work to allow you to e.g. automatically generate client code from it. (I also find that this doesn’t always help understand an API - and now you’ve got two things to understand…)

#5

This is my 5th time of reading all of the above and it is quite overwhelming. this is my very first time working with REST API. I have been coding PHP and building wordpress sites for over 15 years but this companies house API is creating a challenge.

That being said I want to thank you guys who have jumped in to share advice - it does give a sense of community. With that being said, I will try to see how i can make the second steps - I already created the API and have everything set.

Can someone give me the correct URL to use for the search - as I put in my API Key i am not sure if i am using the right Companies House URL.

I will get through this because i like a challenge - but this is definitely a bone breaker.
Thanks @voracityemail

Vr/MSteele

#6

Search URL? Well, before you do that I would start with the following, probably the simplest query for this API (use curl directly from the shell / command line if you can as that provides instant feedback without any conflicting factors like your code not doing what you think…)

curl -u YOURAPIKEY: "https://api.company-information.service.gov.uk/company/00502851"

Note the “:” after your API key (because curl expects a http Basic username and password - Companies House made this so the API key is the username and there is no password…)

That should get you some text (JSON data).
If not, try getting more information - add the “-v” flag (for verbose):

curl -v -u YOURAPIKEY: "https://api.company-information.service.gov.uk/company/00502851"

The basic search URL is https://api.company-information.service.gov.uk/search/companies - to which you add parameters. Because this is a URL don’t forget to URL-encode the parameter values (PHP provides a simple query builder which is nicer for multiple parameters):

curl -u YOURAPIKEY: "https://api.company-information.service.gov.uk/search/companies?q=tescos"

… or to limit the number of results (several parts of the Companies House API implement a “paging” interface to get a subset of a larger data set):

curl -u YOURAPIKEY: "https://api.company-information.service.gov.uk/search/companies?q=tescos&items_per_page=4&start_index=0"

Certainly the first time I worked with any “remote procedures” / external interface it was more challenging. You’re far more reliant on someone else’s documentation and “try it and see”.

However working from basic principles it’s not much different from working with someone else’s code (apart from you don’t get to see that or modify it): try not to “assume”, add tests to check the data as well as your assumptions. Even where something is documented - with external APIs it seems the documentation is far more … variable, and may be inconsistent e.g. parts may be current, parts older.

If you run into a snag check the Companies House documentation but ALSO search this forum, there are several … features of the API.

Also for this particular data set the data can be pretty wild. That is by its nature - legally Companies House is mostly required to record - mostly verbatim - the information that the public at large supply. So expect omissions, duplications, mistakes, misunderstandings etc. Indeed some frankly bogus information - though you can help by reporting on anything you think is verifiably not correct. Plus data covers over a century - “fixed” things have changed in that time (laws, countries, nationalities …)

1 Like