RESTful API documentation

CoronaTab API

We use a public REST API to fetch all the data in our Dashboard. Feel free to use our API for your needs as long as you behave well and credit CoronaTab and the Data Sources we use ourselves :)

All endpoints are cached for 1 Hour through Cloudflare. We purge the cache if the data has updated. We have Origin CORS policies set to only allow coronatab.app domain, so you won't be able to access our API directly from any site, therefore we encourage you to fetch the data and store it on your server, or another option is to setup a Reverse proxy.

If you have any problem with the API please create an Issue and we will discuss possible solutions.

This API is a constantly iterated product so check back often for any announcements, additional data or breaking changes.

Last updated: 2020-03-27 19:00 UTC

Host

https://api.coronatab.app

Locales / Language

We plan to support as many languages as possible. Currently the API will look at Accept-Language header and try to serve the content in that language. You can override that by setting Content-Language header when making the request. If we don't have a translation for any of the entities we will always fall back to English.

Endpoints

All responses are going to have higher level data object that will wrap the results:

{
    "data": ...
}

Places Types

GET /places/types - Get all Place Types

Response:

{
    "data": [
        {
            "id": "planet",
            "name": "Planet"
        },
        {
            "id": "country",
            "name": "Country"
        },
        {
            "id": "region",
            "name": "Region"
        },
        {
            "id": "city",
            "name": "City"
        }
    ]
}

Places

Place schema:

id: string - Unique Place ID
typeId: PlaceTypeId - Place type
name: string - Localised name
parentId: string - Parent Place ID
latestData: { 
  date: 'YYYY-MM-DD' 
  cases: number
  deaths: number
  recovered: number
} - Latest available data for the Place
dataSource?: string
alpha2code?: string - [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code
alpha3code?: string - [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code
population?: number - We have population data for all countries and most regions
location?: GeoJSON Point - centre coordinate of the place (we have about 95% of all 7k+ places)
hospitalBeds?: number - Number of hospital beds in the Place
hospitalBedOccupancy?: number (0.0-1.0) - Percentage of occupied beds during non health crisis period. 
icuBeds?: number - Number of ICU beds in the Place
children?: Place[] - child places if available e.g. Cities of a Region.

Relationships:

children - All the child places of the place e.g. Cities of a Region, Regions of a Country

GET /places - Get/Find places

Query String parameters (? means optional):

typeId?: PlaceTypeId
include?: Relationship[] - Relationship to include. `?include[]=children&include[]=...`
limit?: number - Pagination limit
offset?: number - Pagination offset
name?: string - Fuzzy search places by name

Response to /places?typeId=country&include[]=children&name=united king :

{
    "data": [
        {
            "id": "united-kingdom",
            "typeId": "country",
            "alpha2code": "GB",
            "alpha3code": "GBR",
            "dataSource": "https://www.gov.scot/coronavirus-covid-19/",
            "location": {
                "type": "Point",
                "coordinates": [
                    -3.19243272249992,
                    55.1916161155
                ]
            },
            "population": 67886011,
            "parentId": "earth",
            "latestData": {
                "date": "2020-03-26",
                "cases": 11658,
                "deaths": 578,
                "recovered": 135
            },
            "children": [
                {
                    "id": "united-kingdom-birmingham",
                    "typeId": "region",
                    "location": {
                        "type": "Point",
                        "coordinates": [
                            -1.88584835476777,
                            52.4764612908559
                        ]
                    },
                    "dataSource": "https://www.arcgis.com/sharing/rest/content/items/b684319181f94875a6879bbc833ca3a6/data",
                    "latestData": {
                        "date": "2020-03-27",
                        "cases": 290,
                        "deaths": 0,
                        "recovered": 0
                    },
                    "name": "Birmingham"
                }
            ]
        }
    ]
}

GET /places/closest - Find closest place to coordinates or IP address (X-Forwarded-For header)

Query String parameters (? means optional):

typeId?: PlaceTypeId
include?: Relationship[] - Relationship to include. `?include[]=children&include[]=...`
lng?: number - Longitude coordinate. Only taken into account if Latitude is also provided
lat?: number - Latitude coordinate. Only taken into account if Longitude is also provided

**Response: ** Same as for Places, but limited to only 5 closest places.

GET /places/:placeId - Get a specific place.

Query String parameters (? means optional):

include?: Relationship[] - Relationship to include. `?include[]=children&include[]=...`

**Response: ** Same as for Places, but just 1 place object.

{
    "data": {
        "id": "united-kingdom",
        "typeId": "country",
        "name": "United Kingdom",
        ...
    }
}

Places Data

GET /places/:placeId/data - Get all Place data ordered by date (ascending)

Query String parameters:

compact?: boolean - Make the data payload compact: [['YYYY-MM-DD', cases, deaths, recovered], ...]

Response to /places/china/data.

{
    "data": [
        {
            "date": "2020-01-22",
            "cases": 548,
            "recovered": 28,
            "deaths": 17
        },
        {
            "date": "2020-01-23",
            "cases": 693,
            "recovered": 31,
            "deaths": 20
        },
        ...
    ]
}

Response to /places/china/data?compact=true.

{
    "data": [
        ["2020-01-22", 548, 17, 28],
        ["2020-01-23", 693, 20, 31],
        ...
     ]
}