Overview

The On demand Deep resolution API service allows users to run deep-resolution computations for a predefined area of interest, during a certain time period.

Base URL

The URL for the On demand API is https://api.digifarm.io/deep-resolution

Authentication

The On demand API uses client tokens for authentication. Include your client token in each request to the API.

This API provides deep-resolution data for a specific field over a specified date range. The endpoint accepts various query parameters for customization.

Endpoints

POST /deep-resolution/available_dates

This endpoint provides available dates for deep resolution imagery within a specified bounding box and time range.

Request URL POST https://api.digifarm.io/deep-resolution/available_dates

Method: POST

Request Headers

Content-Type: application/json

Request Body

  • client_token: [string, required] The client token for authorization.

  • bbox: [object, optional] The bounding box coordinates.

    • x_min: [float, required] The minimum longitude.
    • y_min: [float, required] The minimum latitude.
    • x_max: [float, required] The maximum longitude.
    • y_max: [float, required] The maximum latitude.

  • aoi: [object, optional] The GeoJSON format. We have only enabled Polygon and MultiPolygon single geometry GeoJson functionality for our API. Check the valid GeoJSON instructions here.

NOTE: At least need to provide either bbox or aoi. If provide both aoi and bbox, aoi has more precedence.

  • cloud_cover: [integer, required] The maximum allowed cloud cover percentage.

  • start_date: [string, optional] The start date in ISO 8601 format

  • end_date: [string, optional] The end date in ISO 8601 format

  • callback_url: [string, required] The URL to call with the results.


Example Request

curl -X POST https://api.digifarm.io/deep-resolution/available_dates \
 -H "Content-Type: application/json" \
 -d '{
 "bbox": {
    "x_min": 11.16545302951809,
    "y_min": 60.73687126373886,
    "x_max": 11.21197326267199,
    "y_max": 60.75331374707744
 },
 "aoi": { "type": "Feature", "properties": { "id": 1 }, "geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ 138.629423808807388, 35.396884261237581 ], [ 138.627417448995601, 35.396586287008105 ], [ 138.627417448995601, 35.396586287008105 ], [ 138.626682445896222, 35.39814568547569 ], [ 138.627169137137685, 35.399148865381584 ], [ 138.627477043841481, 35.399446839611059 ], [ 138.627993532505911, 35.399466704559693 ], [ 138.628281574261081, 35.399516366931273 ], [ 138.62859941343919, 35.399367379816532 ], [ 138.628807995399796, 35.398989945792529 ], [ 138.629125834577906, 35.398801228780535 ], [ 138.629821107780032, 35.398890621049375 ], [ 138.630417056238969, 35.398890621049375 ], [ 138.631161991812661, 35.398413862282212 ], [ 138.63163875057981, 35.398552916922633 ], [ 138.631608953156871, 35.398890621049375 ], [ 138.631241451607195, 35.399029675689796 ], [ 138.630844152634552, 35.399466704559693 ], [ 138.629890635100224, 35.399655421571694 ], [ 138.62936421396148, 35.400360627248112 ], [ 138.629523133550549, 35.400787723643695 ], [ 138.629632390768023, 35.40094664323275 ], [ 138.629602593345084, 35.401135360244751 ], [ 138.629185429423814, 35.4013538746797 ], [ 138.629016577360431, 35.401473064371487 ], [ 138.628976847463179, 35.401721376229382 ], [ 138.629562863447802, 35.402416649431487 ], [ 138.630019757266325, 35.402645096340756 ], [ 138.631013004697934, 35.402913273147277 ], [ 138.631350708824669, 35.4033006396456 ], [ 138.631946657283606, 35.402823880878437 ], [ 138.63195658975792, 35.402645096340756 ], [ 138.632075779449707, 35.402257729842439 ], [ 138.632701525331612, 35.401502861794434 ], [ 138.633625245442971, 35.401542591691694 ], [ 138.633486190802557, 35.401880295818437 ], [ 138.633595448020031, 35.402088877779065 ], [ 138.634529100605732, 35.403211247376753 ], [ 138.634469505759824, 35.40478057831865 ], [ 138.634688020194773, 35.404949430382025 ], [ 138.635552145460252, 35.405038822650866 ], [ 138.636356675879824, 35.405446054097816 ], [ 138.636585122789086, 35.405058687599499 ], [ 138.636465933097298, 35.404830240690231 ], [ 138.636942691864476, 35.404125035013813 ], [ 138.636833434647002, 35.40379726336139 ], [ 138.636654650109307, 35.403608546349389 ], [ 138.637886276924462, 35.402436514380121 ], [ 138.636604987737712, 35.398155617950003 ], [ 138.629423808807388, 35.396884261237581 ] ] ] ] } },
 "cloud_cover": 70,
 "start_date": "2023-10-01T00:00:00",
 "end_date": "2024-01-01T00:00:00",
 "client_token": "********************************",
 "callback_url": "https://webhook.site/e6249d0a-ed68-4b71-9d09-dc694acb34e4"
 }'

