Hello World - Introducing API for Spatio-Temporal Environmental Data

This tutorial is a quick primer on familiarizing yourself with our Developer Portal.

Prerequisites

To complete this tutorial, you will need

Python
Jupyter Notebook
Access to the Terminal or Windows Command-Line or CLI

Setting up your environment

To get started, one needs to set up a coding environment on your computer. Setting it up can vary depending on if you are on a Mac OS, Linux or Windows.

Python
Jupyter Notebook
Installing necessary packages

Understanding the Developer Portal

We disseminate our high-quality spatiotemporal environmental datasets through our APIs which can be accessed through the Developer Portal. The Dev Portal allows you to access information and tools necessary to use our API and helps integrate them into your workflows as input. Sign up for the Developer Portal here.

After signing up, you land on the console that lets you track how much data you are requesting and other account-related details like your current subscriptions, etc. We offer 300 free API calls per month when you sign up.

The Developer Portal Home Screen

Generating your API key

API is the acronym for Application Programming Interface. It is simply a way to get data from a specific set of URLs on the internet. You can read more about it here.

Before making an API call, you need to generate an API key. You can do this by clicking the blue button 🔁 on the Console Page. This generates your API key, a token that you will use to access datasets via API endpoints.

API keys usually are a mangled set of letters and numbers. You do not have to remember them. The console will always keep a record for you. Moreover, you can regenerate them any time you want but be aware that will expire the previous key & might break any integration you had made with it.

💡 Keep your API key safe & secure, and do not share it with anyone!

Introducing the documentation

Our Documentation or Docs describe the various kinds of products and API endpoints we provide and how the endpoints are structured. They tell you how to use them and what query parameters to send along with the request. They also provide the responses you can expect when you send queries.

They have three main components

https://gateway.blueskyhq.io/api/spatial-air-quality?api-key=XXXX-XXXX-XXXXX-XXXX&product=${product}&shapeId=${shapeId}&longitude=${longitude}&latitude=${latitude}&duration=${duration}&startDate=${startDate}&endDate=${endDate}&region=${region}&regionType=${regionType}

Endpoints

Query Parameters

query parameter	possible values
product	pm25 for PM2.5, so2 for Sulphur Dioxide emissions, etc.
region	Names of regions or places like Uttar Pradesh, Lucknow
regionType	The type of region could be a state, district, etc.
duration	The duration for which data is needed, so 1d for 1 day, 3d for 3 days, 1w for 1 week, 1m for a month, and 1y for a year.

Response

Your first API Call

Accessing the data by visiting an endpoint is termed as “Calling an API”. We will demonstrate this using 2 methods:

1. Using Curl

One way to access the data is by using curl through the terminal. You open the terminal, copy the curl command from the documentation and replace it with the query parameters you want. Let’s say we want data for a single day for Lucknow. You provide in the query parameters for product, region, regionType and duration

curl "https://gateway.blueskyhq.io/api/spatial-air-quality?api-key=86486514-6e39-527b-8ddd-6584b56147cf&product=pm25&region=lucknow&regionType=district&duration=1d"\ -X "GET"

Once you run the above line, you get the data for your query.

HTTP/1.1 200 OK
Content-Type: application/json

// Object containing two fields meta and data where meta is metadata of requested data and data is an array of objects where each object contains product data of a time instant.

{
   "data":[
      {
         "datetime":"2022-01-29T00:00:00.000Z",
         "pm25":88.34724169542709
      }
   ],
   "meta":{
      "duration":"1d",
      "region":"lucknow",
      "regionType":"district"
   }
}

2. Using Jupyter Notebook

Another way to access data is through Python and Jupyter Notebook. When we want to do a more detailed analysis, the Jupyter notebook is a better choice!

Start your Jupyter notebook. You do this by going to the Terminal and typing jupyter notebook

The above command will spin a local server & open a webpage in your browser connected to that server. This is the interface where all your work will happen.

A snapshot of the Jupyter Notebook Interface

Open a new Python 3 notebook. You will run the code in this new notebook necessary to make an API request.

We start with importing two packages necessary: requests andjson

# This package helps us reach out to the API
import requests 
# This package is necessary to ensure we receive data in a JSON format
import json

To access data, you need to know the endpoint and what parameters you need to provide. You can vary them & request data as per your needs. We repeat the above example of wanting the PM2.5 data for the district of Lucknow for a single day. Let’s break it down below how you’d select the parameters.

Product would be PM2.5, Region would be Lucknow, and RegionType would be District. You could also enter the latitude or longitude of a place instead as well. You also need to provide the Duration for which you want this data. To make your first API call, you will need to follow the steps provided below:

Let us list the parameters that you need to provide. You will need your API key, the product’s name, the region, the type of region, and the duration. The endpoint will be a concatenation of all of these parameters.
Let us now make an API call.
This code produces the following output. This is the result of an API call you just made.

Congratulations! You made your first API call. As you can see on the first line of the response, a status code of 200 means the request was successful. You could access data on PM2.5 levels in less than five lines of code.

Looking at the above output, you notice two components: data and meta. The meta part has the same values you gave to the API. The data component has PM 2.5 values for the last one day for the district of Lucknow.

If this interests you, in the following tutorial, you will look at getting data for a longer duration and figuring out how to make this data easier to analyze with a Jupyter notebook. Stay tuned!