0
# State Historical Data Streams
1
2
Full-refresh streams providing historical COVID-19 data for all German states. These streams deliver comprehensive state-level historical data with specialized parsing for multi-state responses but use full-refresh synchronization.
3
4
## Capabilities
5
6
### States Historical Cases
7
8
Historical COVID-19 cases data for all German states.
9
10
```python { .api }
11
class StatesHistoryCases(ByStateRkiCovidStream):
12
"""
13
Historical COVID-19 cases data for all German states.
14
15
API Endpoint: https://api.corona-zahlen.org/states/history/cases/:days
16
Sync Mode: Full refresh
17
Primary Key: None
18
19
Provides historical daily cases data for each German state
20
with state names and abbreviations included in each record.
21
"""
22
23
primary_key = None
24
25
def __init__(self, config, **kwargs):
26
"""
27
Initialize with configuration containing start_date.
28
29
Parameters:
30
- config: dict containing 'start_date' in YYYY-MM-DD format
31
"""
32
33
def date_to_int(self, start_date) -> int:
34
"""
35
Convert start_date to days parameter for API.
36
37
Calculates difference between start_date and current date.
38
Returns minimum of 1 if date is in future.
39
"""
40
41
def path(self, stream_state=None, stream_slice=None, next_page_token=None) -> str:
42
"""Returns path with days: 'states/history/cases/{days}'"""
43
```
44
45
### States Historical Incidence
46
47
Historical COVID-19 incidence data for all German states.
48
49
```python { .api }
50
class StatesHistoryIncidence(ByStateRkiCovidStream):
51
"""
52
Historical COVID-19 incidence data for all German states.
53
54
API Endpoint: https://api.corona-zahlen.org/states/history/incidence/:days
55
Sync Mode: Full refresh
56
Primary Key: None
57
58
Provides historical 7-day incidence rates per 100,000 population
59
for each state with geographic identifiers.
60
"""
61
62
primary_key = None
63
64
def path(self, stream_state=None, stream_slice=None, next_page_token=None) -> str:
65
"""Returns path: 'states/history/incidence/{days}'"""
66
```
67
68
### States Historical Frozen Incidence
69
70
Historical COVID-19 frozen incidence data for all German states.
71
72
```python { .api }
73
class StatesHistoryFrozenIncidence(ByStateRkiCovidStream):
74
"""
75
Historical COVID-19 frozen incidence data for all German states.
76
77
API Endpoint: https://api.corona-zahlen.org/states/history/frozen-incidence/:days
78
Sync Mode: Full refresh
79
Primary Key: None
80
81
Provides historical frozen incidence rates for consistent
82
state-level reporting and cross-state comparisons.
83
"""
84
85
primary_key = None
86
87
def path(self, stream_state=None, stream_slice=None, next_page_token=None) -> str:
88
"""Returns path: 'states/history/frozen-incidence/{days}'"""
89
```
90
91
### States Historical Deaths
92
93
Historical COVID-19 deaths data for all German states.
94
95
```python { .api }
96
class StatesHistoryDeaths(ByStateRkiCovidStream):
97
"""
98
Historical COVID-19 deaths data for all German states.
99
100
API Endpoint: https://api.corona-zahlen.org/states/history/deaths/:days
101
Sync Mode: Full refresh
102
Primary Key: None
103
104
Provides historical daily deaths data for each state
105
for mortality analysis and state-level trend tracking.
106
"""
107
108
primary_key = None
109
110
def path(self, stream_state=None, stream_slice=None, next_page_token=None) -> str:
111
"""Returns path: 'states/history/deaths/{days}'"""
112
```
113
114
### States Historical Recovered
115
116
Historical COVID-19 recovery data for all German states.
117
118
```python { .api }
119
class StatesHistoryRecovered(ByStateRkiCovidStream):
120
"""
121
Historical COVID-19 recovery data for all German states.
122
123
API Endpoint: https://api.corona-zahlen.org/states/history/recovered/:days
124
Sync Mode: Full refresh
125
Primary Key: None
126
127
Provides historical recovery data for each state to support
128
active case calculations and recovery rate analysis.
129
"""
130
131
primary_key = None
132
133
def path(self, stream_state=None, stream_slice=None, next_page_token=None) -> str:
134
"""Returns path: 'states/history/recovered/{days}'"""
135
```
136
137
### States Historical Hospitalization
138
139
Historical COVID-19 hospitalization data for all German states.
140
141
```python { .api }
142
class StatesHistoryHospitalization(ByStateRkiCovidStream):
143
"""
144
Historical COVID-19 hospitalization data for all German states.
145
146
API Endpoint: https://api.corona-zahlen.org/states/history/hospitalization/:days
147
Sync Mode: Full refresh
148
Primary Key: None
149
150
Provides historical hospitalization metrics for each state
151
including admissions and ICU utilization data.
152
"""
153
154
primary_key = None
155
156
def path(self, stream_state=None, stream_slice=None, next_page_token=None) -> str:
157
"""Returns path: 'states/history/hospitalization/{days}'"""
158
```
159
160
## Base State Stream Class
161
162
All state historical streams inherit from ByStateRkiCovidStream.
163
164
```python { .api }
165
class ByStateRkiCovidStream(RkiCovidStream, ABC):
166
"""
167
Base class for state-level historical data streams.
168
169
Extends RkiCovidStream with specialized parsing for multi-state
170
API responses that contain nested data structures organized by state.
171
"""
172
173
def parse_response(self, response, **kwargs):
174
"""
175
Parse multi-state historical response structure.
176
177
Processes API responses where each state is keyed by abbreviation
178
and contains a 'history' array of historical records.
179
180
Response Structure:
181
{
182
"data": {
183
"BW": {"name": "Baden-Württemberg", "history": [...]},
184
"BY": {"name": "Bayern", "history": [...]},
185
...
186
}
187
}
188
189
Returns:
190
Flattened records where each historical data point includes:
191
- Original historical data fields
192
- name: Full state name
193
- abbreviation: Two-letter state code
194
"""
195
```
196
197
## Usage Examples
198
199
### Accessing State Historical Data
200
201
```python
202
from source_rki_covid import SourceRkiCovid
203
204
source = SourceRkiCovid()
205
config = {"start_date": "2023-01-01"}
206
207
# Get all streams
208
streams = source.streams(config)
209
210
# Filter for state historical streams
211
state_streams = [
212
stream for stream in streams
213
if stream.__class__.__name__.startswith('StatesHistory')
214
]
215
216
print(f"State historical streams: {len(state_streams)}") # 6 streams
217
```
218
219
### Reading Multi-State Data
220
221
```python
222
# Example with States Cases stream
223
states_cases = StatesHistoryCases(config=config)
224
225
# Read historical data for all states
226
state_data = {}
227
for record in states_cases.read_records():
228
state_name = record['name']
229
state_abbr = record['abbreviation']
230
date = record['date']
231
cases = record.get('cases', 0)
232
233
if state_name not in state_data:
234
state_data[state_name] = []
235
236
state_data[state_name].append({
237
'date': date,
238
'cases': cases,
239
'abbreviation': state_abbr
240
})
241
242
print(f"States with data: {len(state_data)}") # 16 German states
243
```
244
245
### Date Range Processing
246
247
```python
248
from datetime import datetime, timedelta
249
250
# Calculate API parameters
251
states_incidence = StatesHistoryIncidence(config={"start_date": "2023-03-01"})
252
253
# Check days calculation
254
days = states_incidence.date_to_int("2023-03-01")
255
print(f"Requesting {days} days of historical data")
256
257
# API endpoint will be: states/history/incidence/{days}
258
path = states_incidence.path()
259
print(f"API path: {path}")
260
```
261
262
### State-Level Analysis
263
264
```python
265
# Analyze data by specific states
266
target_states = ['Bayern', 'Nordrhein-Westfalen', 'Baden-Württemberg']
267
268
states_deaths = StatesHistoryDeaths(config=config)
269
270
for record in states_deaths.read_records():
271
if record['name'] in target_states:
272
print(f"{record['name']} ({record['abbreviation']}): "
273
f"{record['date']} - Deaths: {record.get('deaths', 0)}")
274
```
275
276
## Data Structure
277
278
State historical streams return records with the following structure:
279
280
### Historical Data Fields
281
- **date**: Date string in YYYY-MM-DD format
282
- **cases/deaths/recovered**: Daily counts for the specific metric
283
- **incidence**: 7-day incidence rate per 100,000 population
284
- **weekIncidence**: Weekly incidence calculations
285
- **delta**: Day-over-day changes in metrics
286
287
### State Identification Fields
288
- **name**: Full German state name (e.g., "Baden-Württemberg")
289
- **abbreviation**: Two-letter state code (e.g., "BW")
290
291
### Metadata Fields
292
- **population**: State population for rate calculations
293
- **meta**: Additional metadata including last update timestamps
294
295
## German States Coverage
296
297
The streams provide data for all 16 German federal states (Bundesländer):
298
299
- **Baden-Württemberg** (BW)
300
- **Bayern** (BY)
301
- **Berlin** (BE)
302
- **Brandenburg** (BB)
303
- **Bremen** (HB)
304
- **Hamburg** (HH)
305
- **Hessen** (HE)
306
- **Mecklenburg-Vorpommern** (MV)
307
- **Niedersachsen** (NI)
308
- **Nordrhein-Westfalen** (NW)
309
- **Rheinland-Pfalz** (RP)
310
- **Saarland** (SL)
311
- **Sachsen** (SN)
312
- **Sachsen-Anhalt** (ST)
313
- **Schleswig-Holstein** (SH)
314
- **Thüringen** (TH)
315
316
## Sync Behavior
317
318
Unlike Germany historical streams, state historical streams use **full refresh** synchronization:
319
320
1. **Complete Data Fetch**: Retrieves all historical data for all states on each sync
321
2. **No State Tracking**: Does not maintain incremental state between syncs
322
3. **Comprehensive Coverage**: Ensures complete historical dataset for all states
323
4. **API Efficiency**: Uses date range parameter to limit response size
324
5. **Data Consistency**: Full refresh ensures no missing state data