A Free GraphQL API for Johns Hopkins University COVID-19 Dataset
Rate this tutorial
You can retrieve an access token using the API like so:
Then you can read the GraphQL API documentation and start running queries like this one using the access token you just retrieved:
Recently, we built the MongoDB COVID-19 Open Data project using the dataset from Johns Hopkins University (JHU).
It's a great dataset for education purposes and for pet projects. The MongoDB Atlas cluster is freely accessible using the user
readonly
and the password readonly
using the connection string:This cluster contains 2 databases:
covid19
and covid19jhu
. Only the first one will be exposed with this GraphQL API. The second one contains the unprocessed raw data from JHU's CSV files. Learn about the databases and collection in the dedicated blog post.You can use this cluster to build your application, but I also set up a GraphQL API using MongoDB Realm to expose this data for you.
In this blog post, I will first show you how to access our GraphQL endpoint securely. Then we will have a look at the documentation together to build out a variety of GraphQL queries to access all sorts of information in our dataset - all against a single API endpoint. Learning how to to use filters and request only specific fields in our data will help optimize the performance of your applications - by bringing you exactly the data you want - nothing more, nothing less.

- Or any other tool which handles HTTP queries. I also tested to run the following queries with Postman, and it works great.
I used MongoDB Realm to create this GraphQL API. Since MongoDB Realm is secure by default, only authenticated queries can be made. Yet since I want to keep this service as open as possible, I simply used the Anonymous Authentication offered by MongoDB Realm.
So now, all you need to retrieve an access token is the MongoDB Realm Application ID — or
APP_ID
, for short — of my MongoDB Realm application:Inserting the
APP_ID
into the URL gives you:If you execute this query in your favorite shell, you will receive a JSON answer that looks like this one:
Access tokens expire 30 minutes after MongoDB Realm grants them. When an access token expires, you can request a new one using the same API, or you can get a new one using the refresh token. Although it's often just easier to request a new one.
Once you have the token, you can start browsing the GraphQL API documentation that I generated with GraphDoc and build your first query.
Five collections are available in this GraphQL API, and you can learn more about each one of them in our documentation. Each have a "singular" query which can be used to retrieve a single document and a "plural" one to retrieve a list of documents. As an exception, the metadata collection contains only a single document so it offers no "plural" query.
You can see all the possible queries in the "query" page in the documentation, but I have also summarized them in the following table:
Collection | Query (singular / plural) | Fields available |
---|---|---|
metadata |
|
|
countries_summary |
|
|
global |
|
|
global |
|
|
global_and_us |
|
|
us_only |
|
|
Find all the details in the GraphQL documentation. To explore this data and the flexibility of GraphQL, let's build out three example queries.
Let's first query the metadata collection. This collection contains only one single document listing all the values (obtained with mongodb distinct function) for the major fields.
Here is the GraphQL query:
Now let's build an HTTP query with it. Don't forget to replace the
ACCESS_TOKEN
in the query with your own valid token.Now let's refine our data query even further. We want to see how France is trending for the last week, so we will use a query filter:
Plus we will sort the dates in descending order with the most recent dates first. Remember with GraphQL, we can request as many or as few data fields as we want for the client. In this example, we'll only ask for the number of confirmed cases, deaths, and recoveries, along with the date. The final query with this filter and those specific fields is:
Or with cURL:
Which gives me:
Finally, let's find the three counties in the USA with the greatest number of confirmed cases:
Or with cURL:
Results:
You want to improve your knowledge even more around MongoDB and GraphQL? Then you must read the blog post GraphQL: The Easy Way to Do the Hard Stuff from Karen and Brian.
MongoDB made setting up a GraphQL API really easy. And this GraphQL API made querying our Covid19 dataset to gain insight even easier. We update this data every hour, and we hope you will enjoy using this data to explore and learn.
Are you trying to help solve this pandemic in any way? Remember that if you are trying to build an application that helps to detect, understand, or stop the spread of the COVID-19 virus, we have a FREE MongoDB Atlas credit program that can help you scale and hopefully solve this global pandemic.
I truly hope you will be able to build something amazing with this GraphQL API. Even if it won't save the world from the COVID-19 pandemic, I hope it will be a great source of motivation and training for your next pet project.
Send me a tweet or ping me in our Community Forum with your project using this API. I will definitely check it out!