CAFv3

Quick Start

Searching addresses

You can search for addresses using an HTTP GET call:

• Endpoint: https://cafv3.gov.gg/v3/addresses/search
• Parameters:
  • term: The JSON representation of a search term object. For example, a basic postcode search looks like this: term={index:'postCode',value:'GY1 2ET'}
  • include: Specifies what fields to include, as a comma-separated list. The available fields are listed in the full API documentation by expanding Models -> State[Addresses] -> Addresses

You need to specify some fields in the include parameter, otherwise you will receive back only a list of identifiers without any text or other address details.

Try it out

• /v3/addresses/search?term={index:'postCode',value:'GY1 2ET'}&include=text - search by postcode
• /v3/addresses/search?term={index:'address',value:'Digimap'}&include=text,xy - search by address and include XY

Note that, generally, you should also add a term of {index:'active',value:'true'} unless you want to receive inactive addresses in your results. E.g.:

• /v3/addresses/search?term={index:'postCode',value:'GY1 2ET'}&term={index:'active',value:'true'}&include=text - search by postcode, excluding inactive records

Full documentation

The full list of term types and includable fields are documented at /v3/search/addresses. In addition, the full documentation shows how to sort results, limit the number of results and skip a number of results for windowed searching (e.g. for paginated display).

Searching roads

The same style of API can be used for searching the road list:

• /v3/roads/search?term={index:'name',value:'Pier'}&include=name - search by name

Testing using cURL

cURL is a widely available command line tool which is useful for testing web service calls.

To test a simple GET request, simply specify the URL:

> curl https://cafv3.gov.gg/v3/lastRef
132811

This request works without authentication (the /v3/lastRef call does not require authentication).

All other calls require authentication and will return a 401 HTTP status code response without it:

> curl https://cafv3.gov.gg/v3/addresses/35368/current?include=business,subElementDesc
{
  "message": "No authentication details provided. Please use HTTP Basic authentication, supplying your API key as your username."
}

To specify your API key, use curl's -u <user:password> switch, specifying your API key and a blank password:

> curl https://cafv3.gov.gg/v3/addresses/35368/current?include=business,subElementDesc -u {apiKey}:
{
  "journal": "Addresses",
  "doc": 35368,
  "rev": 1,
  "ref": 124224,
  "attributes": {
    "business": "Digimap Ltd",
    "subElementDesc": ""
  },
  "from": "2018-11-28T05:06:39.419664",
  "predecessorRef": 35368
}

Doc, Rev and Ref

Every object returned by the CAF v3 API contains properties 'Doc', 'Rev' and 'Ref':

• Doc: An assigned identifier for the object. The meaning of this identifier depends on the type of object, and is described in each case in the full API documentation. However, whatever the type of object, the Doc is immutable, so however the properties of an address point or road change, the Doc will remain the same.
• Rev: An incrementing revision number for this object. Consecutive revision of the same object have consecutive revision numbers. The Rev number is incremented whenever there is a change to the intrinsic properties of an object.
• Ref: A globally unique identifier for the current revision of this object. Refs are assigned incrementally, which means a Ref also identifies the state of the CAF data at that point in time.