Covid-19 HTTP API: case numbers as time series, for individual German states

I have built an HTTP API for providing the confirmed case numbers of Covid-19 infections in Germany, resolved by time as well as spatially — by the individual states.

To my knowledge that is the only data source providing this kind of information for automated consumption. That’s why I built it.

Here is the corresponding GitHub repository: https://github.com/jgehrcke/covid-19-germany-gae

The API is served by Google App Engine in Europe.

Of course this project is based on the shoulders of giants. Feel free to ask questions below. Thank you!

The primary concerns are:

  • convenience (easy to consume for you in your tooling!)
  • interface stability
  • data credibility
  • availability

Here is how to use that API:

For the history (time series) information for a specific German state:

First, construct the URL based on this pattern:

https://covid19-germany.appspot.com/timeseries/<state>/<metric>

For <state> use a ISO 3166 code, for <metric> use “cases” or “deaths”.

For example, to fetch the time evolution of the number of confirmed cases for Bayern (Bavaria):

$ curl -s https://covid19-germany.appspot.com/timeseries/DE-BY/cases | jq
{
  "data": {
    "2020-03-10T12:00:00+01:00": "314",
    "2020-03-11T12:00:00+01:00": "366",
    "2020-03-12T12:00:00+01:00": "500",
    "2020-03-13T12:00:00+01:00": "558",
    "2020-03-14T12:00:00+01:00": "681",
    "2020-03-15T12:00:00+01:00": "886",
    "2020-03-16T12:00:00+01:00": "1067",
    "2020-03-17T21:00:00+01:00": "1352",
    "2020-03-18T23:00:00+01:00": "1798"
  },
  "meta": {
    "info": "https://gehrcke.de/2020/03/covid-19-http-api-german-states-timeseries",
    "source": "Official numbers published by public health offices (Gesundheitsaemter) in Germany"
  }
}

The points in time are encoded using localized ISO8601 time string notation. Any decent datetime library can parse that into timezone-aware native timestamp representations.

For a current snapshot for all of Germany (no time series information):

$ curl -s https://covid19-germany.appspot.com/now | jq
{
  "current_totals": {
    "cases": 12223,
    "deaths": 31,
    "recovered": 99,
    "tested": "unknown"
  },
  "meta": {
    "contact": "Dr. Jan-Philip Gehrcke, jgehrcke@googlemail.com",
    "source": "ZEIT ONLINE (aggregated data from individual ministries of health in Germany)",
    "time_source_last_consulted_iso8601": "2020-03-19T03:47:01+00:00",
    "time_source_last_updated_iso8601": "2020-03-18T22:11:00+01:00"
  }
}

The data

Original data source: Gesundheitsämter

All data is exclusively based on official numbers published by public health offices in Germany (the Gesundheitsämter).

Attribution for collection and aggregation: RKI, ZEIT ONLINE

Numbers from the individual (hundreds of) health offices are first collected and aggregated on the state level, by the individual state health ministries. From here, they are further collected and published by the Robert Koch-Institut (yielding the data points in my database before March 17), but also by ZEIT ONLINE (yielding the data points in my database from March 17 on).

The time evolution detail of the data on the individual state level however gets lost in this publishing process, and I am carefully re-adding this aspect in hindsight.