Initially you'll get an immediate feedback like the one below

Response

  • statusCode: [string] The status of the request.

  • message: [string] A message describing the outcome of the request.

  • version: [string] API version number

  • timestamp: [datetime] The ID of the initiated task.

{
    "statusCode":200,
    "data":
        {
            "message":"Fetching available dates, callback url will be called to https://webhook.site/eccf1ed3-d2b2-4190-bf86-62f08e9bda3a when done",
            "version":"v1.0",
            "timestamp":"2024-03-04T13:18:19.557515"
        }
}

Later after successful execution, your endpoint will be called and you'll get the one below 

{
    "statusCode":200,
    "data": {
        "area_hectares": 924.1013977515,
        "available_dates": [
            {
                "cloud_cover": 1,
                "data_source": "S2B_32VPN_20231001_0_L2A",
                "date": "2023-10-01T00:00:00.000Z",
                "mgrs": "32VPN"
            },
            {
                "cloud_cover": 0.11560557173211615,
                "data_source": "S2A_32VPN_20231002_0_L2A",
                "date": "2023-10-02T00:00:00.000Z",
                "mgrs": "32VPN"
            },
            {
                "cloud_cover": 0.20893995435586685,
                "data_source": "S2B_32VPN_20231004_0_L2A",
                "date": "2023-10-04T00:00:00.000Z",
                "mgrs": "32VPN"
            },
            {
                "cloud_cover": 1,
                "data_source": "S2A_32VPN_20231006_0_L2A",
                "date": "2023-10-06T00:00:00.000Z",
                "mgrs": "32VPN"
            },
            {
                "cloud_cover": 1,
                "data_source": "S2B_32VPN_20231007_0_L2A",
                "date": "2023-10-07T00:00:00.000Z",
                "mgrs": "32VPN"
            }
        ],
    }
    "version":"v1.0",
    "status": "SUCCESS",
    "timesetamp":"2023-08-02T03:17:23.340688"
}

POST /deep-resolution

This endpoint provides deep resolution data for a specified bounding box over a given date range.

Request URL POST https://api.digifarm.io/deep-resolution

Method: POST

Request Headers

Content-Type: application/json

Request Body

  • client_token: [string, required] The client token for authorization.

  • bbox: [object, optional] The bounding box coordinates.

    • x_min: [float, required] The minimum longitude.
    • y_min: [float, required] The minimum latitude.
    • x_max: [float, required] The maximum longitude.
    • y_max: [float, required] The maximum latitude.

  • aoi: [object, optional] The GeoJSON format. We have only enabled Polygon and MultiPolygon single geometry GeoJson functionality for our API. Check the valid GeoJSON instructions here.

NOTE: At least need to provide either bbox or aoi. If provide both aoi and bbox, aoi has more precedence.

  • cloud_cover: [integer, required] The maximum allowed cloud cover percentage.

  • interval: [integer, optional] The frequency of image processing, in days. If the interval is not provided, the system will check available images every day.

  • start_date: [string, optional] The start date in ISO 8601 format. If start_date is not provided in the request body, the system will assume the current date is the start_date.

  • end_date: [string, optional] The end date in ISO 8601 format. It possible to provide future date as end_date. System will look for new image after every interval day.

  • callback_url: [string, required] The URL to call with the results.

  • dates: [list of string, optional] The dates to use for processing the area of interest.

