GET /v1/entity

HTTP Method: GET

Path: /v1/entity

Authentication: API Key required

Description: Fetch an single entity (business) by supplying its unique identifier.

Parameters:

Sample Response:

When retrieving and entity (a business), then the "data" would contain everything that is known about a business:

{
    "success": true,
    "msg": "ok",
    "data": {
        "_id": "379236608286720",
        "_rev": "9-0d00bb35d6ae504d7478c547635abc75",
        "type": "business",
        "when": "2012-12-07 14:37:42 +00:00",
        "our_data": false,
        "country": "ie",
        "scope": "public",
        "trust": 1,
        "seed": {
            "masheryid": "yourlocalie",
            "when": "2012-12-07 14:37:42 +00:00"
        },
        "status": {
            "status": "active",
            "meta": {
                "source": [],
                "confidence": 100
            }
        },
        "tags": [{
            "tag": "fireplace construction",
            "language": "English",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "stopwords": "fireplace construction",
            "stemmed": "fireplac construct",
            "phonetic": "FRPLK KNSTRKT",
            "gen_id": 392603277185024
        }, {
            "tag": "fireplace installation",
            "language": "English",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "stopwords": "fireplace installation",
            "stemmed": "fireplac instal",
            "phonetic": "FRPLK NSTL",
            "gen_id": 392603277185025
        }],
        "name": {
            "name": "The Gas Man",
            "formal_name": "The Gas Man",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "stopwords": "the gas man",
            "stemmed": "gas man",
            "phonetic": "KS MN"
        },
        "postal_address": {
            "address1": "28 Fassaugh Avenue",
            "address2": "",
            "address3": "",
            "district": "Cabra",
            "town": "Dublin",
            "county": "County Dublin",
            "postcode": "Dublin 7",
            "address_type": "",
            "meta": {
                "source": [],
                "confidence": 100
            }
        },
        "geopoint": {
            "longitude": -6.293201,
            "latitude": 53.367048,
            "wgs84": [53.367048, - 6.293201],
            "meta": {
                "source": [],
                "confidence": 100
            },
            "geohash": "gc7x8g1mt"
        },
        "phones": [{
            "meta": {}
        }],
        "faxes": [{
            "number": "01 8684033",
            "description": "",
            "premium_rate": false,
            "meta": {
                "source": [],
                "confidence": 100
            },
            "gen_id": 379236608299009,
            "processed": "018684033"
        }],
        "categories": [{
            "category_id": "1693",
            "category_name": "Gas Installers",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "gen_id": 379236638519296,
            "stopwords": "gas installers",
            "stemmed": "gas instal",
            "phonetic": "KS NSTL"
        }, {
            "category_id": "734",
            "category_name": "Boilers Servicing and Repairs",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "gen_id": 380353440014336,
            "stopwords": "boilers servicing and repairs",
            "stemmed": "boil serv repair",
            "phonetic": "BL SRF RPR"
        }],
        "lastEditDate": "2012-12-15 08:57:17 +00:00",
        "employees": [{
            "title": "Mrs",
            "forename": "Bernie",
            "surname": "Black",
            "job_title": "",
            "description": "",
            "email": "",
            "phone_number": "",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "gen_id": 380353440018433
        }],
        "emails": [{
            "email_address": "gasman1@indigo.ie",
            "email_description": "",
            "meta": {
                "source": [],
                "confidence": 100
            },
            "gen_id": 381805038006273
        }]
    }
}

If the API had been asked to fetch a non-existent entity, then you will see this response:

{
    "success": false,
    "msg": "There was an error",
    "data": {
        "missing": true
    }
}

Three things have happened here:

• the API returns with HTTP 404 (instead of HTTP 200)
• the returned json has a success of 'false'
• the return json's data element has 'missing' set to true, meaning that this entity does not exist

A third sceanrio is possible:

{
    "success": true,
    "msg": "ok",
    "data": {
        "_id": "380354326396928",
        "_rev": "1-57d724782ea388f81d5cc1eb24aac19f",
        "type": "deprecated",
        "when": "2013-01-15 14:22:18 +00:00",
        "merged_into": "380354332282880"
    }
}

In this case, entity_id 380354326396928 has been found to be a duplicate of entity_id 380354332282880 and has been deprecated. This occurs from time to time as our internal systems continuously improve our data set.