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>).

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.

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>).

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
Code Description Scenario Handling
200 Success The inputs given are proper and the request was processed. NA
400 Bad Request Incorrect keys given in the request Verify the inputs given
401 Unauthorized Incorrect password Enter correct userId and password
403 Forbidden Max sessions already active Logout of active sessions or re-use active sessions
500 Internal Server Error Issue occurred at server while trying to process the request Try again after sometime. If the issue still persists, inform API administrator
Access Token
                        
{
    "userId": <userId>,
    "password": <password>,
    "grant_type": "password"
}
                        
                                    
                        
{
    "userId": <user_id>,
    "access_token": <access_token>,
    "token_type": "Bearer",
    "expires_in": <access_token-expiry-time-in-seconds>,
    "refresh_token": <refresh_token>
}
                        
                                    
Refresh Token
                        
{
    "userId": <userId>,
    "refresh_token": <refresh_token>,
    "grant_type": "refresh_token"
}
                        
                                    
                        
{
    "userId": <user_id>,
    "access_token": <access_token>,
    "token_type": "Bearer",
    "expires_in": <access_token-expiry-time-in-seconds>,
    "refresh_token": <refresh_token>
}
                        
                                    
Example Input JSON Object for Access Token:
{
"userId" : "bhoonidhiuser",
"password" : "password@123",
"grant_type" : "password"
}
Example Output JSON Object for Access Token:
{
"userId": "bhoonidhiuser",
"access_token": "eyJhbGcidfgdUzdgisvJ9.eyJ0aW1lc3RhbXAiOjE3MjEwNDQxMzIzMDksInN112345k9OTF9hYmNwcXIiLCJpYXQiOjE3MjEwNDQxMzIsImV4cCI6MTcyMTA0NTMzMn0.S13PlY0mCKgbpSTO-BmySigpLZa2ibKnU1Bw-owWBU9vpH2my0MHxGnOLLGazV10JKleGurhm-9Zy20KEskA0w",
"token_type": "Bearer",
"expires_in": 1200,
"refresh_token": "eyJhbGcidfgdUzUxMiJ9.eyJzdWIiOiJPTkxfYWJjcHFyIiwiaWF0IjoxNzIxMDQ0MTMyLC09876iOjE3MjEwNjIxMzJ9.31eyXxroTEXGIUEwEzttO7JGe4WpcZXeKJ_BZ6jsP3iWOqAl_F7n6BHsxlIWadF_tfRmxq4uF4StS8yN1DqA7Q"
}
Example Input JSON Object for Refresh Token:
{
"userId" : "bhoonidhiuser",
"refresh_token" : "eyJhbGciOiJIUzUxMgfhgfhiJ9.eyJzdWIiOiJPTkxfbmFzZWViIiwiaWF0IjoxNzfyhhghIwNjk2NTMwLCJleHAiOjE3MjA3MTQ1MzB9.c-rukaI-9N9uLzqRQsKffghgfhS1GZI7fgAPZ0hAa-Clb3u47Q6kIw7LNkpyeGpusa7wkpk2-swFPK0Efr_CX1f-DmlA",
"grant_type" : "refresh_token"
}
Example Output JSON Object for Refresh Token:
{
"userId": "bhoonidhiuser",
"access_token": "eyJhbGciOighgfJIUzUxMiJ9.eyJ0aW1lc3RhbXAiOjE3MjEwNDQyNjI3NzEsInN1YiI6Ifghk9OTF9hYmNwcXIiLCJpYXQiOjE3MjEwNDQyNjIsImV4cCI6MTcyMTA0NTQ2Mn0.6OeHy4Xf0r_jguOQiLeu9wd6B7P_P3O-L4f9GudcNC9-cxpI3LUmWd6jepxcZ5nZNhQcclSvvyS_cRCUffpN5w",
"token_type": "Bearer",
"expires_in": 1200,
"refresh_token": "eyJhbGciOiJIUfghgzUxMiJ9.eyJzdWIiOiJPTkxfYWJjcHFyIiwiaWF0IfghgfjoxNzIxMDQ0MjYyLCJleHAiOjE3MjEwNjIyNjJ9.DUbVoZXRoSLXu8GjhICuUgqLWXwikvN9al-M2sqT1DKeeypNZcyRJtFpfqqtXzY6rX8Hej3Y8D2SGVmkaJFing"
}




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.

GET request
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
Code Description Scenario Handling
401 Unauthorized Session expired Invalid session detected. Please login again
404 Product not found Product is not available on online storage Product cannot be downloaded as it is not available on online storage.
412 Precondition failed Concurrent downloads exceeded Wait till the currently running download is completed before initiating another download.
500 Internal Server Error Issue occurred at server while trying to process the request Recheck the input given. If everything is correct, try again after some time or intimate the API provider
504 Gateway Timeout Download gets interrupted Download interrupted. Download the product again



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:

    • 3 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
Response Code Description
400Bad Request
401Unauthorized
402Payment Required
403Forbidden
404Not Found
405Method Not Allowed
406Not Acceptable
407Proxy Authentication Required
408Request Timeout
409Conflict
410Gone
411Length Required
412Precondition Failed
413Payload Too Large
414Request-URI Too Long
415Unsupported Media Type
416Requested Range Not Satisfiable
417Expectation Failed
418I’m a teapot
421Misdirected Request
422Unprocessable Entity
Response Code Description
423Locked
424Failed Dependency
426Upgrade Required
428Precondition Required
429Too Many Requests
431Request Header Fields Too Large
444Connection Closed Without Response
451Unavailable for Legal Reasons
499Client Closed Request
500Internal Server Error
501Not Implemented
502Bad Gateway
503Service Unavailable
504Gateway Timeout
505HTTP Version Not Supported
506Variant Also Negotiates
507Insufficient Storage
508Loop Detected
510Not Extended
511Network Authentication Required
598Network Read Timeout Error
599Network Connect Timeout Error