IMPORTANT:

  • At least dates is required, or, alternatively, end_date.
  • If start_date and end_date are provided, all available dates in between will be processed.

  • If any future date provide as end_date, automatically image will process after every interval day based on the cloud cover.


Example Request

curl -X POST "https://api.digifarm.io/deep-resolution" \
 -H "Content-Type: application/json" \
 -d '{
 "bbox": {
    "x_min": 11.16545302951809,
    "y_min": 60.73687126373886,
    "x_max": 11.21197326267199,
    "y_max": 60.75331374707744
 },
 "aoi": { "type": "Feature", "properties": { "id": 1 }, "geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ 138.629423808807388, 35.396884261237581 ], [ 138.627417448995601, 35.396586287008105 ], [ 138.627417448995601, 35.396586287008105 ], [ 138.626682445896222, 35.39814568547569 ], [ 138.627169137137685, 35.399148865381584 ], [ 138.627477043841481, 35.399446839611059 ], [ 138.627993532505911, 35.399466704559693 ], [ 138.628281574261081, 35.399516366931273 ], [ 138.62859941343919, 35.399367379816532 ], [ 138.628807995399796, 35.398989945792529 ], [ 138.629125834577906, 35.398801228780535 ], [ 138.629821107780032, 35.398890621049375 ], [ 138.630417056238969, 35.398890621049375 ], [ 138.631161991812661, 35.398413862282212 ], [ 138.63163875057981, 35.398552916922633 ], [ 138.631608953156871, 35.398890621049375 ], [ 138.631241451607195, 35.399029675689796 ], [ 138.630844152634552, 35.399466704559693 ], [ 138.629890635100224, 35.399655421571694 ], [ 138.62936421396148, 35.400360627248112 ], [ 138.629523133550549, 35.400787723643695 ], [ 138.629632390768023, 35.40094664323275 ], [ 138.629602593345084, 35.401135360244751 ], [ 138.629185429423814, 35.4013538746797 ], [ 138.629016577360431, 35.401473064371487 ], [ 138.628976847463179, 35.401721376229382 ], [ 138.629562863447802, 35.402416649431487 ], [ 138.630019757266325, 35.402645096340756 ], [ 138.631013004697934, 35.402913273147277 ], [ 138.631350708824669, 35.4033006396456 ], [ 138.631946657283606, 35.402823880878437 ], [ 138.63195658975792, 35.402645096340756 ], [ 138.632075779449707, 35.402257729842439 ], [ 138.632701525331612, 35.401502861794434 ], [ 138.633625245442971, 35.401542591691694 ], [ 138.633486190802557, 35.401880295818437 ], [ 138.633595448020031, 35.402088877779065 ], [ 138.634529100605732, 35.403211247376753 ], [ 138.634469505759824, 35.40478057831865 ], [ 138.634688020194773, 35.404949430382025 ], [ 138.635552145460252, 35.405038822650866 ], [ 138.636356675879824, 35.405446054097816 ], [ 138.636585122789086, 35.405058687599499 ], [ 138.636465933097298, 35.404830240690231 ], [ 138.636942691864476, 35.404125035013813 ], [ 138.636833434647002, 35.40379726336139 ], [ 138.636654650109307, 35.403608546349389 ], [ 138.637886276924462, 35.402436514380121 ], [ 138.636604987737712, 35.398155617950003 ], [ 138.629423808807388, 35.396884261237581 ] ] ] ] } },
 "cloud_cover": 70,
 "interval": 5
 "end_date": "2024-01-01T00:00:00",
 "client_token": "********************************",
 "callback_url": "https://webhook.site/e6249d0a-ed68-4b71-9d09-dc694acb34e4"
 }'

Response

  • statusCode: [string] The status of the request.

  • message: [string] A message describing the outcome of the request.

  • version: [string] API version number

  • timestamp: [datetime] The ID of the initiated task.

{
    "statusCode":200,
    "data": {
        "message":"Job queued",
        "job_id":"037d4b03-0b7a-46b5-b618-f81bdbe08739"
    },
    "version":"v1.0",
    "timesetamp":"2023-08-02T03:17:23.340688"
}

