README.md
In Terrabrasilis/terrabrasilisAnalyticsAPI: The R client for TerraBrasilis analytics API of thematic maps
R Client Terrabrasilis Analytics API
terrabrasilisAnalyticsAPI is an R client package for Terrabrasilis Analytics API.
Getting started
Installing and loading terrabrasilisAnalyticsAPI package in R
devtools::install_github("terrabrasilis/terrabrasilisAnalyticsAPI") # github group name is terrabrasilis
library(terrabrasilisAnalyticsAPI) # R package name is terrabrasilisAnalyticsAPI
Initialize Terrabrasilis Analytics API path variable
apiPath <- "http://terrabrasilis.dpi.inpe.br/dashboard/api/v1/redis-cli/"
Define calls for application identifiers listing. From that information, it is possible then to make specific requests to other API end-points.
appIdentifier <- list_datasets(apiPath)
appIdentifier
[1] "prodes_cerrado" "prodes_amazon" "prodes_legal_amazon"
With that in mind, let's create a prodesCerrado variable.
prodesCerrado <- appIdentifier[1]
prodesCerrado
[1] "prodes_cerrado"
The first question that reminds us to ask to the API is: which periods do Prodes Cerrado contains?
periods <- list_periods(apiPath, prodesCerrado)
periods
periods
# A tibble: 15 x 6
startDate.year startDate.month startDate.day endDate.year endDate.month endDate.day
<int> <int> <int> <int> <int> <int>
1 2000 8 1 2002 7 31
2 2002 8 1 2004 7 31
3 2004 8 1 2006 7 31
4 2006 8 1 2008 7 31
5 2008 8 1 2010 7 31
6 2010 8 1 2012 7 31
7 2012 8 1 2013 7 31
8 2013 8 1 2014 7 31
9 2014 8 1 2015 7 31
10 2015 8 1 2016 7 31
11 2016 8 1 2017 7 31
12 2017 8 1 2018 7 31
13 2018 8 1 2019 7 31
14 1987 8 1 2000 7 31
15 2019 8 1 2020 7 31
Users can also ask to the API, for example, which classes do PRODES Cerrado contains?
classes <- list_classes(apiPath, prodesCerrado)
classes
In this case, it is just one class designating deforestation label. Other thematic mapping projects, however, would contain more than one class or even the same class name.
# A tibble: 1 x 3
id name description
<int> <chr> <chr>
1 1 deforestation It is the process of complete and permanent disappearance of forests
Besides responding which classes and periods, users might ask which local of interests (lois) as states, municipalities, conservation units, indigeneous areas, and Landsat Path/Row, the API provides.
locals <- list_locals(apiPath, prodesCerrado)
locals
# A tibble: 4 x 2
gid name
<int> <chr>
1 1 uf
2 2 mun
3 3 consunit
4 4 indi
Nevertheless, locals are not considered the final granularity since each state, municipality, conservation unit, indigeneous areas, and Landsat Path/Row also contain small-scale local of interests.
localOfInterest <- list_local_of_interests(apiPath, prodesCerrado)
localOfInterest[402:412,]
# A tibble: 11 x 4
gid loiname codibge loi
<int> <chr> <int> <dbl>
1 2850 CRIXÁS_GOIÁS 5206404 2
2 2468 ADELÂNDIA_GOIÁS 5200159 2
3 1798 DOIS IRMÃOS DO TOCANTINS_TOCANTINS 1707207 2
4 2429 SANTA LÚCIA_SÃO PAULO 3546900 2
5 1489 PONTO CHIQUE_MINAS GERAIS 3152131 2
6 2335 ASSIS_SÃO PAULO 3504008 2
7 1989 ROMARIA_MINAS GERAIS 3156403 2
8 1560 SERRA DO SALITRE_MINAS GERAIS 3166808 2
9 1587 CAMPOS NOVOS PAULISTA_SÃO PAULO 3509809 2
10 2574 PROFESSOR JAMIL_GOIÁS 5218391 2
11 1898 SANTA RITA_MARANHÃO 2110203 2
Users are able to filter loinames by one specific loi such as UF.
loiUF = dplyr::filter(locals, grepl("uf", name))$gid
loinamesByLoi <- list_localOfInterestByLocal(apiPath, prodesCerrado, loiUF)
loinamesByLoi
# A tibble: 13 x 2
gid loiname
<int> <chr>
1 1185 BAHIA
2 1186 DISTRITO FEDERAL
3 1187 GOIÁS
4 1188 MARANHÃO
5 1189 MATO GROSSO
6 1190 MATO GROSSO DO SUL
7 1191 MINAS GERAIS
8 1192 PARÁ
9 1193 PIAUÍ
10 1194 SÃO PAULO
11 1195 TOCANTINS
12 1196 PARANÁ
13 1197 RONDÔNIA
In order to fit data into governmental needs, we also considered filters for each data recognized that as type in the data API call.
filters <- list_filters(apiPath, prodesCerrado)
filters
# A tibble: 2 x 2
id type
<int> <chr>
1 1 fid_area >= 0.0625
2 2 fid_area >= 0.01
All this data is used to gather specific thematic map area values produced by government agencies such as the National Institute for Space Research. In this example, users are able to acquire data by loiname, that is, the function accepts as parameters, the class name and loiname gid as well.
data <- get_dataByLocalOfInterest(apiPath,
prodesCerrado,
classes$name,
loinamesByLoi[1,]$gid)
data
name clazz startDate.year startDate.month startDate.day endDate.year endDate.month endDate.day loi loiname type area
1 PRODES CERRADO deforestation 2000 8 1 2002 7 31 1 1185 1 4308.7598
2 PRODES CERRADO deforestation 2000 8 1 2002 7 31 1 1185 2 4570.1642
3 PRODES CERRADO deforestation 2002 8 1 2004 7 31 1 1185 1 5075.4283
4 PRODES CERRADO deforestation 2002 8 1 2004 7 31 1 1185 2 5400.1104
5 PRODES CERRADO deforestation 2004 8 1 2006 7 31 1 1185 1 3305.8449
6 PRODES CERRADO deforestation 2004 8 1 2006 7 31 1 1185 2 3599.6725
7 PRODES CERRADO deforestation 2006 8 1 2008 7 31 1 1185 1 3635.5140
8 PRODES CERRADO deforestation 2006 8 1 2008 7 31 1 1185 2 4020.0215
9 PRODES CERRADO deforestation 2008 8 1 2010 7 31 1 1185 1 2177.6916
10 PRODES CERRADO deforestation 2008 8 1 2010 7 31 1 1185 2 2417.5602
11 PRODES CERRADO deforestation 2010 8 1 2012 7 31 1 1185 1 2922.7548
12 PRODES CERRADO deforestation 2010 8 1 2012 7 31 1 1185 2 3047.2696
13 PRODES CERRADO deforestation 2012 8 1 2013 7 31 1 1185 1 1330.3253
14 PRODES CERRADO deforestation 2012 8 1 2013 7 31 1 1185 2 1562.1050
15 PRODES CERRADO deforestation 2013 8 1 2014 7 31 1 1185 1 972.4348
16 PRODES CERRADO deforestation 2013 8 1 2014 7 31 1 1185 2 1078.8954
17 PRODES CERRADO deforestation 2014 8 1 2015 7 31 1 1185 1 1205.3126
18 PRODES CERRADO deforestation 2014 8 1 2015 7 31 1 1185 2 1334.5169
19 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 1 714.1984
20 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 2 782.1150
21 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 1 728.0815
22 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 2 783.0249
23 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 1 646.8232
24 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 2 696.9687
25 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 1 780.0096
26 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 2 832.3697
27 PRODES CERRADO deforestation 1987 8 1 2000 7 31 1 1185 1 29577.0078
28 PRODES CERRADO deforestation 1987 8 1 2000 7 31 1 1185 2 29781.4093
29 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 1 834.6321
30 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 2 919.1458
The same query can be performed using get data by parameters function. In this case, users pass also as parameters a start and end date. Unlikely the previous call, users will not receive all the available timeline as soon as they really desire.
data <- get_dataByParameters(apiPath,
prodesCerrado,
classes$name,
loinamesByLoi[1,]$gid,
"2015-01-01",
"2021-01-01")
data
name clazz startDate.year startDate.month startDate.day endDate.year endDate.month endDate.day loi loiname type area
1 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 1 714.1984
2 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 2 782.1150
3 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 1 728.0815
4 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 2 783.0249
5 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 1 646.8232
6 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 2 696.9687
7 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 1 780.0096
8 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 2 832.3697
9 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 1 834.6321
10 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 2 919.1458
In this example, users are able to acquire data by loiname (SÃO PAULO) and dates, we also considered filters in the data.
Compare with SÃO PAULO http://www.terrabrasilis.dpi.inpe.br/app/dashboard/deforestation/biomes/cerrado/increments
data <- get_dataByParameters(apiPath, prodesCerrado, classes$name, loinamesByLoi[10,]$gid, "2015-01-01", "2020-12-31") %>%
dplyr::filter(.,type==2) %>%
dplyr::filter(.,endDate.year!=2000) %>%
dplyr::select(name, clazz, startDate.year, endDate.year, area)
data
name clazz startDate.year endDate.year area
1 PRODES CERRADO deforestation 2015 2016 3.275794
2 PRODES CERRADO deforestation 2016 2017 3.706419
3 PRODES CERRADO deforestation 2017 2018 14.607230
4 PRODES CERRADO deforestation 2018 2019 6.113063
5 PRODES CERRADO deforestation 2019 2020 8.259873
Plot result
library(ggplot2)
ggplot(data, aes(x=as.factor(endDate.year), y=area, fill=clazz)) +
geom_text(aes(label=as.numeric(round(data$area, 2))), vjust=-0.5, hjust=0.3, size = 4) +
geom_bar(stat = "identity", width = 0.8, fill = "#008080") +
scale_x_discrete("Year", labels = as.character(data$endDate.year), breaks = data$endDate.year) +
theme(axis.text.x = element_text(angle = 45, vjust = 0.5)) +
labs(colour = "Date") + labs(x = "Years") + labs(y = "Areas (km²)") +
labs(title = loinamesByLoi[10,]$loiname) + labs(fill = "class")
Fig. 1. Deforestation increments - Cerrado biome, São Paulo State
References
Assis, L. F. F. G. A.; Ferreira, K. R.; Vinhas, L.; Maurano, L.; Almeida, C. A., Nascimento, J. R., Carvalho, A. F. A.; Camargo, C.; Maciel, A. M. TerraBrasilis: A Spatial Data Infrastructure for Disseminating Deforestation Data from Brazil. In Proceeding of the XIX Remote Sensing Brazilian Symposium, 2019.
Reporting Bugs
Any problem should be reported to terrabrasilis@inpe.br.
Terrabrasilis/terrabrasilisAnalyticsAPI documentation built on April 20, 2021, 2:11 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
R Client Terrabrasilis Analytics API
terrabrasilisAnalyticsAPI is an R client package for Terrabrasilis Analytics API.
Getting started
Installing and loading terrabrasilisAnalyticsAPI package in R
devtools::install_github("terrabrasilis/terrabrasilisAnalyticsAPI") # github group name is terrabrasilis
library(terrabrasilisAnalyticsAPI) # R package name is terrabrasilisAnalyticsAPI
Initialize Terrabrasilis Analytics API path variable
apiPath <- "http://terrabrasilis.dpi.inpe.br/dashboard/api/v1/redis-cli/"
Define calls for application identifiers listing. From that information, it is possible then to make specific requests to other API end-points.
appIdentifier <- list_datasets(apiPath)
appIdentifier
[1] "prodes_cerrado" "prodes_amazon" "prodes_legal_amazon"
With that in mind, let's create a prodesCerrado variable.
prodesCerrado <- appIdentifier[1]
prodesCerrado
[1] "prodes_cerrado"
The first question that reminds us to ask to the API is: which periods do Prodes Cerrado contains?
periods <- list_periods(apiPath, prodesCerrado)
periods
periods
# A tibble: 15 x 6
startDate.year startDate.month startDate.day endDate.year endDate.month endDate.day
<int> <int> <int> <int> <int> <int>
1 2000 8 1 2002 7 31
2 2002 8 1 2004 7 31
3 2004 8 1 2006 7 31
4 2006 8 1 2008 7 31
5 2008 8 1 2010 7 31
6 2010 8 1 2012 7 31
7 2012 8 1 2013 7 31
8 2013 8 1 2014 7 31
9 2014 8 1 2015 7 31
10 2015 8 1 2016 7 31
11 2016 8 1 2017 7 31
12 2017 8 1 2018 7 31
13 2018 8 1 2019 7 31
14 1987 8 1 2000 7 31
15 2019 8 1 2020 7 31
Users can also ask to the API, for example, which classes do PRODES Cerrado contains?
classes <- list_classes(apiPath, prodesCerrado)
classes
In this case, it is just one class designating deforestation label. Other thematic mapping projects, however, would contain more than one class or even the same class name.
# A tibble: 1 x 3
id name description
<int> <chr> <chr>
1 1 deforestation It is the process of complete and permanent disappearance of forests
Besides responding which classes and periods, users might ask which local of interests (lois) as states, municipalities, conservation units, indigeneous areas, and Landsat Path/Row, the API provides.
locals <- list_locals(apiPath, prodesCerrado)
locals
# A tibble: 4 x 2
gid name
<int> <chr>
1 1 uf
2 2 mun
3 3 consunit
4 4 indi
Nevertheless, locals are not considered the final granularity since each state, municipality, conservation unit, indigeneous areas, and Landsat Path/Row also contain small-scale local of interests.
localOfInterest <- list_local_of_interests(apiPath, prodesCerrado)
localOfInterest[402:412,]
# A tibble: 11 x 4
gid loiname codibge loi
<int> <chr> <int> <dbl>
1 2850 CRIXÁS_GOIÁS 5206404 2
2 2468 ADELÂNDIA_GOIÁS 5200159 2
3 1798 DOIS IRMÃOS DO TOCANTINS_TOCANTINS 1707207 2
4 2429 SANTA LÚCIA_SÃO PAULO 3546900 2
5 1489 PONTO CHIQUE_MINAS GERAIS 3152131 2
6 2335 ASSIS_SÃO PAULO 3504008 2
7 1989 ROMARIA_MINAS GERAIS 3156403 2
8 1560 SERRA DO SALITRE_MINAS GERAIS 3166808 2
9 1587 CAMPOS NOVOS PAULISTA_SÃO PAULO 3509809 2
10 2574 PROFESSOR JAMIL_GOIÁS 5218391 2
11 1898 SANTA RITA_MARANHÃO 2110203 2
Users are able to filter loinames by one specific loi such as UF.
loiUF = dplyr::filter(locals, grepl("uf", name))$gid
loinamesByLoi <- list_localOfInterestByLocal(apiPath, prodesCerrado, loiUF)
loinamesByLoi
# A tibble: 13 x 2
gid loiname
<int> <chr>
1 1185 BAHIA
2 1186 DISTRITO FEDERAL
3 1187 GOIÁS
4 1188 MARANHÃO
5 1189 MATO GROSSO
6 1190 MATO GROSSO DO SUL
7 1191 MINAS GERAIS
8 1192 PARÁ
9 1193 PIAUÍ
10 1194 SÃO PAULO
11 1195 TOCANTINS
12 1196 PARANÁ
13 1197 RONDÔNIA
In order to fit data into governmental needs, we also considered filters for each data recognized that as type in the data API call.
filters <- list_filters(apiPath, prodesCerrado)
filters
# A tibble: 2 x 2
id type
<int> <chr>
1 1 fid_area >= 0.0625
2 2 fid_area >= 0.01
All this data is used to gather specific thematic map area values produced by government agencies such as the National Institute for Space Research. In this example, users are able to acquire data by loiname, that is, the function accepts as parameters, the class name and loiname gid as well.
data <- get_dataByLocalOfInterest(apiPath,
prodesCerrado,
classes$name,
loinamesByLoi[1,]$gid)
data
name clazz startDate.year startDate.month startDate.day endDate.year endDate.month endDate.day loi loiname type area
1 PRODES CERRADO deforestation 2000 8 1 2002 7 31 1 1185 1 4308.7598
2 PRODES CERRADO deforestation 2000 8 1 2002 7 31 1 1185 2 4570.1642
3 PRODES CERRADO deforestation 2002 8 1 2004 7 31 1 1185 1 5075.4283
4 PRODES CERRADO deforestation 2002 8 1 2004 7 31 1 1185 2 5400.1104
5 PRODES CERRADO deforestation 2004 8 1 2006 7 31 1 1185 1 3305.8449
6 PRODES CERRADO deforestation 2004 8 1 2006 7 31 1 1185 2 3599.6725
7 PRODES CERRADO deforestation 2006 8 1 2008 7 31 1 1185 1 3635.5140
8 PRODES CERRADO deforestation 2006 8 1 2008 7 31 1 1185 2 4020.0215
9 PRODES CERRADO deforestation 2008 8 1 2010 7 31 1 1185 1 2177.6916
10 PRODES CERRADO deforestation 2008 8 1 2010 7 31 1 1185 2 2417.5602
11 PRODES CERRADO deforestation 2010 8 1 2012 7 31 1 1185 1 2922.7548
12 PRODES CERRADO deforestation 2010 8 1 2012 7 31 1 1185 2 3047.2696
13 PRODES CERRADO deforestation 2012 8 1 2013 7 31 1 1185 1 1330.3253
14 PRODES CERRADO deforestation 2012 8 1 2013 7 31 1 1185 2 1562.1050
15 PRODES CERRADO deforestation 2013 8 1 2014 7 31 1 1185 1 972.4348
16 PRODES CERRADO deforestation 2013 8 1 2014 7 31 1 1185 2 1078.8954
17 PRODES CERRADO deforestation 2014 8 1 2015 7 31 1 1185 1 1205.3126
18 PRODES CERRADO deforestation 2014 8 1 2015 7 31 1 1185 2 1334.5169
19 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 1 714.1984
20 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 2 782.1150
21 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 1 728.0815
22 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 2 783.0249
23 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 1 646.8232
24 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 2 696.9687
25 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 1 780.0096
26 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 2 832.3697
27 PRODES CERRADO deforestation 1987 8 1 2000 7 31 1 1185 1 29577.0078
28 PRODES CERRADO deforestation 1987 8 1 2000 7 31 1 1185 2 29781.4093
29 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 1 834.6321
30 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 2 919.1458
The same query can be performed using get data by parameters function. In this case, users pass also as parameters a start and end date. Unlikely the previous call, users will not receive all the available timeline as soon as they really desire.
data <- get_dataByParameters(apiPath,
prodesCerrado,
classes$name,
loinamesByLoi[1,]$gid,
"2015-01-01",
"2021-01-01")
data
name clazz startDate.year startDate.month startDate.day endDate.year endDate.month endDate.day loi loiname type area
1 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 1 714.1984
2 PRODES CERRADO deforestation 2015 8 1 2016 7 31 1 1185 2 782.1150
3 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 1 728.0815
4 PRODES CERRADO deforestation 2016 8 1 2017 7 31 1 1185 2 783.0249
5 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 1 646.8232
6 PRODES CERRADO deforestation 2017 8 1 2018 7 31 1 1185 2 696.9687
7 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 1 780.0096
8 PRODES CERRADO deforestation 2018 8 1 2019 7 31 1 1185 2 832.3697
9 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 1 834.6321
10 PRODES CERRADO deforestation 2019 8 1 2020 7 31 1 1185 2 919.1458
In this example, users are able to acquire data by loiname (SÃO PAULO) and dates, we also considered filters in the data. Compare with SÃO PAULO http://www.terrabrasilis.dpi.inpe.br/app/dashboard/deforestation/biomes/cerrado/increments
data <- get_dataByParameters(apiPath, prodesCerrado, classes$name, loinamesByLoi[10,]$gid, "2015-01-01", "2020-12-31") %>%
dplyr::filter(.,type==2) %>%
dplyr::filter(.,endDate.year!=2000) %>%
dplyr::select(name, clazz, startDate.year, endDate.year, area)
data
name clazz startDate.year endDate.year area
1 PRODES CERRADO deforestation 2015 2016 3.275794
2 PRODES CERRADO deforestation 2016 2017 3.706419
3 PRODES CERRADO deforestation 2017 2018 14.607230
4 PRODES CERRADO deforestation 2018 2019 6.113063
5 PRODES CERRADO deforestation 2019 2020 8.259873
Plot result
library(ggplot2)
ggplot(data, aes(x=as.factor(endDate.year), y=area, fill=clazz)) +
geom_text(aes(label=as.numeric(round(data$area, 2))), vjust=-0.5, hjust=0.3, size = 4) +
geom_bar(stat = "identity", width = 0.8, fill = "#008080") +
scale_x_discrete("Year", labels = as.character(data$endDate.year), breaks = data$endDate.year) +
theme(axis.text.x = element_text(angle = 45, vjust = 0.5)) +
labs(colour = "Date") + labs(x = "Years") + labs(y = "Areas (km²)") +
labs(title = loinamesByLoi[10,]$loiname) + labs(fill = "class")
Fig. 1. Deforestation increments - Cerrado biome, São Paulo State
References
Assis, L. F. F. G. A.; Ferreira, K. R.; Vinhas, L.; Maurano, L.; Almeida, C. A., Nascimento, J. R., Carvalho, A. F. A.; Camargo, C.; Maciel, A. M. TerraBrasilis: A Spatial Data Infrastructure for Disseminating Deforestation Data from Brazil. In Proceeding of the XIX Remote Sensing Brazilian Symposium, 2019.
Reporting Bugs
Any problem should be reported to terrabrasilis@inpe.br.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.