Browsing the Catalog

A Catalog is a collection of variables that may be purchased via the API for a particular entity. In the case of our "Behind the Bricks" example, a Postal Address would have a catalog of purchasable variables with variable types such as Bedroom Count and Property Flood Risk Score.

Variable Type Categories

The Catalog Browser allows you to browse variable types that are categorized into ontologies defined by schemas provided by WhenFresh or third parties. In the "Behind the Bricks" context, the third parties include the Valuation Office Agency (who define council tax bands) and Cadw (who define variables for listed buildings):

Each variable type defines a variable's key characteristics including the underlying data type, allowed values and indicative price range.

Variable Provenances

The same type of variable could be provided by multiple providers, and the variable's provenance is used to distinguish the desired source of the data (in this case WhenFresh or Zoopla):

Put simply, you can obtain a value for this variable from either WhenFresh or Zoopla, and the Variable Identifier (see above) is the unique key to purchase the provenanced variable via the API.

Variable Prices

Whereas the variable type defines a min-max price range for the variable, the actual price to purchase the variable depends on the provider and the entity to which it relates. For example, the price of the Bedroom Count variable might be different for different postal addresses.

Note

In the preceding descriptions, a schema provider such as Cadw (who provide variable type schemas) is not the same as a variable provider such as Zoopla (who provide values for the purchased variables).

Resource Catalogs

Variables are purchasable from specific Resource Catalogs.

You will know which Resource Catalog a variable is purchasable from by looking in the top right of the variable pane in the Catalog Browser.

The currently available Resource Catalogs, along with their uri templates, are as follows:

PostalAddress

https://api.whenfresh.com/world/gb/addresses/<resource-identifier>/catalog

For the PostalAddress Resource Catalog the resource identifier will be a WhenFresh Property Address Key (e.g. 6c09o·0).

Postcode

https://api.whenfresh.com/world/gb/postcodes/<resource-identifier>/catalog

For the Postcode Resource Catalog the resource identifier will be a Postcode Unit (e.g. HD5 8JL).

SpatialAddress

https://api.whenfresh.com/world/gb/spatial/addresses/<resource-identifier>/catalog

For the SpatialAddress Resource Catalog the resource identifier will be an OS UPRN (e.g. 83068271).

Title

https://api.whenfresh.com/world/gb/titles/<resource-identifier>/catalog

For the Title Resource Catalog the resource identifier can be either a Land Registry or Registers od Scotland Title Number (e.g. YK29451).

EnglandAndWalesTitle

https://api.whenfresh.com/world/gb-eaw/titles/<resource-identifier>/catalog

For the EnglandAndWalesTitle Resource Catalog the resource identifier will be a Land Registry Title Number (e.g. YK29451).