-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
208 lines (129 loc) · 7.59 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# valueR <img src="inst/logo/hex.png" align="right" height="160"/>
The goal of valueR is to facilitate access to real estate market data from VALUE AG's Market Data team via our API interfaces with R.
## Development
This package emerged from our own analyses of VALUE market data using R that we would like to make available to our users. The package is still under active development and we are happy to receive hints on enhancements to the functionality.
## Installation
You can install the development version of valueR from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools", dependencies = T)
devtools::install_github("Immobrain/valueR")
```
## API
With valueR you can access two of our REST-APIs:
##### **ANALYST**
VALUE ANALYST is based on our real estate market database, which provides up-to-date and comprehensive information on prices, rents and yields of the German real estate market. Most users access our database via our GUI "Analyst", we therefore refer to this access as "Analyst" in the context of valueR.
If you have a VALUE license with API/REST access, you can find the Swagger documentation [here](https://api.value-marktdaten.de/api-docs/).
##### **AVM**
VALUE AVM is a fully comprehensive solution for automated value indication and system-supported derivation of market and lending values. With the AVM, different value indications and also object and location parameters can be fetched. The latter are currently not yet implemented in valueR.
If you have a VALUE license with AVM-API/REST access, you can find the Swagger documentation [here](https://avm-api.value-marktdaten.de/v1/api-docs/).
## USAGE
To access VALUE Analyst and VALUE AVM you need a license with individual access data for each. Without valid credentials, the use of valueR is pointless. Please contact us if you would like a [trial license](https://www.value-marktdaten.de/en/contact/).
To load the package, run
```{r example, message=FALSE}
library(valueR)
```
You will be asked to provide you credentials using `valuer_access()`:
``` r
#> Unable to connect to AVM.
#> Unable to connect to ANALYST.
#> Please connect with valuer_access() to AVM or ANALYST.
```
To avoid having to enter credentials every time, valueR recognizes the following system variables:
- VALUER_ANALYST_USER
- VALUER_ANALYST_PW
- VALUER_AVM_USER
- VALUER_AVM_PW
It is highly recommended to set these variable using `Sys.setenv()` in [.Renviron](https://support.rstudio.com/hc/en-us/articles/360047157094-Managing-R-with-Rprofile-Renviron-Rprofile-site-Renviron-site-rsession-conf-and-repos-conf).
Developers with access to our testing-systems might also set `VALUER_AVM_URL` and `VALUER_ANALYST_URL` which both default to our live-systems if not provided.
Once you have provided your credentials, you will be logged in:
``` r
#> Connected to AVM: https://avm-api.value-marktdaten.de/v1
#> Connected to ANALYST: https://api.value-marktdaten.de/
```
## ANALYST EXAMPLES
First, you might check the system status by
```{r standard, results = F}
analyst_status()
```
There are some information on your license, e.g. the segments of your license
```{r segments}
analyst_segments() %>% dplyr::select(key, titleEn) %>% head(5)
```
your licensed variables
```{r vars}
analyst_vars() %>% dplyr::select(key, titleEn) %>% head(5)
```
or spatial information
```{r spatial}
analyst_spatial(type = 'municipalities') %>% head(5) %>% dplyr::select(municipalityCode,municipality)
```
Each of these functions return a `data.frame()` inlcuding all available descriptions.
To start a query, you must create a query on a given segment, with the provided filter conditions using `analyst_id()`. The returned ID can be used in subsequent API requests to access the data described by this query. The ID is only valid for 6 hours, before it expires and has to be posted again. A query must be provided as JSON, e.g.
```{r id}
id <- analyst_id(json = '{"segment": "WHG_K","administrativeSpatialFilter": {"postalCodes": [23558]}}',query_id = T)
id
```
To create a valid JSON, you can also create a query in our ANALYST GUI and get the corresponding JSON output. Note that due to `query_id = T`, `analyst_id()` will return only an integer that can be used for further requests that return an object of class `analyst_class`.
This class is a structured list of objects from which you can choose. In most cases, you probably want to refer to `values` that include a tidy `data.frame()` of results. But you might also use the returned `JSON` to start a new query. Let's say, you want to create an ID for the counterpart to your original request, you could than use `analyst_queries()` to get the counterpart
```{r counter}
counterpart <- analyst_queries(id = id, subquery = 'counterpart')
class(counterpart)
```
and then getting a new ID for that counterpart:
```{r counter_json, include = F}
json <- jsonlite::fromJSON(as.character(counterpart$json))
json$durationMillis <- NULL
json <- jsonlite::toJSON(json)
counterpart <- NULL
counterpart$json <- json
```
```{r counter_json_id}
counterpart$json
id_counter <- analyst_id(json = counterpart$json,query_id = T)
id_counter
```
You're then ready to get all results of your original request and its counterpart using `analyst_results()`. E.g. to get a timeline of both requests, set `subquery = 'timeline'` and provide `yearParts`.
```{r timeline, fig.height = 3, dpi=600}
# Leave variable empty to get available variables:
analyst_results(id, subquery = 'timeline', yearparts = 2)$values$key
orig <- analyst_results(id, subquery = 'timeline', variable = 'kosten_je_flaeche', yearparts = 2)
orig_seg <- analyst_queries(id = id, subquery = 'queryId')$values$segment # get segment of ID
orig_v <- orig$values %>% dplyr::mutate(segment = orig_seg)
counter <- analyst_results(id_counter, subquery = 'timeline', variable = 'kstn_miete_kalt_pqm', yearparts = 2)
counter_seg <- analyst_queries(id = id_counter, subquery = 'queryId')$values$segment # get segment of counter ID
counter_v <- counter$values %>% dplyr::mutate(segment = counter_seg)
# combine both queries and compute index to plot results:
results <- orig_v %>% dplyr::bind_rows(counter_v) %>%
dplyr::group_by(segment) %>%
dplyr::mutate(index = value / value[date == min(date)] * 100)
```
```{r plot, echo=FALSE, fig.height = 3, dpi=600}
# Leave variable empty to get available variables:
library(ggplot2)
ggplot(results, aes(x = reorder(yearPartLabelEn, as.Date(date)), y = index, group = segment, color = segment)) +
geom_line() +
scale_color_manual(values=c("#00a8b0", "#5a17df")) +
xlab("period") +
ylab("index") +
theme_minimal() +
theme(axis.text.x = element_text(angle = 90, vjust = 0.5, hjust=1)) +
theme(legend.position="bottom",
legend.title=element_blank())
```
With `analyst_results()` and the corresponding ID, all predefined results can be retrieved. You can also get all single offers of the query by setting `subquery = 'offers'` to run your own statistics and analysis.
Please note that due to technical reasons a maximum of 100,000 individual offers can be retrieved. Currently, valueR does not yet contain an automated procedure to retrieve larger data sets. This limitation will be fixed soon.
Please also note that the ANALYST API also includes an endpoint to retrieve georeferencing of an address. Currently, this endpoint cannot be accessed with valueR. This limitation should also be fixed soon.
## AVM EXAMPLES
coming soon...