Responsible Local Authority from Address

The challenge facing NHS Trusts that need to make referrals to Social Care include:

  • NHS Trusts deal with multiple Local Authorities
  • Health system / end user does not know which Local Authority is responsible for providing Social Care for a patient
  • Manual checking of responsible Local Authority is time consuming
  • System / user may not know the appropriate format and/or current address to send a referral to, once the LA has been determined.
  • Existing tools work on Postcode, however many Postcodes span Local Authority boundaries (see below)
PostcodeSplitMap


The Healthcare Service Locator API is service that NHS Trusts can use to identify which Local Authority is responsible for a patient (i.e. based on their home/main address), the service will also return the preferred Endpoint(s) for the required Healthcare Service. It operates at the property/building level, so will still provide the correct result where postcodes straddle Local Authority boundaries

The diagram below show the system interactions:

HealthcareServiceLocator-SequenceDiagram

HTTPS Request

Method:

GET

Host Environments:

Environment Host
Test fhir-test.nottinghamshire.gov.uk
Live fhir.nottinghamshire.gov.uk

Base URL:

/LocatorService/v2/HealthcareService

Query Parameters:

Name Card. Type Note
_query 1..1 Fixed: "responsibleLAfromAddress" Additional query types could be supported in future versions, e.g. Responsible LA from GPS Co-ordinates
address 1..1 string The address should be comma separated, however, because the comma has special meaning in FHIR, each comma in the parameter value should be escaped with a preceding '\'. The address parameter is case insensitive. The value SHALL be URL Encoded
postcode 1..1 string The postcode parameter is case insensitive & can be supplied with or without a space. The value SHALL be URL Encoded
type 1..1 coding Coding for the type of Social Care Sevice required.

Binding: LocatorService-HealthcareServiceType

Note: Currently only http://snomed.info/sct|715591000000108 is suppported. Additional HealthcareService types could be supported in future versions, e.g. "GP Referral to Social Care". The value SHALL be URL Encoded.

The HTTP GET will consist of 'https://'+'{Host}'+'{BaseURL}'+'?'+'{QueryString}'

See examples for an illustration of a search query and respective URL encoding

Response

The API Resposne will be a single Bundle Resource with Zero or One HealthcareService entries:

HealthcareServiceLocator-ClassDiagram


Profiles

StructureDefinition Version
CareConnect-LocatorService-HealthcareService-1 0.0.1
CareConnect-LocatorService-Organization-1 0.0.1
CareConnect-LocatorService-Location-1 0.0.1
LocatorService-Endpoint 0.0.1
Extensions Version
tbc tbc
ValueSets Version
LocatorService HealthcareServiceType 0.0.1
LocatorService OrganizationType 0.0.1
CodeSystems Version
ODS API Organization Role 1.12.0

Further details of the StructureDefinitions, including tree and table structures, are available here

Examples

Search Query

Unencoded query string

https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/HealthcareService?_query=responsibleLAfromAddress&address=23 Deer Park Drive\, Nottingham&postcode=NG5 8SA&type=http://snomed.info/sct|715591000000108

URL Encoded version

https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/HealthcareService?_query=responsibleLAfromAddress&address=23%20Deer%20Park%20Drive%5C%2C%20Nottingham&postcode=NG5%208SA&type=http%3A%2F%2Fsnomed.info%2Fsct%7C715591000000108

Responses

Example 1 - Response for Local Authority in a two tier structure that supports FHIR and Email Referrals

