1 Extracting data using the Fingertips API

The Fingertips API was published recently at this link. At first sight it looks rather complex so we are developing scripts in R to facilitate extracting data via the API. The data and meta data are all available in JSON format which is easily handled by R using packages like jsonlite.

1.1 Extracting ages

Lets start with a simple example - extracting the age groups contained within the Fingertips tool. All the calls to the API are of the form https://fingertips.phe.org.uk/api/ so to read the data we simply need to pass the URL to the fromJSON function. So for example the following code reads the IDs and names for all the age bands used in Fingertips.

if(!require(jsonlite))install.packages("jsonlite")
Loading required package: jsonlite
library(jsonlite)
ages <- fromJSON("https://fingertips.phe.org.uk/api/ages")
head(ages, 20)

We can extract the gender codes in a similar fashion

sexes <- fromJSON("https://fingertips.phe.org.uk/api/sexes")
head(sexes)

And see what profiles are contained in the tool

profiles <- fromJSON("https://fingertips.phe.org.uk/api/profiles")
names(profiles)
[1] "Id"       "Name"     "Key"      "GroupIds"
head(profiles, 20)

We can see that within each profiles there are GroupIDs which reflect profile subdomains. For examples, within the PHOF tool which is profile 19, there are 6 domains, or 8 in the Common Mental Disorders Profile.

1.2 Getting domain names

Domain names can be extracted as follows:

## for mental health profiles
mh <- fromJSON("https://fingertips.phe.org.uk/api/profile?profile_id=40")
mhdomains <- as.vector(mh$GroupIds)
url <- paste0("https://fingertips.phe.org.uk/api/group_metadata?group_ids=", paste0(mhdomains, collapse = "%2C"))
url  
[1] "https://fingertips.phe.org.uk/api/group_metadata?group_ids=8000026%2C8000041%2C8000042%2C8000043%2C8000044%2C1938132720%2C1938132954%2C1938132955"
mhdon <- fromJSON(url)
mhdon

1.2.1 Getting area names

Follows a similar pattern.

