Confusing documentation for beta API

API Issues
1

I’m trying to use the new beta API, and I’m finding the documentation rather confusing. Here are some things I’ve encountered:

  1. When viewing my applications (https://developer.companieshouse.gov.uk/developer/applications), there is a link on the left hand side for Authentication (https://developer.companieshouse.gov.uk/account/docs/oauth2/oauth2.html) - it 404s.

  2. When I look at a specific application in my account (e.g.: this for staff reference) the API Key field is blank, and there is no field for Client ID. But when I look at the list of my applications (https://developer.companieshouse.gov.uk/developer/applications) the only field I see is Client ID. I’m left presuming that Client ID and API Key actually have the same meaning for this API, seeing as I don’t in fact have an API Key…

  3. Point 2 above is further confused by the Authorisation documentation (https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/apikey_authorisation.html), which makes no reference to Client ID, so again, I can only presume that my Client ID is actually my API Key.

  4. Moving forward with the above assumptions, I try to make requests against the API. I’m using the Python Requests library, which has builtin support for HTTPBasicAuth. I use my app’s Client ID as the username, and leave the password empty, as per the documentation. My code looks like:

import requests
from requests.auth import HTTPBasicAuth
>>> response = requests.get('https://api.companieshouse.gov.uk/search/companies', auth=HTTPBasicAuth('MY_CLIENT_ID_HERE', ''))
>>> response.json()
>>> {'errors': [{'error': 'access-denied', 'type': 'ch:service'}]}

Note: I’m workng from localhost, so I added 127.0.0.1 to Restricted IPs.

I’d like to be able to use the API: what steps am I missing/is the documentation missing in order to do so?

1 Like
2

Just wanted to say thinks for your post - the only way I found the link to the Developer Hub or how to get my API key (it was blank, same as yours) was by reading this post.

3

Hi @mike: it is good to know it helped you. I still don’t have the API working though - are you actually making successful requests? If so, is there any light you can shed on it, as it seems things are a bit slow to get an official response.

4

@pwalsh yeah it’s fine for me. Getting some HTML in some JSON fields, which is annoying, but otherwise OK. This is node but you should be able to convert it to Python / requests pretty easily:

	var superagent = require('superagent');

	var log = console.log.bind(console)

	var API_KEY = 'FILL ME IN'

	var getHelper = function(endPoint, query, cb){
		superagent
		  .get('https://api.companieshouse.gov.uk/'+endPoint)
		  .query(query)
		  // From https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/apikey_authorisation.html
		  // the Companies House API takes the username as the API key and ignores the password;
		  .auth(API_KEY, '')
		  .end(cb)
	}

	var search = function(item){
		getHelper('search/companies', {
			q: item
		}, function(err, res){
			if ( err ) {
				return log(err)
			}
			log(res.ok)
			log(res.body)
		})

	}

Then just run:

search('something')

PS. I have ‘Restricted IPs’ set to ‘No IP restrictions’

5

Ah @mike you’re a champ: it was just the IP restriction thing!

6

:+1:

Fun fact: posts have to be 20 characters.

7

Thank you for the feedback. The issues you raised about the 404 and the missing API key are being looked at now, and I’ll update this thread when they’re fixed. You’re right about the confusion of Client ID and API key, that will be renamed.

Are you still experiencing difficulties with the API?

8

No more difficulties, apart from the specific issues I’m opening to discuss the functionality of the API. But the docs really do need addressing in order for people to get on board smoothly.

9

Just a point: the IP address “127.0.0.1” means “this machine” so adding it to the list of hosts may well be what causes the issue. Since when your request hits the CH server it will see the requests coming from your external IP address(or more likely an IP address from your service provider’s network), which is not 127.0.0.1, it probably just decides not to respond.

The site http://www.whatsmyip.org/ will tell you what IP the companies house server will see, but it’s easier just to work unrestricted until you get definite results. If you just remove the 127.0.0.1 from the restrictions list, leaving it empty, you will probably see a result.

S