{
    "resourceType": "Bundle",
    "id": "87fce214-e677-4664-8b04-4615549e4a2c",
    "meta": {
        "lastUpdated": "2020-08-25T16:42:14.138+01:00"
    },
    "type": "searchset",
    "total": 2,
    "link":  [
        {
            "relation": "self",
            "url": "https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/HealthcareService?_format=json&_query=responsibleLAfromAddress&address=23%20Deer%20Park%20Drive%5C%2C%20Nottingham&postcode=NG5%208SA&type=http%3A%2F%2Fsnomed.info%2Fsct%7C715591000000108"
        }
    ],
    "entry":  [
        {
            "fullUrl": "https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/HealthcareService/141",
            "resource": {
                "resourceType": "HealthcareService",
                "id": "141",
                "meta": {
                    "profile":  [
                        "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-HealthcareService-1|0.0.1"
                    ]
                },
                "contained":  [
                    {
                        "resourceType": "Organization",
                        "id": "o1",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Organization-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "511"
                            }
                        ],
                        "type":  [
                            {
                                "coding":  [
                                    {
                                        "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                        "code": "33",
                                        "display": "COUNTY COUNCIL"
                                    }
                                ]
                            }
                        ],
                        "name": "Nottinghamshire County Council"
                    },
                    {
                        "resourceType": "Location",
                        "id": "l1",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "139"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3015"
                            }
                        ],
                        "name": "Broxtowe Borough Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "34",
                                    "display": "BOROUGH COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Location",
                        "id": "l2",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "195"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3020"
                            }
                        ],
                        "name": "Gedling Borough Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "34",
                                    "display": "BOROUGH COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Location",
                        "id": "l3",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "286"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3040"
                            }
                        ],
                        "name": "Rushcliffe Borough Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "34",
                                    "display": "BOROUGH COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Location",
                        "id": "l4",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "127"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3010"
                            }
                        ],
                        "name": "Bassetlaw District Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "36",
                                    "display": "DISTRICT COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Location",
                        "id": "l5",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "120"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3005"
                            }
                        ],
                        "name": "Ashfield District Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "36",
                                    "display": "DISTRICT COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Location",
                        "id": "l6",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "244"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3025"
                            }
                        ],
                        "name": "Mansfield District Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "36",
                                    "display": "DISTRICT COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Location",
                        "id": "l7",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "255"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3030"
                            }
                        ],
                        "name": "Newark And Sherwood District Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "36",
                                    "display": "DISTRICT COUNCIL"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Endpoint",
                        "id": "e1",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/LocatorService-Endpoint|0.0.1"
                            ]
                        },
                        "status": "active",
                        "connectionType": {
                            "system": "http://hl7.org/fhir/endpoint-connection-type",
                            "code": "hl7-fhir-rest",
                            "display": "HL7 FHIR"
                        },
                        "managingOrganization": {
                            "reference": "#o1"
                        },
                        "payloadType":  [
                            {
                                "coding":  [
                                    {
                                        "system": "http://hl7.org/fhir/resource-types",
                                        "code": "ReferralRequest"
                                    }
                                ]
                            }
                        ],
                        "payloadMimeType":  [
                            "application/fhir+json",
                            "application/fhir+xml"
                        ],
                        "address": "https://fhir-test.nottinghamshire.gov.uk/ReferralService/v3/"
                    },
                    {
                        "resourceType": "Endpoint",
                        "id": "e2",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/LocatorService-Endpoint|0.0.1"
                            ]
                        },
                        "status": "active",
                        "connectionType": {
                            "system": "http://hl7.org/fhir/endpoint-connection-type",
                            "code": "secure-email",
                            "display": "Secure email"
                        },
                        "managingOrganization": {
                            "reference": "#o1"
                        },
                        "payloadType":  [
                            {
                                "coding":  [
                                    {
                                        "system": "http://hl7.org/fhir/endpoint-payload-type",
                                        "code": "any",
                                        "display": "Any"
                                    }
                                ]
                            }
                        ],
                        "address": "mailto:adult-social-care.test@nottscc.gov.uk"
                    }
                ],
                "active": true,
                "providedBy": {
                    "reference": "#o1"
                },
                "type":  [
                    {
                        "coding":  [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "715591000000108",
                                "display": "Hospital Discharge Notification to Social Care"
                            }
                        ]
                    }
                ],
                "name": "Nottinghamshire County Council - Social Care",
                "coverageArea":  [
                    {
                        "reference": "#l1"
                    },
                    {
                        "reference": "#l2"
                    },
                    {
                        "reference": "#l3"
                    },
                    {
                        "reference": "#l4"
                    },
                    {
                        "reference": "#l5"
                    },
                    {
                        "reference": "#l6"
                    },
                    {
                        "reference": "#l7"
                    }
                ],
                "endpoint":  [
                    {
                        "reference": "#e1"
                    },
                    {
                        "reference": "#e2"
                    }
                ]
            },
            "search": {
                "mode": "match",
                "score": 0.8
            }
        },
        {
            "fullUrl": "https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/OperationOutcome/bd0153de-d9c3-425a-9406-afed049db5c8",
            "resource": {
                "resourceType": "OperationOutcome",
                "id": "bd0153de-d9c3-425a-9406-afed049db5c8",
                "issue":  [
                    {
                        "severity": "information",
                        "code": "processing",
                        "diagnostics": "HealthcareService resource returned is based on an approximate address match"
                    }
                ]
            },
            "search": {
                "mode": "outcome"
            }
        }
    ]
}