Important to note that the processing endpoint (/deep-resolution) has a guard code to prevent AOIs larger or smaller than the current limit (min. 3 hectares, max. 25.000 hectares) and returns a specific error in those cases.

Example Request

    curl -X POST "https://api.digifarm.io/deep-resolution" \
        -H "Content-Type: application/json" \
        -d '{
        "bbox": {
        "x_min": 0.0,
        "y_min": 0.0,
        "x_max": 0.15603603603603605,
        "y_max": 0.15603603603603605
        },
        "cloud_cover": 70,
        "data_cover": 70,
        "start_date": "2023-10-01T00:00:00",
        "end_date": "2024-01-01T00:00:00",
        "client_token": "********************************",
        "callback_url": "https://webhook.site/e9062ce5-f2a5-4f63-8f03-10696be609c9"
    }'


{
    "statusCode":200,
    "data":{
        "detail":"AOI must be between 3 and 25,000 hectares. Given area: 29969.1494036403 hectares."
    },
    "version":"v1.0",
    "timesetamp":"2023-08-02T03:17:23.340688"
}

GET /deep-resolution/status/{job_id}

This endpoint provides available dates for deep resolution imagery within a specified bounding box and time range.

Request URL GET https://api.digifarm.io/deep-resolution/status/{job_id}

Method: GET

Request Headers

Content-Type: application/json

client_token: [string, required] The client token for authorization.

Example Request

curl -X GET "https://api.digifarm.io/deep-resolution/status/5fb2d945-adc2-41e0-9a26-d5ef0613cc43" -H "client_token: ********************************"

Response

  • statusCode: [string] The status of the request.

  • data: [object] Dictionary contaning dates and job_id

    • job_id: [string] The job id.

    • status: [string] The status of job. It can be ACTIVE or CANCELLED.

    • dates: [list] The list of requested image.

  • version: [string] API version number

  • timestamp: [datetime] The time of the initiated task.

