The CAF API requires a client to provide an API key upon each request. If the API key provided does not match one of those distributed then the call will fail.

The API documentation can be accessed here.
 

New In APIv3

 

• Address matching API: Three new calls providing address matching using Bayesian heuristics
• X/Y and Latitude/Longitude: Added geographic locations of addresses to the ‘Address’ object
• Classifications: Support for AVU user to assign vocabulary terms to addresses; API support for restricting searches to match addresses with a given vocabulary term; API call added for retrieving the term from a specific vocabulary which has been assigned to an address
• Delivery point ID invariance: Enforce invariance of delivery point IDs (or UPRNs) between addresses and their successors – this allows client systems to safely store delivery point IDs instead of CAF IDs as an alternative method of integration
• Retrieval of addresses by delivery point ID: A new call has been added to allow addresses to be retrieved by delivery point ID
• Event type field: New event type field to record whether address updates represent the construction or demolition of a property – useful information for tracking changes in the property stock
• General API simplification: New versions of the existing API calls have been created which are substantially simpler to use
• Removal of unused legacy features: A number of legacy features which are not being used by existing client systems have been removed
• API calls for exporting the entire address set: Two new calls have been added to allow external systems to export the entire set of addresses in order to provide better support for legacy systems which require the use of a static address file for their address lookups
• Simplified authentication: Authentication is instead done through an API key which is provided to you with your CAF license. For old API users this is in the format of <user>:<pass>

 

General CAF Concepts

 

Address Validation Unit (AVU)

The AVU is the person, group, or organisation whom maintains the CAF database.

CAF ID

Each new address or new revision of an existing address in the CAF will receive a sequentially assigned CAF ID. The CAF ID therefore represents the state of the CAF immediately after that update was accepted.

When an address is revised, a new CAF ID is allocated for the revision and this CAF ID becomes the successor of the previous version. CAF IDs may be merged in which case two CAF IDs will have the same successor.
Client databases will store CAF IDs in their local tables to represent addresses. When an address is updated, the client database will receive a new CAF ID and the new address fields to replace the details on record.

Delivery Point ID

A delivery point ID is a unique number to identify an address. The delivery point ID does not change from one version of an address to another. API calls are provided to retrieve addresses by delivery point ID, which means the delivery point ID can be used by systems instead of the CAF ID in order to store the link to a CAF address.

Candidate and Accepted Addresses

A ‘candidate’ address is an address which has been submitted by a client to the CAF. It may be a new address or a proposed amendment to an existing address. In the latter case, the client will specify what address is being amended. Candidate addresses will subsequently be accepted or discarded by the AVU. If a candidate is accepted, a new ‘accepted’ address is created, with a further new CAF ID created to represent it.

Current Address

The ‘current’ address for a given CAF ID is the last accepted address reached by following the chain of successors starting from that CAF ID.

Address Succession

Internally the CAF tracks addresses using links between CAF IDs:

• Each address (either candidate or accepted) has a link to its successor. New candidates and current addresses to not have successors.
• Each candidate address also has a link to its predecessor only if it is a proposed update as opposed to a new address.

 

A CAF address lifecycle is illustrated in the following diagram which demonstrates various update scenarios.