I don’t know of any endpoint which ONLY gives you a single exact match or nothing. (Except if you have the company number but that’s not a search though.
I don’t know how the alphabetic search works though - just possibly that would?
So you could try using the “Companies Search” endpoint of the API.
If you get back zero results (an empty items array) your name doesn’t match. If you get back results you need to check the first one - or perhaps first few - to see if the name (title member) matches your text.
For the matching part you could either:
a) Try being lucky - assume an exact match will be the first result returned - and just check the name against what you have. Alternatively check several.
b) Make the search more specific with the new restrictions parameter. For example you could use the legally-equivalent-company-name value - this will only match on “legally equivalent names” as it says (e.g. so “ltd” in you search will match e.g “ltd.”, “limited” etc. So it won’t guarantee that it only matches EXACTLY what you’ve supplied. However this will greatly limit the numbers of responses that do match so an “exact” match should be the first one (if it exists). Again you will need to check your text against the returned title field.
You can add other restrictions here also e.g. active-companies for only active ones.
You can specify a small items_per_page value e.g. 2 or 3 to save retrieving data you won’t use. (There was and there may still be a bug if items_per_page is 1 - check this carefully).
Let’s try an example. I’m using curl here. That means that as we’re passing parameters in the url text values like space will need urlencoding - hence the “%20” etc.
Here’s a totally non-existent name, doesn’t match anything at all. Nothing found here:
curl -u YOURAPIKEY: “https://api.company-information.service.gov.uk/search/companies?q=abzxysfe&items_per_page=2&start_index=1”
Response - http 200.
{
"kind": "search#companies",
"page_number": 1,
"items_per_page": 3,
"total_results": 0,
"items": [ ],
"start_index": 0
}
Items is empty - no results found.
Example 2 - a “standard” search for “AB CAPITAL LTD”:
curl -u YOURAPIKEY: “https://api.company-information.service.gov.uk/search/companies?q=ab%20capital%20ltd&items_per_page=3&start_index=1”
(I’ve skipped the JSON here but it returns various companies matching the name and variations of it - the total_results is quite large, obviously it only returns the number of those given by items_per_page).
- Adding a restriction to this to make it more specific:
curl -u YOURAPIKEY: “https://api.companyinformation.service.gov.uk/search/companies?q=ab&items_per_page=3&start_index=1&restrictions=legally-equivalent-company-name”
(I’ve skipped some values below for clarity):
{
"start_index": 0,
"items_per_page": 3,
"total_results": 4,
"items": [
{
...
"company_number": "11325602",
"title": "AB CAPITAL LTD",
}
],
...
}
- If you add the
active-companies restriction you only get one for this particular example:
curl -u YOURAPIKEY: “https://api.company-information.service.gov.uk/search/companies?q=ab&items_per_page=3&start_index=1&restrictions=active-companies%20legally-equivalent-company-name”
Hope this helps.
