API for local information on COVID-19
(hotlines, websites, test sites, health departments)
Search dashboard • Swagger docs • Contact
This API provides local information and addresses on COVID-19 for a given location (e.g. local hotlines & websites, nearby test sites, relevant health departments). It can be easily integrated into existing websites and apps, giving the user relevant information for their location. E.g., a tracing app could use this API to refer the user to their nearest test site in case of an infection risk. Features:
- Local information (hotlines, websites, test sites, health departments) for major German cities (more coming soon)
- Integration in websites & apps via REST API and Python/JavaScript clients
- Built-in location search for cities, neighborhoods, states, ...
Check out our search dashboard to get an idea of which data the API offers!
Our API in practice – web and mobile
We now have client libraries for Python (covid-local-py) and JavaScript (covid-local-js), so you can access the API directly from code. Both repos show some examples in their READMEs. Please make sure to still read the usage guide below to get an idea of how the API works in general. (Need a client for another language? Generate it yourself or reach out)
You can try out the API using our live deployment at http://ec2-3-90-67-33.compute-1.amazonaws.com (note that the main page does not return information!).
For example, to get all local information for Berlin Mitte, go to:
http://ec2-3-90-67-33.compute-1.amazonaws.com/all?place_name=Berlin&20Mitte
The data is returned as JSON. Note that information for hierachically higher areas (e.g. country-wide hotlines) are automatically returned as well.
Above, we used the /all
endpoint to request all information from the database. You can
also use the more specific endpoints /hotlines
, /websites
, /test_sites
and
/health_departments
, which will only a return a subset of the data, e.g.:
http://ec2-3-90-67-33.compute-1.amazonaws.com/hotlines?place_name=Berlin&20Mitte
To specify the location of the query, we support two options: You can either use the
place_name
parameter like above (with a city, neighborhood, state, ...). Under the
hood, this searches on geonames.org and simply uses the first result to search our
database. To get more control over the place selection (e.g. if the place name is
ambiguous), you can use the /places
endpoint:
http://ec2-3-90-67-33.compute-1.amazonaws.com/places?q=Berlin&20Mitte
This returns a list of places for your query. It uses the
geonames.org location search
with sensible defaults (e.g. search only for cities and districts) and clean
formatting. If you found the correct place among these results, you can extract its
geonames_id
and pass it to the other endpoints like this:
http://ec2-3-90-67-33.compute-1.amazonaws.com/all?geonames_id=2950159
For more details on endpoints, query parameters, and output formats, please have a look at the Swagger docs.
To run the API locally, clone this repo and run the following command:
cd ./covid-local-api/app/covid_local_api
uvicorn local_test:app --reload
The API should now be accessible at 127.0.0.1:8000. You can also deploy the API with docker, using the dockerfile in the repo (note that this will serve the API at port 80 instead of 8000).
To start the search dashboard, run:
streamlit run search-dashboard.py
This will start the dashboard on port 8501. Note that the dockerfile automatically
starts the dashboard along with the API (using the prestart.sh
file; docker deployment uses port 8600 instead of 8501).
Help us collect new data with our Google Form: https://bit.ly/covid-local-form
The data for this project is stored in a Google Sheet (note that there is one worksheet for each data type). If you think that any of the data is wrong, please add a comment directly to the document or write to [email protected]. You can also use our dashboard to search through the data.
Python 3.7 and all packages in requirements.txt
Client libraries can be generated automatically with the OpenAPI Generator. If you update an existing client, please make sure to copy its README.md
file before, as it was probably adapted manually.
For Python, run:
openapi-generator generate -i http://ec2-3-90-67-33.compute-1.amazonaws.com/openapi.json -g python -o covid-local-py --additional-properties packageName=covid_local,projectName=covid-local-py,packageUrl=https://github.com/cotect/covid-local-py,packageVersion=0.1.0 --git-host github.com --git-user-id cotect --git-repo-id covid-local-py
For JavaScript, run:
openapi-generator generate -i http://ec2-3-90-67-33.compute-1.amazonaws.com/openapi.json -g javascript -o covid-local-js --additional-properties moduleName=CovidLocal,projectName=covid-local-js,projectVersion=0.1.0 --git-host github.com --git-user-id cotect --git-repo-id covid-local-js
Both commands will use the API definition from the live deployment and write the client to covid-local-py
or covid-local-js
. After creating the client, you need to manually replace all occurences (in all files) of http://localhost
with http://ec2-3-90-67-33.compute-1.amazonaws.com
. This way, the client will pull data from the live deployment of the API (instead of a local deployment).