CAFv3

Migration Guide for CAF V2 users

Authentication

Instead of using SOAP headers (V1) or an API key parameters (V2), V3 is presented over the Internet using standard HTTP basic authencation over HTTPS.

If you already have a username and password (CAF V1) or API key (CAF V2), then you can use these immediately to test authentication to CAF V3:

• Click this link: /v3/me
• Your browser will ask you for a username and password.
• Enter your V1 username and password, or your V2 API key as the username and leave the password blank (you can also use a password of 'k' in case your browser insists on a password being specified).
• If authentication is successful, you will see a JSON response body with a user identifier.

REST/JSON, not SOAP/XML

The V3 API is a REST/JSON API which provides all the functionality of the V1 and V2 APIs. You can retrieve V3 assets by making standard HTTP GET requests to the URLs. This means that the search and retrieval parts of the API can be tested in the browser.

The API is also has machine readable documentation in OpenAPI format, and you can explore the API using Swagger.

Searching addresses

Address searches are carried out via the /v3/addresses/search API call. Your call should have one or more term querystring parameters, each of which is a JSON string representing a restriction on your query. For example, to query by post code, you can use the JSON string {index:'postCode',value:'JE2 4WG'}. Terms can have additional properties which specify whether to search aliases or history, or to use metaphones.

Records are never destroyed in CAF, only marked inactive, and searches continue to retrieve inactive records unless you specify otherwise. To do this, add a term of {index:'active',value:'true'}.

The CAF V2 parameters map to V3 search terms as follows:

• searchTextProperty: propertyName index
• searchTextRoad: roadName index
• searchTextRoadAlias: Use the roadName index and specify aliases: true
• searchTextParish: parish index
• searchTextPostcode: postCode index
• includeHistoric: Specify history: true
• includeInactive: Do not add the {index:'active',value:'true'} term.
• useMetaphone: Specify termType: 'metaphone'
• sortBy: Specify the order parameter as follows:
  • AddressHierarchical: cafHierarchical
  • AddressTextual: cafTextual
  • AddressToString: text
  • CAFID: ref
  • PostCodeHierarchical: cafPostCodeHierarchical_
• classifications: Classifications are not implemented in V3 as a search index in itself, because V3 has a much richer data model for additional attributes. If you require this type of functionality, please contact Digimap.
• sortDescending: Specify the order parameter value with a hyphen in front of it.
• fromIndex and maxResults: Are now querystring parameters, also called fromIndex and maxResults.

Where are the CAF IDs?

V3 provides a ref property for every object. This is a numeric value which is globally unique within the CAF database, regardless of whether the object is a Road, Address, Candidate or Parish. ref therefore provides an analogue for the CAF ID in CAF V1 and V2.

However, CAF V3 also guarantees the immutability of the doc property. Every object within a given journal (Addresses, Roads, Candidates and Parishes) has a doc which is unique within that journal. Each revision of that object also has a unique rev. For most uses, therefore, it is sufficient to store and use doc values only in your system.

GetUpdates

The ref property is primarily of use to specify as a parameter to the /v3/{journal}/pull call, which is analogous to the V1 and V2 GetUpdates call.

The V3 pull call works very similarly. However, unlike the V1 and V2 GetUpdates call, it does not attempt to collapse multiple updates to the same address into a single update (some users of GetUpdates found this behaviour quite obscure). V3's pull simple lists every update separately.

Pull can be now be used with any journal, e.g. for roads:

• /v3/roads/pull?include=name