Introduction

Bhoonidhi Data Access Software Interface Specification (SIS) outlines the protocol for accessing the data product catalog and facilitating data downloads from Bhoonidhi. It includes details on the access methods and the range of data products available for download. Bhoonidhi facilitates the dissemination of open satellite data via a user-friendly web application equipped with robust search functionalities for identifying target areas and downloading data.

The Bhoonidhi API allows developers and researchers to programmatically access and retrieve a diverse range of earth observation satellite data.

Key Features

• Data Access: Detailed documentation on accessing the Bhoonidhi data product catalog and initiating downloads.
• Search Capabilities: Bhoonidhi Search API works on STAC catalogue and follows the STAC specifications, leveraging advanced search options to identify and select satellite data products.
• Integration Guidelines: Guidance for integrating Bhoonidhi APIs into applications for automated data retrieval and processing.
• Use Cases: Examples illustrating how to effectively utilize Bhoonidhi API’s capabilities in various research and operational scenarios.

Getting Started

Whether you are a developer integrating satellite data into applications or a researcher exploring remote sensing data, this API specification provides all the necessary details to access Bhoonidhi API effectively.

The input is to be submitted as a request having JSON payload in the body of a POST request to the endpoint. The output response contains the same standard fields. The "errorCode" and "description" fields are populated in case of an API exception.

• Authenticate yourself using the userId and password: /auth/token
• Prepare the filter parameters
• Search for your data by providing the filter inputs: /data
• Download the product: /download

Prerequisites

• Python - minimum version supported is Python 3

Authentication

To access the APIs at Bhoonidhi, users must authenticate themselves with user id and password. Once the user is authenticated, access token is generated which is used to search and download data products. The access tokens are used for authenticating all catalogue access API requests within the validity period. Tokens are JSON Web Tokens (JWT). Do not fetch a new token for each API request you make.

Authentication in our API employs access tokens and refresh tokens to secure access and manage user sessions effectively.

Access Token

Access token is used to grant permission to access specific resources on behalf of the user. Validity of these tokens is short-lived and the token must be included in the 'Authorization' header of API requests (Bearer <access_token>).

• Endpoint: /auth/token
• URL: https://bhoonidhi-api.nrsc.gov.in/auth/token

Refresh Token

Refresh tokens are used to obtain a new access token once the current one expires. The validity of refresh token is longer-lived, designed to persist between sessions. Send this refresh token to the token endpoint to request a new access token when the current one expires.

• Endpoint: /auth/token
• URL: https://bhoonidhi-api.nrsc.gov.in/auth/token

Logout

Logout functionality in our API allows users to securely terminate their session and revoke access to their resources. To logout a user from our system, clients should send a POST request to the token revocation endpoint (/auth/logout) with the refresh_token included in the Authorization header of API requests (Bearer <refresh_token>).

• Endpoint: /auth/logout
• URL: https://bhoonidhi-api.nrsc.gov.in/auth/logout

Authentication Flow

1. Obtain Access Token: Client requests an access token from the authorization server by presenting credentials (e.g., username/password or client credentials).

2. Use Access Token: Include the access token in API requests to authenticate and authorize actions.

3. Refresh Access Token: When the access token expires, use the refresh token to obtain a new access token without requiring re-authorization.

Usage and Validity

These tokens have finite lifetimes for various reasons, but you can obtain new ones or request them from the Bhoonidhi API auth server using the token endpoint provided below. Although tokens are not permanent, they remain valid for a reasonable duration, ensuring they can be effectively reused. Avoid requesting a new token for every API call. Token retrieval is subject to rate limiting; therefore, receiving an HTTP 429 error indicates excessive token requests.

Response Code

Collections

Bhoonidhi STAC Collection groups geospatial data assets that share common satellite, sensor and product type. It provides a high-level structure to describe and organize multiple STAC Items, enabling easier discovery and access to spatial data.

Available Collections

Note: Include the access_token in the 'Authorization' header of API requests (Bearer access_token)

1. Get all collections:
https://bhoonidhi-api.nrsc.gov.in/data/collections

2. Get collection details:
https://bhoonidhi-api.nrsc.gov.in/data/collections/ {collection_id}

3. Get all items in a collection:
https://bhoonidhi-api.nrsc.gov.in/data/collections/ {collection_id}/items

4. Get details of an item (id):
https://bhoonidhi-api.nrsc.gov.in/data/collections/ {collection_id}/items/{item_id}

Search Data