NOTE: The job status will be ACTIVE if the system is still looking for new images. If the user cancels the job using the cancel API, the status will be CANCELLED. Otherwise, if all processes are completed, the system will remove the status value from the response payload.


    {
        "statusCode": 200,
        "data": {
            "job_id": "5fb2d945-adc2-41e0-9a26-d5ef0613cc43",
            "dates": [
                {
                    "date": "2023-03-14T00:00:00.000Z",
                    "status": "PROCESSED",
                    "link": "https://digi-data-v1.s3.eu-central-1.amazonaws.com/partial-dr/16ecf247-3e11-43b9-add1-407771f2c7b5/5fb2d945-adc2-41e0-9a26-d5ef0613cc43/32TMK/2023-03-14_MS.tif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAZG6BNOQIGMVWC5LP%2F20240607%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240607T092647Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGIaDGV1LWNlbnRyYWwtMSJGMEQCICOLZjM%2FXryqUjH%2FUn68leQnAGSCDQDobAN5T%2BdLyAdtAiBpEnGfuBjEsPGL2yn1RvT1yuH%2FqTEcsRppMVLNNdGNMCq%2FAwjr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDYzMzM3NjQzNzI2NCIMotLmGKnY5s8GbfwZKpMDfUUa8tafcuQ3godhmP%2BdKnRKCYleRe6y%2BZkJq%2FFuRYNdEQQ1kiWW4EQgHNgExZqMrciLjNZfInXNR8VVa1bg2ZKPqtIMow%2F2OkpMzJV95NBqKvVauaUIqpQuVbtX1iThKzk%2FE6CO3xRLkc6hFiSHzuZ5kDfBu2xjbe8zitoZkChnW2Ret3ZMf6aLbexL0MIvyrn0oZcXPQhEXtERiuSiqagrQ3Df6lAsCpbSleqevgXerTpCPByzR0EVDwoJpJrTHZkz5EKxlTmrNdg2FLJbiIb%2Fa5F0dKnSvKbLt4dI2iAzM1e12V7mizQ7dMmHYk513HQ7SKS3PX8AgqDi0JlXCZmg5t6kSzoyqHFRAT2d8zCUHV0sh%2BNAhsKWpFoFkJni2x01LUBEpBm4H7FbQUB%2B39cwZlXjfOBtsF%2FiCDR7kp6zbthBGo5ysdHELntKRfy8TuQUPoLhLN%2F98xAM7ImfmuGw76sn6K%2FZsvczSaSZK9c%2FGvFyOEcdqunxgpBheN8FDc8UiWA%2F2TTbCG%2F4x0AieGbQ3zDKpIuzBjqfAQ9S9e8jpgzjMM4GO8fqyObbWONrbklkDyiMiDCZOOaunx2i2DvZ7Jz7E0nGO7ToXwzAvEb1qeNQAWWeHe4OJ8kQOw0oV6dkS15ObZHKlJTPvPqXOtJ5axP409KVnnzrPwTUqG0BAp4fCR5z%2BmOC1LkbjJo94AEhljmi8ewd5B9JkISrn1NJTHK9xT6SkucR8u92uqwUiyvbdfXOyRKRBw%3D%3D&X-Amz-Signature=c66d44b3afd56837ce20087b5f14f8674da5bdc60f52adf3c2fd7e7e54943abd&X-Amz-SignedHeaders=host"
                },
                {
                    "date": "2023-02-22T00:00:00.000Z",
                    "status": "PROCESSED",
                    "link": "https://digi-data-v1.s3.eu-central-1.amazonaws.com/partial-dr/16ecf247-3e11-43b9-add1-407771f2c7b5/5fb2d945-adc2-41e0-9a26-d5ef0613cc43/32TMK/2023-02-22_MS.tif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAZG6BNOQIGMVWC5LP%2F20240607%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240607T092647Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGIaDGV1LWNlbnRyYWwtMSJGMEQCICOLZjM%2FXryqUjH%2FUn68leQnAGSCDQDobAN5T%2BdLyAdtAiBpEnGfuBjEsPGL2yn1RvT1yuH%2FqTEcsRppMVLNNdGNMCq%2FAwjr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDYzMzM3NjQzNzI2NCIMotLmGKnY5s8GbfwZKpMDfUUa8tafcuQ3godhmP%2BdKnRKCYleRe6y%2BZkJq%2FFuRYNdEQQ1kiWW4EQgHNgExZqMrciLjNZfInXNR8VVa1bg2ZKPqtIMow%2F2OkpMzJV95NBqKvVauaUIqpQuVbtX1iThKzk%2FE6CO3xRLkc6hFiSHzuZ5kDfBu2xjbe8zitoZkChnW2Ret3ZMf6aLbexL0MIvyrn0oZcXPQhEXtERiuSiqagrQ3Df6lAsCpbSleqevgXerTpCPByzR0EVDwoJpJrTHZkz5EKxlTmrNdg2FLJbiIb%2Fa5F0dKnSvKbLt4dI2iAzM1e12V7mizQ7dMmHYk513HQ7SKS3PX8AgqDi0JlXCZmg5t6kSzoyqHFRAT2d8zCUHV0sh%2BNAhsKWpFoFkJni2x01LUBEpBm4H7FbQUB%2B39cwZlXjfOBtsF%2FiCDR7kp6zbthBGo5ysdHELntKRfy8TuQUPoLhLN%2F98xAM7ImfmuGw76sn6K%2FZsvczSaSZK9c%2FGvFyOEcdqunxgpBheN8FDc8UiWA%2F2TTbCG%2F4x0AieGbQ3zDKpIuzBjqfAQ9S9e8jpgzjMM4GO8fqyObbWONrbklkDyiMiDCZOOaunx2i2DvZ7Jz7E0nGO7ToXwzAvEb1qeNQAWWeHe4OJ8kQOw0oV6dkS15ObZHKlJTPvPqXOtJ5axP409KVnnzrPwTUqG0BAp4fCR5z%2BmOC1LkbjJo94AEhljmi8ewd5B9JkISrn1NJTHK9xT6SkucR8u92uqwUiyvbdfXOyRKRBw%3D%3D&X-Amz-Signature=bc2eba998d65b51a4d5c0827d51269e8089abac22f114d8fcdbca13c38987724&X-Amz-SignedHeaders=host"
                },
                {
                    "date": "2023-01-28T00:00:00.000Z",
                    "status": "PROCESSED",
                    "link": "https://digi-data-v1.s3.eu-central-1.amazonaws.com/partial-dr/16ecf247-3e11-43b9-add1-407771f2c7b5/5fb2d945-adc2-41e0-9a26-d5ef0613cc43/32TMK/2023-01-28_MS.tif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAZG6BNOQIGMVWC5LP%2F20240607%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240607T092647Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGIaDGV1LWNlbnRyYWwtMSJGMEQCICOLZjM%2FXryqUjH%2FUn68leQnAGSCDQDobAN5T%2BdLyAdtAiBpEnGfuBjEsPGL2yn1RvT1yuH%2FqTEcsRppMVLNNdGNMCq%2FAwjr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDYzMzM3NjQzNzI2NCIMotLmGKnY5s8GbfwZKpMDfUUa8tafcuQ3godhmP%2BdKnRKCYleRe6y%2BZkJq%2FFuRYNdEQQ1kiWW4EQgHNgExZqMrciLjNZfInXNR8VVa1bg2ZKPqtIMow%2F2OkpMzJV95NBqKvVauaUIqpQuVbtX1iThKzk%2FE6CO3xRLkc6hFiSHzuZ5kDfBu2xjbe8zitoZkChnW2Ret3ZMf6aLbexL0MIvyrn0oZcXPQhEXtERiuSiqagrQ3Df6lAsCpbSleqevgXerTpCPByzR0EVDwoJpJrTHZkz5EKxlTmrNdg2FLJbiIb%2Fa5F0dKnSvKbLt4dI2iAzM1e12V7mizQ7dMmHYk513HQ7SKS3PX8AgqDi0JlXCZmg5t6kSzoyqHFRAT2d8zCUHV0sh%2BNAhsKWpFoFkJni2x01LUBEpBm4H7FbQUB%2B39cwZlXjfOBtsF%2FiCDR7kp6zbthBGo5ysdHELntKRfy8TuQUPoLhLN%2F98xAM7ImfmuGw76sn6K%2FZsvczSaSZK9c%2FGvFyOEcdqunxgpBheN8FDc8UiWA%2F2TTbCG%2F4x0AieGbQ3zDKpIuzBjqfAQ9S9e8jpgzjMM4GO8fqyObbWONrbklkDyiMiDCZOOaunx2i2DvZ7Jz7E0nGO7ToXwzAvEb1qeNQAWWeHe4OJ8kQOw0oV6dkS15ObZHKlJTPvPqXOtJ5axP409KVnnzrPwTUqG0BAp4fCR5z%2BmOC1LkbjJo94AEhljmi8ewd5B9JkISrn1NJTHK9xT6SkucR8u92uqwUiyvbdfXOyRKRBw%3D%3D&X-Amz-Signature=2063af4c6829b2c1ae34f030e24acb19f04fb4e5f4e9d85de38a55ec07ceca36&X-Amz-SignedHeaders=host"
                }
            ]
        },
        "version": "v1.0",
        "timestamp": "2024-06-07T09:26:47.881040"
    }