The resposne below is for the same Address **except** that the building number is '15' instead of '23'. Although on the same street with an identical Postcode, the Responsible Local Authority is different.

Example 2 - Response for Local Authority in a Unitary structure that supports only Email Referrals 
{
    "resourceType": "Bundle",
    "id": "1a755361-659a-49fa-ae69-6f59e01cf055",
    "meta": {
        "lastUpdated": "2020-08-25T16:44:00.256+01:00"
    },
    "type": "searchset",
    "total": 2,
    "link":  [
        {
            "relation": "self",
            "url": "https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/HealthcareService?_format=json&_query=responsibleLAfromAddress&address=15%20Deer%20Park%20Drive%5C%2C%20Nottingham&postcode=NG5%208SA&type=http%3A%2F%2Fsnomed.info%2Fsct%7C715591000000108"
        }
    ],
    "entry":  [
        {
            "fullUrl": "https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/HealthcareService/63",
            "resource": {
                "resourceType": "HealthcareService",
                "id": "63",
                "meta": {
                    "profile":  [
                        "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-HealthcareService-1|0.0.1"
                    ]
                },
                "contained":  [
                    {
                        "resourceType": "Organization",
                        "id": "o1",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Organization-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "512"
                            }
                        ],
                        "type":  [
                            {
                                "coding":  [
                                    {
                                        "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                        "code": "40",
                                        "display": "UNITARY AUTHORITY"
                                    }
                                ]
                            }
                        ],
                        "name": "Nottingham City Council"
                    },
                    {
                        "resourceType": "Location",
                        "id": "l1",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/CareConnect-LocatorService-Location-1|0.0.1"
                            ]
                        },
                        "identifier":  [
                            {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "512"
                            },
                            {
                                "system": "http://ordnancesurvey.co.uk/addressbase/custodian-code",
                                "value": "3060"
                            }
                        ],
                        "name": "Nottingham City Council",
                        "physicalType": {
                            "coding":  [
                                {
                                    "system": "https://directory.spineservices.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRole-1",
                                    "code": "40",
                                    "display": "UNITARY AUTHORITY"
                                }
                            ]
                        }
                    },
                    {
                        "resourceType": "Endpoint",
                        "id": "e1",
                        "meta": {
                            "profile":  [
                                "https://fhir.nottinghamshire.gov.uk/STU3/StructureDefinition/LocatorService-Endpoint|0.0.1"
                            ]
                        },
                        "status": "active",
                        "connectionType": {
                            "system": "http://hl7.org/fhir/endpoint-connection-type",
                            "code": "secure-email",
                            "display": "Secure email"
                        },
                        "managingOrganization": {
                            "reference": "#o1"
                        },
                        "payloadType":  [
                            {
                                "coding":  [
                                    {
                                        "system": "http://hl7.org/fhir/endpoint-payload-type",
                                        "code": "any",
                                        "display": "Any"
                                    }
                                ]
                            }
                        ],
                        "address": "mailto:adult-social-care.test@nottinghamcity.gov.uk"
                    }
                ],
                "active": true,
                "providedBy": {
                    "reference": "#o1"
                },
                "type":  [
                    {
                        "coding":  [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "715591000000108",
                                "display": "Hospital Discharge Notification to Social Care"
                            }
                        ]
                    }
                ],
                "name": "Nottingham City Council - Social Care",
                "coverageArea":  [
                    {
                        "reference": "#l1"
                    }
                ],
                "endpoint":  [
                    {
                        "reference": "#e1"
                    }
                ]
            },
            "search": {
                "mode": "match",
                "score": 0.8
            }
        },
        {
            "fullUrl": "https://fhir-test.nottinghamshire.gov.uk/LocatorService/v2/OperationOutcome/333e7a34-7c34-4a6b-bfbe-c70e6cec625c",
            "resource": {
                "resourceType": "OperationOutcome",
                "id": "333e7a34-7c34-4a6b-bfbe-c70e6cec625c",
                "issue":  [
                    {
                        "severity": "information",
                        "code": "processing",
                        "diagnostics": "HealthcareService resource returned is based on an approximate address match"
                    }
                ]
            },
            "search": {
                "mode": "outcome"
            }
        }
    ]
}