County API

The Surpass County API lets you retrieve the unique identifier for each county in the United Kingdom. These identifiers can be used when assigning a county to a resource, for example, when creating centres using the Centre API. For more information on the Centre resource, read Centre API.

The County API resource is used to list and retrieve counties.

This article explains what calls can be made to the Surpass API using the County resource.

Import this API into your Postman Workspace

Listing counties

get /api/v2/County

Send a request to the endpoint to retrieve a list of counties. Refer to the available parameters to influence the response. No request body is required.

Parameters

Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.

EXAMPLE: The endpoint /api/v2/County?$filter=contains(name, 'Yorkshire') would return all countries that contain ‘Yorkshire’.

Name	Parameter	Input	Description
authorization	header MANDATORY	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
top	query OPTIONAL	`/api/v2/County?$top={top}`	Defines number of responses to return when paging a response, where `{top}` is a number between 1 and 40.
skip	query OPTIONAL	`/api/v2/County?$skip={skip}`	Defines how many responses to skip when paging a response, where `{skip}` is a number that should not exceed the total number of responses.
filter	query OPTIONAL	`/api/v2/County?$filter={filter} {operator} {value}`	Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: `{filter}` is `id`, `{operator}` is `eq` (equal to), and `{value}` is the integer the filter query looks for an exact match for in the request. For a greater than query: `{filter}` is `id,` `{operator}` is `ge` (greater than), and `{value}` is the integer the filter looks for more than in the request. For a less than query: `{filter}` is `id,` `{operator}` is `le` (less than), and `{value}` is the integer the filter looks for less than in the request. For a contains query: `{filter}` is `contains({attribute}, '{value}')`, where `{attribute}` is `name`; and `{value}` is the string the filter query looks for the data to contain in the request.
orderBy	query OPTIONAL	`/api/v2/County?$orderBy={attribute}`	Determines order of results, where `{attribute}` is `name`.

TIP: Multiple query parameters can be passed in a request at once. filter parameters can be joined using and between attributes. top, skip, and other parameters are joined using &. For example, the endpoint /api/v2/County?$top=10&$skip=25 would skip the first 25 results and return 10.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.

{
    "count": 253,
    "top": 10,
    "skip": 0,
    "pageCount": 26,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/County?$skip=10",
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/1",
            "name": "Greater London"
        },
        {
            "id": 2,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/2",
            "name": "Greater Manchester"
        },
        {
            "id": 3,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/3",
            "name": "Merseyside"
        },
        {
            "id": 4,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/4",
            "name": "South Yorkshire"
        },
        {
            "id": 5,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/5",
            "name": "Tyne and Wear"
        },
        {
            "id": 6,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/6",
            "name": "West Midlands"
        },
        {
            "id": 7,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/7",
            "name": "West Yorkshire"
        },
        {
            "id": 8,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/8",
            "name": "Bedfordshire"
        },
        {
            "id": 9,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/9",
            "name": "Buckinghamshire"
        },
        {
            "id": 10,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/10",
            "name": "Cambridgeshire"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

NOTE: Unique identifiers above and including 110 are country codes, such as GM for The Gambia. For more information on countries, read Country API.

Retrieving county information

get /api/v2/County/{id}

Send a request to the endpoint to retrieve information for a specific county using its ID. No request body is required.

Parameters

Name

Parameter

Input

Description

authorization

header

MANDATORY

Basic {credentials}

Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string.

accept

header

OPTIONAL

application/json or application/xml

Determines data format of the response, which can be either JSON or XML.

path

MANDATORY

/api/v2/County/{id}

Returns information for the specified county, where {id} is the county’s unique identifier.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.

{
    "count": null,
    "top": null,
    "skip": null,
    "pageCount": null,
    "nextPageLink": null,
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/County/1",
            "name": "Greater London"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Error Codes

Refer to the following table for information on error codes that may be encountered when using this resource.

Name	Code	Description
InternalServer	1	Internal server error.
Unauthorized	3	The request has been sent by an unauthorised user.
IncorrectFieldFormat	4	A field in the request has not been completed in the correct format.
InaccessibleOperation	5	The request has been sent by a user with invalid permissions.
InaccessibleData	6	The request has been sent by a user with invalid permissions.
InvalidInputParameters	15	There is an issue with the path or query parameters.
InvalidId	16	The ID number used in the request is invalid.
InvalidODataOperation	19	There is an issue with the query parameters.
BadRequest	20	There is an issue with the `/api/v2/County?$skip={skip}` query parameter, where `{skip}` is a number that should not exceed the total number of responses.

County API

In This Article

Listing counties

Parameters

Sample response

Response schema

Retrieving county information

Parameters

Sample response

Response schema

Error Codes

Further reading

About the site