POST /deep-resolution/cancel/{job_id}

This endpoint provides the ability to cancel any image requests.

Request URL POST https://api.digifarm.io/deep-resolution/cancel/{job_id}

Method: POST

Request Headers

Content-Type: application/json

client_token: [string, required] The client token for authorization.

Example Request

curl -X GET "https://api.digifarm.io/deep-resolution/cancel/5fb2d945-adc2-41e0-9a26-d5ef0613cc43" -H "client_token: ********************************"

Response

  • statusCode: [string] The status of the request.

  • data: [object] Dictionary contaning dates and job_id

    • job_id: [string] The job id.

    • status: [string] The status of job.

  • version: [string] API version number

  • timestamp: [datetime] The time of the initiated task.

{
    "statusCode": 200,
    "data": {
        "job_id": "5fb2d945-adc2-41e0-9a26-d5ef0613cc43",
        "status": "CANCELLED"
    },
    "version": "v1.0",
    "timestamp": "2025-01-23T12:15:43.221783"
}

Error Response

In case of errors, the API will return an HTTP status code and a JSON object containing an error message.

Condition: If fields are missing or the data is in the wrong format.

Code: 400 BAD REQUEST

Content Example:

Type json

{
  "statusCode":400,
  "data":{
      "message": "Bad request. Invalid input data. Please provide all fields in correct format."
  },
  "version":"v1.0",
  "timestamp": "Current timestamp"
}

