JSON class object for Company Search within c# windows app

Hi all,

I’m a newbie to the forum and to using the CO API. I am developing a standalone workstation app in c# on VS 2015 with Newtonsoft.JSON.

Starting simple I am writing an app to search for company names listed based on a search string. In essence I’m doing a
GET https://api.companieshouse.gov.uk/search
with the q parameter set
Got this bit working. Working sweetly. Now to understand the Response.

Documentation says the response is JSON and my HTTPClient is set up to receive. The API documentation gives a Search Resource Representation which is not in the JSON class structure used in VS.

Has the class already been documented in this style, or do I have to create if from the representation or is there a tool I’m unaware of that will create the class object from the Resource Representation?

If I am misunderstanding what I need to do programatically let me know. No knowledge is wasted even if it isn’t used for a long time.

Many thanks :grinning:

Just thought I would add this, in case someone else has already faced it. I noticed that with .NET 4 on I can use dynamic rather than define explicitly the JSON object(s),

So trying this our I am using the c# source

var url = theURL + “/search”;

        if (theSearchtext.Length > 0)
            url = string.Format("{0}?q='{1}'",url, theSearchtext);
        HttpResponseMessage response = client.GetAsync(url).Result;
        if (response.IsSuccessStatusCode)
        {
            tbOutput.Text = string.Empty;
            var theCompanies = response.Content.ReadAsStringAsync().Result;
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            dynamic jsonDe = JsonConvert.DeserializeObject(theCompanies);
            int myIndex = 0;
            if (jsonDe.total_results > 0)
            {
                tbOutput.Text = "Total number of Companies found: " + jsonDe.total_results+"\r\n";
                tbOutput.AppendText(string.Format("\r\nItems grouped in {0}", jsonDe.items.Count));
                foreach (var item in jsonDe.items)
                {
                    tbOutput.AppendText(string.Format("\r\n{0} :: {1} :: {2}", myIndex++, item.company_number, item.title));
                }
            }

Using the text string “Profile Business” this produces the output
Total number of Companies found: 58996

Items grouped in 20
0 :: 09283478 :: PROFILE BUSINESS SOLUTIONS LTD
1 :: 02990482 :: PROFILE BUSINESS SERVICES LIMITED
2 :: 05881052 :: FX COMPARED LIMITED
3 :: 09914479 :: BUSINESS PROFILES LIMITED
4 :: 04582250 :: PROFILE - THE BUSINESS SOLUTIONS COMPANY LIMITED
5 :: 07675750 :: PROFILE 4 BUSINESS SUPPORT LIMITED
6 :: 04482012 :: HIGH PROFILE BUSINESS SERVICES LIMITED
7 :: :: ANGLIAN BUSINESS CONSULTANCY SERVICES
8 :: :: ANGLIAN BUSINESS CONSULTANCY SERVICES

As you can see once I get passed company 6 the Title is repeated and there is no company number. Using the q value of “Profile Business” on the web based Try It

https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html#here

Below is the output of company 6 and company 7. I can see that the structure is different. The structure also doesn’t match the “Items” structure defined in

This may be down to my misunderstanding of what would be happening or the documentation is out of sync.

Any advice greatfully received.

{
“kind”: “searchresults#company”,
“description_identifier”: [
“dissolved-on”
],
“address_snippet”: “6 Spring Gardens, Woodford Green, Essex, England, IG8 7DD”,
“company_status”: “dissolved”,
“snippet”: “”,
“links”: {
“self”: “/company/04482012”
},
“company_number”: “04482012”,
“description”: “04482012 - Dissolved on 14 February 2012”,
“address”: {
“region”: “Essex”,
“address_line_1”: “Spring Gardens”,
“premises”: "6 ",
“locality”: “Woodford Green”,
“postal_code”: “IG8 7DD”,
“country”: “England”
},
“matches”: {
“snippet”: [],
“title”: [
6,
12,
14,
21
]
},
“title”: “HIGH PROFILE BUSINESS SERVICES LIMITED”,
“date_of_cessation”: “2012-02-14”,
“company_type”: “ltd”,
“date_of_creation”: “2002-07-10”
},
{
“matches”: {
“title”: [
1,
7
],
“snippet”: [
1,
8
]
},
“company_type”: “ltd”,
“date_of_creation”: “2008-05-27”,
“date_of_cessation”: “2012-09-11”,
“title”: “PROFILE YOU LIMITED”,
“description”: “06602233 - Dissolved on 11 September 2012”,
“address”: {
“address_line_2”: “Hale”,
“country”: “United Kingdom”,
“postal_code”: “WA15 9NJ”,
“locality”: “Altrincham”,
“premises”: "2 ",
“address_line_1”: “Park Road”,
“region”: “Cheshire”
},
“company_number”: “06602233”,
“links”: {
“self”: “/company/06602233”
},
“snippet”: "BUSINESS SERVICES 8 ",
“description_identifier”: [
“dissolved-on”
],
“kind”: “searchresults#company”,
“address_snippet”: “2 Park Road, Hale, Altrincham, Cheshire, United Kingdom, WA15 9NJ”,
“company_status”: “dissolved”
},

Aha - you’ve probably spotted it yourself now but the last two results are actually officer appointment items, not companies. You get these in the list because you’re using:

var url = theURL + "/search";

…which searches for all results (companies and officer appointments). If you’re just wanting to search for company names, you probably want:

var url = theURL + "/search/companies";

You can compare the two at the CH Beta site:

vs.

Brilliant. No, I was definately slow there. Was just about to look at what I was doing wrong and you beat me to it.

Saving me time not seeing the wood for the trees is definitely worth a pint/glass of wine/whatever the tipple.

Thank you :grinning:

As an aside, there is something slightly strange (or at odds with what I understand from the documentation I’ve seen) about those officer results. When you look at the officers list for the companies e.g.
/company/06909966/officers
…the json for this officer records them as “officer_role”: “secretary” / “director” - I had assumed that this would be the constant “corporate-secretary” or “corporate-director” (as in the constants.yml file) etc.

I don’t know whether this is a bug / old data or if my assumptions are wrong!

Example 1)
/officers/Hpn0KrPOAOP4OKqshrfqqtUfJ68/appointments
Looking at e.g. /company/06909966/officers

