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

    Python is a high-level programming language designed to be easy to be read and implement. You can install the latest version of Python suitable for your computer from here. Here is a step-by-step breakdown of installing Python.

  • Jupyter Notebook

    After Python is installed, you will then install Jupyter Notebook from here. This is the code editor you will be running the code on. These notebooks have several advantages for analysis, including that they will let you see the output of the results of your input and are easier to tweak. You can find a detailed introduction to Jupyter notebooks here.

  • Installing necessary packages

    Open your Terminal and then type pip install requests. This install requests, a package that will be used later in the tutorial.

Understanding the Developer Portal

We disseminate our high-quality spatio-temporal 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 also helps with integrating them into your workflows as input. Sign up for the Developer Portal here.

After signing up, you land on the console that enables you to 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

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 you can make an API call, you need to generate an API key. You can do this by clicking on the blue button 🔁 on the Console Page. This generates your API key, which is just 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.

💡 Be sure to 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 one needs to send along with the request. They also provide you with the kind of responses you can expect when you send queries.


A preview of our documentation

A preview of our documentation

They have three main components

https://gateway.blueskyhq.in/api/breezo/spatial?api-key={your-api-key}&product={product}&shapeId={shapeId}&region={region}&regionType={regionType}&longitude={longitude}&latitude={latitude}&duration={duration}&startDate={startDate}&endDate={endDate}
  • Endpoints

    Endpoints or API endpoints are nothing but URLs where requests for information are sent to receive the resource that exists there. An endpoint looks like this:

    https://gateway.blueskyhq.in/api/breezo/spatial
    
  • Query Parameters

    If you carefully look in the above URL, you will notice smaller components such as "Product", "ShapeID", "Region", "RegionType", etc. These are called query parameters. For an endpoint to be accessible, you need to provide it in certain parameters. For example,

    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, it 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.

    It is essential to read the documentation carefully when looking for a specific request. You need to know which the endpoint is and what parameters to provide. Most of them are optional but some are required for the endpoint for a successful response and they are marked with “*.

  • Response

    The response part of the documentation shows what kind of an output/response to expect if all goes well. The data is usually in a JSON format. Sometimes, you might not get a response with data but with an error code, you’ll have to figure out what went wrong. Here is a list of what each error code means.

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.in/api/breezo/spatial?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

A snapshot of the Jupyter Notebook Interface


Open a new Python 3 notebook. In this new notebook, you will run the code necessary to make an API request.

We start off 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 out 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 response, a status code of 200, which means the request made was successful. You were able to access data on PM2.5 levels in less than five lines of code.

If you look 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.

You can find the code used in this tutorial here and a lot more in the getting-started repo.

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


Resources