Search for satellite data products from Bhoonidhi STAC catalogue

• Endpoint: /search
• URL: https://bhoonidhi-api.nrsc.gov.in/data/search

Search Methods

• GET request using query parameters
• POST request with query parameters as request body

Requesting for Data

Note: Include the access_token in the 'Authorization' header of API requests (Bearer access_token)

Query Parameters

GET request

Search by Query Parameters – date, ID, bbox, etc

• ?datetime=2024-10-01T00:59:31.293Z/
• ?bbox=-80.673805 ,-0.52849 ,-78.060341 ,1.689651
• ?datetime=2021-12-31T09:59:31.293Z/2023-12-31T09:59:31.293Z
• ?bbox=-80.673805,-0.52849,-78.060341,1.689651&datetime=2014-10-13T23:28:54.650Z
• ?limit=10
• STAC item properties as attributes for filtering; see query_by_filters

POST request

Input json format

{
  "collections": ["string"],
  "ids": ["string"],
  "bbox": ["string","string","string","string"],
  "intersects": {
    "type": "Point", //Other options - MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon
    "coordinates": ["string","string"],
    "bbox": ["string","string","string","string"]
  },
  "datetime": "string",
  "limit": 10,
  "sortby": [
    {
      "field": "string",
      "direction": "asc"
    }
  ],
  "fields": {
    "include": [],
    "exclude": []
  },
  "token": "string",
  "filter": {},
  "filter-crs": "string",
  "filter-lang": "cql2-json"
  }

Pagination

For GET and POST requests, a link with "rel": "next" is provided in the response. This link will contain the URL to get the next page of results. For more details, please refer this

Responses

Data Product Download

The product download endpoints facilitate seamless access to the data products from ISRO's earth observation satellites. Developers can integrate these endpoints into their applications to automate the download of products and this specification details the endpoints, parameters, authentication requirements, expected responses, and error handling procedures necessary to effectively utilize Bhoonidhi's comprehensive data repository of satellite data products.

• Endpoint: /download
• URL: https://bhoonidhi-api.nrsc.gov.in/download

GET request

• https://bhoonidhi-api.nrsc.gov.in/download?id=<id>&collection=<collection_name>
• Note: Include the access_token in the 'Authorization' header of API requests (Bearer access_token)

Download Issues

• Any issue at download is indicated by the response code returned in the response object. If the response code indicates an error, “wait” logic is to be implemented instead of immediate multiple retires.
• The users are requested to periodically check the Bhoonidhi notifications page at Bhoonidhi home URL about known system downtimes or dataset issues.
• We recommend using concurrent downloads as it is allowed at Bhoonidhi. If the request returns a Rate Limit error, decrease the concurrency.
• Download only the products with property 'Online' = 'Y' see Search -> Examples (filter_by_online_status). Accessing downloads tagged as 'Online' = 'N' will cause data fetch delays. Download restrictions and throttling are active on the Bhoonidhi API. If you encounter slow download speeds, it's probably due to high data demand.

Responses

Rate Limiting

To enhance user experience and maintain system stability, Bhoonidhi implements rate limiting to prevent system overload. When the rate limit is exceeded, the Bhoonidhi API responds with an HTTP 429 response code. In such cases, we recommend increasing the time interval between retry attempts for failed requests to improve API interaction reliability.

• Authentication endpoint: 20 requests per hour per IP address

• Search endpoint: 3 requests per second per IP address

• Download endpoint:

  • 5 concurrent downloads per user & IP address. If this limit is exceeded, an HTTP 412 response code is returned.

  • Once the daily download limit is reached, only 1 concurrent download per user & IP address is allowed, and the bandwidth will be throttled.

Errors

Whenever an error occurs, whether it be the fault of the user or an internal system, an error object will be returned. HTTP response codes of 4xx suggest a bad request. If you receive a 4xx response, we recommend reviewing the API docs for more context to help you troubleshoot. 5xx errors suggest a problem on Bhoonidhi API's end, so if you receive a 5xx error, please contact support.

  {
    "ErrorCode": <error_code>,
    "Description": <description>,
    "Action": <action>
  }
                        

In case of any issues while accessing Bhoonidhi API, please contact us at bhoonidhi[at]nrsc[dot]gov[dot]in. The mail to have following details:

Subject: Bhoonidhi API access - UserId, IP address, End point
Contents: Contents of the request and response, error snapshot and any other information that may help us in debugging and provide resolution to the issues. 
                        

HTTP Status Code Summary