The Hong Kong Covid-19 API

The Hong Kong Covid-19 API is a GraphQL endpoint based on the data provided in DATA.GOV.HK. You will have access to data about the cases of COVID-19 infection, related buildings and large clusters with 10 or more cases.

GraphQL

Usage

There are 6 queries in total: case, cases, building, buildings, cluster, and clusters. The singular query is used to look up a specific record while the plural field returns all records of that type by default, and includes an optional argument that can be used to filter and order the results.

New to GraphQL? check the docs

Here are some examples:

# Query all cases since August and the related buildings
query {
  cases(
    orderBy: { reportDate: desc }
    where: { reportDate: { gte: "2021-01-01T00:00:00Z" } }
    first: 20
  ) {
    id
    age
    gender
    reportDate
    status
    buildings {
      name
      district
    }
  }
}

# Query a specific building with its address (name + district), and get all the relatedCases
query {
  building(
    where: {
      address: { name: "Grand Plaza Tao Heung", district: YAU_TSIM_MONG }
    }
  ) {
    name
    relatedCases {
      id
      age
      status
    }
  }
}

You can open the docs on the right of the GraphQL Playground to learn about all the available arguments.

Data Source

All data is collected from the CSV files provided by the DATA.GOV.HK and resolved to match the GraphQL schema. A cron job is set up to check for updates every hour. Since the data scraping is an on going process, additional fields, such as date of admission/discharge/decease, can be derived by comparing the latest status and the status the day before. But since these fields are derived, they are less accurate.

To learn about how the raw data is transformed, check out the resolver files in the lib folder. The data is stored in a PostgreSQL Database. You can check the full database schema in prisma/schema.prisma.

Contribution

Pull requests and feedback are welcome. Support this repo by giving it a 🌟. 😛

Development

The server and GraphQL API are built with Nexus and Prisma. Nexus is a Node.js TypeScript-focused code-first GraphQL framework. To learn about what that means, check out Nexus tutorial. Once you have a general idea of the Nexus workflow and want to spin up your own hkcovid19 server, here are the steps to get you started, note that you should be developing in a Linux enviroment (e.g. MacOS or Windows Subsystem for Linux):

1. Clone this repo with git clone https://github.com/hangindev/hkcovid19-gq.git.

2. Install the dependencies with npm install or yarn.

3. Set up a PostgreSQL Database. You can set up a local database(recommended) or get a free hosted PostgreSQL database on Heroku.

4. Create a .env file in the prisma directory and add your database connection url to it:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA"

5. Start the development server with npm run dev. When you are developing with Nexus, it is recommended to keep the dev server running to get the best static typing experience.

6. Create the database tables with Prisma Migrate

npx prisma migrate save --name init --experimental
npx prisma migrate up --experimental

7. To seed the database, open up a different terminal and run:

npm run seed

8. Now you should be able to visit http://localhost:4000 and start querying data.

9. If at any moment you want to clear the database, you may run:

npm run blowitallaway

License

MIT License