{
    "name": "ANGLIAN BUSINESS CONSULTANCY SERVICES",
    "officer_role": "secretary",
    "links": {
        "officer": {
             "appointments": "/officers/Hpn0KrPOAOP4OKqshrfqqtUfJ68/appointments"
        }
     },
     ...
}

Example 2)
/officers/pKu3WfC8D4At24esTw74lsnC9xs/appointments
Looking at e.g. /company/06903160/officers

{
    "name": "ANGLIAN BUSINESS CONSULTANCY SERVICES",
    "officer_role": "secretary",
    "links": {
        "officer": {
            "appointments": "/officers/pKu3WfC8D4At24esTw74lsnC9xs/appointments"
         }
    },
    ...
}

Thanks for the aside. I’ll keep that in mind when looking up and checking against companies I know

EDIT - changing my response text below!

The /company/06909966/officers “ANGLIAN BUSINESS CONSULTANCY SERVICES” officer isn’t registered as a company with CH so I guess the values given are fair enough. Showing my lack of subject knowledge - I thought you were a sole trader under your own name or you’d need to register in some way. I’m guessing no-one’s changed their name to “ANGLIAN BUSINESS CONSULTANCY SERVICES”…

EDIT - after reading the following:

…I checked and actually this did exist as company, but dissolved in 2009 so won’t be available via the API.

ANGLIAN BUSINESS CONSULTING SERVICES LIMITED - 05998939

You can look the name up on WebCHeck or get the data via a call to the company URI e.g. http://data.companieshouse.gov.uk/doc/company/05998939.json here. (I think you can either have ‘.json’ at the end of the URI or use http content negociation to get the format you want from json, html, xml, csv…).

If “ANGLIAN BUSINESS CONSULTANCY SERVICES” and “ANGLIAN BUSINESS CONSULTING SERVICES LIMITED” represent the same entity, why aren’t they returned as companies e.g. as “corporate-secretary” / “corporate-director” (as appropriate)? Could be this was never flagged as a company?

Another possibility is that CH alters the data returned by the officer list request such that officers which are corporate entites (or legal persons?) which were dissolved more than 6ish years ago / can’t be looked up in API are not returned as e.g. “corporate-director” but just “director” as if they were individual persons.

I’ll keep an eye out for more…

So how to tell these apart from actual individual persons? Doesn’t seem to be a simple solution - those I’ve seen are missing “date_of_birth” field but so are actual individuals e.g. /officers/LADpprauE0nmHG2BR8zb2Q9TZLQ/appointments . The officer appointments list (e.g. /officers/Hpn0KrPOAOP4OKqshrfqqtUfJ68/appointments) field “is_corporate_officer” is set to false which also doesn’t help.

I’d find it more useful if they returned these as e.g. “corporate-director” - ideally providing the company registration number (even though this won’t provide any data if looked up using the API). Ideally of course there would be a flag set that company data isn’t in API!

Created a question on this last point: officer_role values - meaning of "corporate"