Resources and purchasing from their catalog

Every dataset in our Catalog displays which type of resource a variable is avaiable for by looking at the right-hand side of each entry. The following example shows how to retrieve a property address key for each resource type.

The WhenFresh API allows purchasing from any of those locations in the UK:

• PostalAddress using a Property AddressKey
• Ordnance Survey Spatial address using a UPRN

For each of these resources, you can get a Resource Catalog URI you can purchase variables from using our address search API, or using one of the URI templates described below. They are guaranteed not to change over time.

Property Address Key

Resource catalogs for Postal Addresses use a Property Address Key, as described in Identifying an address.

Once you retrieve the key, you can make purchase against the Postal Address catalog by using the following URI template:

https://api.whenfresh.com/world/GB/addresses/{propertyAddressKey}/catalog

Ordnance Survey Spatial Address

Ordnance survey's spatial addresses expose resource catalogs at the following URI template:

https://api.whenfresh.com/world/GB/spatial/addresses/{osUprn}/catalog

Purchasing Variables from a ResourceCatalog

The following request demonstrates how to purchase variables for a postal address. It requires an address's catalog link obtained (for example) by Getting Postal Addresses for a Postcode.

POST /world/GB/addresses/8e05p%C2%B70/catalog HTTP/1.1
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/ld+json
Accept: application/ld+json

{
  "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
  "@type": "PurchaseVariableAction",
  "variables": [
    "https://api.whenfresh.com/vars/Zoopla/Property Attribute#Dwelling/Rooms/Bedrooms/Bedroom Count"
  ]
}

Variable identifiers can be found and copied from the Catalog Bowser.

The list of purchased variables is returned as JSON Variable resources:

HTTP/1.1 200 OK
Content-Type: application/ld+json

{
    "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
    "@type": "hydra:Collection",
    "manages": {
        "property": "rdf:type",
        "object": "Datum"
    },
    "member": [
        {
            "@type": "https://api.whenfresh.com/ontologies/Dwelling/Rooms#Bedrooms/Bedroom Count",
            "price": {
                "value": 1,
                "currency": "GBP"
            },
            "variable": {
                "@type": "Variable",
                "@id": "https://api.whenfresh.com/vars/Zoopla/Property Attribute#Dwelling/Rooms/Bedrooms/Bedroom Count"
            },
            "value": "2"
        }
    ],
    "totalItems": 1
}

Purchasing Functions

A function is a special kind of variable. It still has a type and an identifier, but it also takes inputs, and the response is usually the result of a calculation.

To use one, you need to add the input parameters, as documented in the Catalog Browser, to a special form of the PurchaseVariableAction.

The following example demonstrates a theoretical function, https://api.whenresh.com/vars/BritishBank/CanLoan, taking a parameter, requestedLoanAmount.

POST /world/GB/addresses/8e05p%C2%B70/catalog HTTP/1.1
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/ld+json
Accept: application/ld+json

{
  "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
  "@type": "PurchaseVariableAction",
  "variables": [
    { 
      "@id": "https://api.whenresh.com/vars/BritishBank/CanLoan",
      "requestedLoanAmount": 3500
    }
  ]
}

The exact variable identifier and the parameters to pass it will be provided to you by the WhenFresh team, so do not be alarmed if the example doesn't return if you try it with your developer account.

The response will be the same as you would expect from any other variable, as documented elsewhere.

Please note that there may be multiple parameters, they are passed by name directly.

Do also note that it is entirely possible, and encouraged, to mix and match functions and variables in the same purchase call.

For example, combining the two previous samples, your request could look like this:

POST /world/GB/addresses/8e05p%C2%B70/catalog HTTP/1.1
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/ld+json
Accept: application/ld+json

{
  "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
  "@type": "PurchaseVariableAction",
  "variables": [
    "https://api.whenfresh.com/vars/Zoopla/Property Attribute#Dwelling/Rooms/Bedrooms/Bedroom Count",
    { 
      "@id": "https://api.whenresh.com/vars/BritishBank/CanLoan",
      "requestedLoanAmount": 3500
    }
  ]
}

See sample Postman Collections to assist you in getting started with your integration.