## First we need to extract area types
areatype <- fromJSON("https://fingertips.phe.org.uk/api/area_types")
areatype
## for LADs Id = 1
areanames <- fromJSON("https://fingertips.phe.org.uk/api/areas/by_area_type?area_type_id=1")
areanames
## First we need to extract area types
subject <- "alcohol"
url = paste0("https://fingertips.phe.org.uk/api/indicator_search?search_text=", subject)
## for LADs Id = 1
indicators <- fromJSON(url)
indicators
named list()
LS0tCnRpdGxlOiAiRmluZ2VydGlwcyBBUEk6IGRyYWZ0IgpvdXRwdXQ6IAogIGh0bWxfbm90ZWJvb2s6IAogICAgbnVtYmVyX3NlY3Rpb25zOiB5ZXMKICAgIHRvYzogeWVzCi0tLQoKIyBFeHRyYWN0aW5nIGRhdGEgdXNpbmcgdGhlIEZpbmdlcnRpcHMgQVBJIAoKVGhlIEZpbmdlcnRpcHMgQVBJIHdhcyBwdWJsaXNoZWQgcmVjZW50bHkgYXQgW3RoaXMgbGlua10oImh0dHBzOi8vZmluZ2VydGlwcy5waGUub3JnLnVrL2FwaSIpLiBBdCBmaXJzdCBzaWdodCBpdCBsb29rcyByYXRoZXIgY29tcGxleCBzbyB3ZSBhcmUgZGV2ZWxvcGluZyBzY3JpcHRzIGluIFIgdG8gZmFjaWxpdGF0ZSBleHRyYWN0aW5nIGRhdGEgdmlhIHRoZSBBUEkuIFRoZSBkYXRhIGFuZCBtZXRhIGRhdGEgYXJlIGFsbCBhdmFpbGFibGUgaW4gSlNPTiBmb3JtYXQgd2hpY2ggaXMgZWFzaWx5IGhhbmRsZWQgYnkgUiB1c2luZyBwYWNrYWdlcyBsaWtlIGBqc29ubGl0ZWAuCgojIyBFeHRyYWN0aW5nIGFnZXMKCkxldHMgc3RhcnQgd2l0aCBhIHNpbXBsZSBleGFtcGxlIC0gZXh0cmFjdGluZyB0aGUgYWdlIGdyb3VwcyBjb250YWluZWQgd2l0aGluIHRoZSBGaW5nZXJ0aXBzIHRvb2wuIEFsbCB0aGUgY2FsbHMgdG8gdGhlIEFQSSBhcmUgb2YgdGhlIGZvcm0gaHR0cHM6Ly9maW5nZXJ0aXBzLnBoZS5vcmcudWsvYXBpLyBzbyB0byByZWFkIHRoZSBkYXRhIHdlIHNpbXBseSBuZWVkIHRvIHBhc3MgdGhlIFVSTCB0byB0aGUgYGZyb21KU09OYCBmdW5jdGlvbi4gU28gZm9yIGV4YW1wbGUgdGhlIGZvbGxvd2luZyBjb2RlIHJlYWRzIHRoZSBJRHMgYW5kIG5hbWVzIGZvciBhbGwgdGhlIGFnZSBiYW5kcyB1c2VkIGluIEZpbmdlcnRpcHMuCgpgYGB7ciwgZWNobz1UUlVFfQppZighcmVxdWlyZShqc29ubGl0ZSkpaW5zdGFsbC5wYWNrYWdlcygianNvbmxpdGUiKQpsaWJyYXJ5KGpzb25saXRlKQoKYWdlcyA8LSBmcm9tSlNPTigiaHR0cHM6Ly9maW5nZXJ0aXBzLnBoZS5vcmcudWsvYXBpL2FnZXMiKQoKaGVhZChhZ2VzLCAyMCkKYGBgCgpXZSBjYW4gZXh0cmFjdCB0aGUgZ2VuZGVyIGNvZGVzIGluIGEgc2ltaWxhciBmYXNoaW9uCmBgYHtyfQpzZXhlcyA8LSBmcm9tSlNPTigiaHR0cHM6Ly9maW5nZXJ0aXBzLnBoZS5vcmcudWsvYXBpL3NleGVzIikKCmhlYWQoc2V4ZXMpCmBgYAoKQW5kIHNlZSB3aGF0IHByb2ZpbGVzIGFyZSBjb250YWluZWQgaW4gdGhlIHRvb2wKYGBge3J9CnByb2ZpbGVzIDwtIGZyb21KU09OKCJodHRwczovL2ZpbmdlcnRpcHMucGhlLm9yZy51ay9hcGkvcHJvZmlsZXMiKQoKbmFtZXMocHJvZmlsZXMpCgpoZWFkKHByb2ZpbGVzLCAyMCkKCmBgYAoKV2UgY2FuIHNlZSB0aGF0IHdpdGhpbiBlYWNoIHByb2ZpbGVzIHRoZXJlIGFyZSBHcm91cElEcyB3aGljaCByZWZsZWN0IHByb2ZpbGUgc3ViZG9tYWlucy4gRm9yIGV4YW1wbGVzLCB3aXRoaW4gdGhlIFBIT0YgdG9vbCB3aGljaCBpcyBwcm9maWxlIDE5LCB0aGVyZSBhcmUgYHIgdW5saXN0KGxlbmd0aChmaWx0ZXIocHJvZmlsZXMsIElkID09IDE5KSRHcm91cElkc1tbMV1dKSlgIGRvbWFpbnMsIG9yIGByIHVubGlzdChsZW5ndGgoZmlsdGVyKHByb2ZpbGVzLCBJZCA9PSA0MCkkR3JvdXBJZHNbWzFdXSkpYCBpbiB0aGUgQ29tbW9uIE1lbnRhbCBEaXNvcmRlcnMgUHJvZmlsZS4KCiMjIEdldHRpbmcgZG9tYWluIG5hbWVzCgpEb21haW4gbmFtZXMgY2FuIGJlIGV4dHJhY3RlZCBhcyBmb2xsb3dzOiAgCgpgYGB7ciwgZWNobz1UUlVFfQoKIyMgZm9yIG1lbnRhbCBoZWFsdGggcHJvZmlsZXMKbWggPC0gZnJvbUpTT04oImh0dHBzOi8vZmluZ2VydGlwcy5waGUub3JnLnVrL2FwaS9wcm9maWxlP3Byb2ZpbGVfaWQ9NDAiKQoKbWhkb21haW5zIDwtIGFzLnZlY3RvcihtaCRHcm91cElkcykKCnVybCA8LSBwYXN0ZTAoImh0dHBzOi8vZmluZ2VydGlwcy5waGUub3JnLnVrL2FwaS9ncm91cF9tZXRhZGF0YT9ncm91cF9pZHM9IiwgcGFzdGUwKG1oZG9tYWlucywgY29sbGFwc2UgPSAiJTJDIikpCgp1cmwgIAoKbWhkb24gPC0gZnJvbUpTT04odXJsKQptaGRvbgoKYGBgCgojIyMgR2V0dGluZyBhcmVhIG5hbWVzCgpGb2xsb3dzIGEgc2ltaWxhciBwYXR0ZXJuLgoKYGBge3IsIGVjaG89VFJVRX0KCiMjIEZpcnN0IHdlIG5lZWQgdG8gZXh0cmFjdCBhcmVhIHR5cGVzCgphcmVhdHlwZSA8LSBmcm9tSlNPTigiaHR0cHM6Ly9maW5nZXJ0aXBzLnBoZS5vcmcudWsvYXBpL2FyZWFfdHlwZXMiKQphcmVhdHlwZQoKIyMgZm9yIExBRHMgSWQgPSAxCgphcmVhbmFtZXMgPC0gZnJvbUpTT04oImh0dHBzOi8vZmluZ2VydGlwcy5waGUub3JnLnVrL2FwaS9hcmVhcy9ieV9hcmVhX3R5cGU/YXJlYV90eXBlX2lkPTEiKQoKYXJlYW5hbWVzCgpgYGAKCmBgYHtyLCBlY2hvPVRSVUV9CgojIyBGaXJzdCB3ZSBuZWVkIHRvIGV4dHJhY3QgYXJlYSB0eXBlcwpzdWJqZWN0IDwtICJhbGNvaG9sIgp1cmwgPSBwYXN0ZTAoImh0dHBzOi8vZmluZ2VydGlwcy5waGUub3JnLnVrL2FwaS9pbmRpY2F0b3Jfc2VhcmNoP3NlYXJjaF90ZXh0PSIsIHN1YmplY3QpCgojIyBmb3IgTEFEcyBJZCA9IDEKCmluZGljYXRvcnMgPC0gZnJvbUpTT04odXJsKQoKaW5kaWNhdG9ycwoKYGBg