Condition: If the 'client_token' is missing or invalid.

Code: 401 UNAUTHORIZED

Content Example:

json

{
  "statusCode":401,
  "data":{
      "message": "Unauthorized. Invalid client token."
  },
  "version":"v1.0",
  "timestamp": "Current timestamp"
}

Condition: If there's a problem initiating the task.

Code: 500 INTERNAL SERVER ERROR

Content Example:

json

"statusCode":500,
"data":{
    "message": "Internal Server Error. Could not initiate task due to an internal server error. Please try again later."
},
"version":"v1.0",
"timestamp": "Current timestamp"

Webhook Service + Ondemand + Deep Resolution

Overview

The On demand Webhook API provides a way for your application to interact with our service, notifying clients of the completion of tasks. It allows you to register URL endpoints (webhooks) to which we will send notifications regarding specific events happening within our system. When a job is completed, the API makes a POST request to the callback_url that was specified in the original request.

Webhook Event

Task Completion

When a task is completed, a POST request will be sent to the specified callback_url. Please ensure your API service is ready to accept POST requests at the callback URL you provide.

Request Headers

  • Content-Type: application/json

  • X-Digifarm-Signature: A HMAC SHA256 signature computed from the payload and a shared secret, providing a way to ensure the request is from On demand API.

Request Body

  • job_id: [string] The ID of the completed task.

  • statusCode: [string] The http status code of the task.

  • data: [object] The result of the task. This will be present if the task completed successfully.

    • filename: [string] The minimum longitude.

    • link: [string] Presigned S3 URL to download the output file

    • job_id: [string] Job ID of the requested file

    • status: [string] Job ID of the requested file

    • timestamp: [string] Current timestamp of the results

    • version: [string] Current version of the API

{

    "statusCode":200,
    "data": {
        "filename": "2023-11-21_MS.tif",
        "job_id": "43288813-5b43-4b6b-a242-1fa35de35a04",
        "link": "https://digi-data-v1.s3.amazonaws.com/partial-dr/070bd981-197e-4868-bd53-25871f62c76a/43288813-5b43-4b6b-a242-1fa35de35a04/32VPN/2023-11-21_MS.tif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAZG6BNOQIDEMAZT7N%2F20240303%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240303T134949Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGUaDGV1LWNlbnRyYWwtMSJIMEYCIQDE1T0VMDp%2BmXcqnL2J5qlqxrZ2M%2F%2FulGLz8cZaW%2F%2FF%2BAIhAPb30hNjI1DMHO7LCsyKU55iFQ8K6XmTsKIRFnxtkbXqKsQDCF4QAhoMNjMzMzc2NDM3MjY0IgybLKgAEgxb6DB4Us8qoQNcmnPljLVvZSczUSjubZQXyYuVKo4HPMmcjEQUWVtvdjYy0YNJNJhGSrHWb0pPrsQSqEOvJoVH1WN%2BcK3EUKZ%2FM6t7u8Fi1kBakiBboAKbeWB7onA%2F9GCbcA%2BpAAk8Tlz5x34VZXqYF9fJA56cRvL53JPLo%2BPF9W6PPI%2FuDb%2B9sryGjXE18X5klaXNapUvZXlbc2imnM1ZFJA7fkHp3JFRZW%2BL72PALFwNBfYOBdQtz4eQZta%2Fs%2FZXXjuZ%2Fox3jiUbFPBlwyNs7nY0JMkxIcOzsOYct%2F6Qif3lwQ1%2FL6O0zw09oOdy1fwmJceVu0Bj9d%2FnHRFX90wMuBZ%2FLe0oh7eYY3hqWJa9BzM8Fv5OdNzvGLnx9bTLQ1TDfQl%2FA9eqshOv%2Bgj8nAsg9QZzKBz1X9uKJli7MGWxvYms43XChhjhh%2B%2FpkmRrWtXev3tJO9WJW6Z7iOeKvLf73Pa4YmtBxqgpBLqejmum80Uiu7zZSFDaUWUW5CXGVvC8lBuJ0Hz6HTEx7zjdQQ%2B0jrNUOlmctIjQ3r5y1obNKlMcwIOEtOhHW2QwsPCRrwY6nQEWWa2Wv2kP3pTj9ZxZGb56v8UoXlfqJseRlV0UXPMJxn8hclkLRPZ3M9jHQ6JcG4r7a9ByWrDGZDyd2fs%2FkF4ZKK6sjIABTdFH9mrKKCxaaEYrPS0JJ60hB2ybEgEHuBldA3BV5NHeGYr0fUP%2BcMxc9B4hI6t5W9neSUyRAlczkZyVDdnmqWrlDgn92mZgrcK1nuqxgT3tswEv8TLh&X-Amz-Signature=178e829de21ed7b4ebdeacb4034eb75f6b9e538ce737dbc64a5814fff43e1fb6",
        "status": "success",
        "timestamp": "2024-03-03T13:49:49.290596",
        "version": "v1.0"
    }
}

Security

Webhook delivery uses HTTPS to encrypt data during transmission. You may want to set up your endpoint to verify that incoming webhooks are from us.

Verification

We will include a signature in each webhook event's HTTP headers. The header key is X-Digifarm-Signature. Your application can use this signature to verify the request was sent our On demand API. The value of this header is computed by generating a HMAC SHA256 hash of the payload using your client token as the key.

Here's an example in Python showing how you could verify a webhook request:

import hmac
import hashlib

def is_valid_signature(x_digifarm_signature, data, client_token):
    payload_str = json.dumps(data.dict(), sort_keys=True)
    expected_signature = hmac.new(
        client_token.encode(),
        msg=payload_str.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, x_digifarm_signature)

Error Handling

If there's an error during the processing of the task, the webhook request will still be sent, but the statusCode field will be error and the message field will contain information about the error.

Condition: If there's a problem processing the callback request.

Code: 400 BAD REQUEST

Content Example:

"statusCode":400,
"data":{
    "data": {
        "job_id": "fdj4hi8e-3ds4-kl3d-fk4d-4dk3ji8e9sdf",
        "version": "v1.0",
        "error": "Bad Request. There was an error processing the task.",
        "timestamp": "Current timestamp"
    },
},

Instructions for valid GeoJSON Format

Instructions for Polygon Feature
  1. Coordinates length should always be one.
  2. There should not be more than one feature.
  3. There should always be only one geometry type.
{
    "type": "Feature",
    "properties": {},
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [],
                [],
                [],
                []
            ]
        ]
    }
}
Instructions for MultiPolygon FeatureCollection
  1. Coordinates length should always be one and should be in the provided format.
  2. There should not be more than one feature.
  3. There should always be only one geometry type.
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {},
            "geometry": {
                "coordinates": [
                    [
                        [
                            [],
                            [],
                            [],
                            []
                        ]
                    ]
                ],
                "type": "MultiPolygon"
            }
        }
    ]
}
Instructions for MultiPolygon Feature
  1. Coordinates length should always be one and should be in the provided format.
  2. There should not be more than one feature.
  3. There should always be only one geometry type.
{
    "type": "Feature",
    "properties": {},
    "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [],
                    [],
                    [],
                    []
                ]
            ]
        ]
    }
}
Instructions for Polygon FeatureCollection
  1. Coordinates length should always be one.
  2. There should not be more than one feature.
  3. There should always be only one geometry type.
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {},
            "geometry": {
                "coordinates": [
                    [
                        [],
                        [],
                        [],
                        []
                    ]
                ],
                "type": "Polygon"
            }
        }
    ]
}

FAQ

Q: What HTTP status codes should I return? Our service considers any status code between 200 and 299 as a success. Other status codes will be considered as a failure.

Q: How can I verify that the request came from your service? We include a signature in each HTTP header. You can use this signature to verify that the request came from our service.