Examples of Third Party Data Import

The first example below demonstrates the import of PlanetScope data and the second one the import of Pleiades data. We included the examples of both Simple and Native search so that you can compare their interfaces even though both would usually not be used in the same workflow. Similar applies for the examples of Order products and of Order using query. The requests are given in Python. To execute them you need to create an OAuth client as is explained here. It is named oauth in these examples.

A Postman collection with examples can be downloaded here. The examples as provided are demonstrational, thus you can try out the whole workflow free of charge and do not need to set PLANET_API_KEY (except for the search requests for PlanetScope data) as long as you do not modify the input objects of the data orders. You will also need a SH access token to run the examples successfully.

For more detailed explanations, follow our step by step tutorial on ordering and visualizing commercial data using Postman.

Get your quota

url = "https://services.sentinel-hub.com/api/v1/dataimport/quotas"
response = oauth.get(url=url)
response.raise_for_status()
response.json()

PlanetScope data import

Search

Provide your Planet API key in <planetApiKey>, set the field provider to "PLANET" and run one of the examples below.

Simple Search

For PlanetScope simple search, data.itemType must be set to "PSScene4Band".

url = "https://services.sentinel-hub.com/api/v1/dataimport/search"
query = {
    "provider": "PLANET",
    "planetApiKey": <PlanetApiKey>,
    "bounds": {
        "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  15.825815,
                  46.714048
                ],
                [
                  15.813988,
                  46.707248
                ],
                [
                  15.832682,
                  46.703062
                ],
                [
                  15.839931,
                  46.711694
                ],
                [
                  15.835353,
                  46.716664
                ],
                [
                  15.825815,
                  46.714048
                ]
              ]
           ]
        }
    },
    "data": [
        {
            "itemType": "PSScene4Band",
            "dataFilter": {
                "timeRange": {
                    "from": "2019-04-27T00:00:00.000Z",
                    "to": "2019-04-30T00:00:00.000Z"
                },
                "maxCloudCoverage": 30,
                "nativeFilter": {
                    "type": "StringInFilter",
                    "field_name": "quality_category",
                    "config": [
                        "standard"
                    ]
                }
            }
        }
    ]
}
response = oauth.post(url, json=query)
response.raise_for_status()
results = response.json()

To get product ids:

item_ids = [feature["id"] for feature in results["features"]]

Native Search

This native search is equivalent to the above simple search. Search for PlanetScope is requested by the inclusion of "PSScene4Band" in the native search field item_types in native searches. Note also the added Planet-specific filters PermissionFilter and AssetFilter.

url = "https://services.sentinel-hub.com/api/v1/dataimport/nativesearch"
payload = {
    "provider": "PLANET",
    "planetApiKey": <PlanetApiKey>,
    "item_types": [
        "PSScene4Band"
    ],
    "filter": {
        "type": "AndFilter",
        "config": [
            {
                "type": "GeometryFilter",
                "field_name": "geometry",
                "config": {
                    "type": "Polygon",
                    "coordinates": [
                      [
                        [
                          15.825815,
                          46.714048
                        ],
                        [
                          15.813988,
                          46.707248
                        ],
                        [
                          15.832682,
                          46.703062
                        ],
                        [
                          15.839931,
                          46.711694
                        ],
                        [
                          15.835353,
                          46.716664
                        ],
                        [
                          15.825815,
                          46.714048
                        ]
                      ]
                   ]
                }
            },
            {
                "type": "DateRangeFilter",
                "field_name": "acquired",
                "config": {
                    "gte": "2019-04-27T00:00:00.000Z",
                    "lte": "2019-04-30T00:00:00.000Z"
                }
            },
            {
                "type": "RangeFilter",
                "field_name": "cloud_cover",
                "config": {
                    "lte": 0.3
                }
            },
            {
                "type": "StringInFilter",
                "field_name": "quality_category",
                "config": [
                    "standard"
                ]
            },
            {
                "type" : "PermissionFilter",
                "config" : [ "assets:download" ]
            },
            {
                "type" : "AssetFilter",
                "config" : [ "analytic" ]
            }
        ]
    }
}
response = oauth.post(url, json=payload)
response.raise_for_status()
results = response.json()

To get product ids:

item_ids = [feature["id"] for feature in results["features"]]

Thumbnail

After searching for data, you can check the thumbnail of each item by entering the item id into the url of the thumbnail request:

item_id = '20190427_093732_22_105d' 
# or get it from search results: item_id = item_ids[0]
url = f"https://services.sentinel-hub.com/api/v1/dataimport/collections/PLANET_SCOPE/products/{item_id}/thumbnail"
response = oauth.get(url)

The thumbnail can be displayed in Python using:

import io
from PIL import Image
image_bytes = io.BytesIO(response.content)
Image.open(image_bytes)

Order

To order PlanetScope data, set provider to "PLANET" data.itemType to "PSScene4Band".

Order products

To order the import of the products, which we got as a result of search and are stored in the variable item_ids:

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
payload = {
    "name": "planet products",
    "input": {
        "provider": "PLANET",
        "planetApiKey": "",
        "bounds": {
             "geometry": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      15.825815,
                      46.714048
                    ],
                    [
                      15.813988,
                      46.707248
                    ],
                    [
                      15.832682,
                      46.703062
                    ],
                    [
                      15.839931,
                      46.711694
                    ],
                    [
                      15.835353,
                      46.716664
                    ],
                    [
                      15.825815,
                      46.714048
                    ]
                  ]
               ]
            }
        },
        "data": [
            {
                "itemType": "PSScene4Band",
                "productBundle": "analytic",
                "itemIds": item_ids
            }
        ]
    }
}
response = oauth.post(url, json=payload)
response.raise_for_status()
results = response.json()

Order using query

Another way to order data is using search query, in this case using the query from above:

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
query['data'][0]["productBundle"] = "analytic"
payload = {
    "name": "some name",
    "input": query
}
response = oauth.post(url, json=payload)
response.raise_for_status()
order = response.json()

To extract the order id from the response:

order_id = order['id']

To extract the cost in square kilometers:

sqkm = order['sqkm']

Confirm the order

Confirming the order will subtract the ordered area in km² from your quota. To initiate import, confirm the order:

url = f"https://services.sentinel-hub.com/api/v1/dataimport/orders/{order_id}/confirm"
response = oauth.post(url)
response.raise_for_status()

Get order information

url = f"https://services.sentinel-hub.com/api/v1/dataimport/orders/{order_id}"
response = oauth.get(url)
response.raise_for_status()
order = response.json()

To extract the order status:

status = order['status']

To extract the BYOC collection ID:

collection_id = order['collectionId']

List all your orders

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
response = oauth.get(url)
response.raise_for_status()
response.json()

Access PlanetScope data in a BYOC collection and process a truecolor image

This is a normal Process API request that uses a BYOC collectionId that can be fetched from the get order information request.

response = oauth.post('https://services.sentinel-hub.com/api/v1/process',
  headers={"Authorization" : "Bearer <your_access_token>"},
  json={
    'input': {
        "bounds": {
            "properties": {
                "crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
            },
            "bbox": [562218,5174019,564201,5172501]
        },
        "data": [{
            "type": "byoc-<collectionId>",
            "dataFilter": {
                "timeRange": {
                    "from": "2019-04-27T00:00:00Z",
                    "to": "2019-04-28T00:00:00Z"
                }
            }
        }
        ]
    },
    "output": {
        "width": 512,
        "height": 512
    },
    "evalscript": """
        //VERSION=3
        function setup() {
            return {
                input: [{"bands": ["B1", "B2", "B3","dataMask"]}],
                output: { bands: 4}
            };
        }
        var f = 10000;
        function evaluatePixel(sample) {
            return [sample.B3/f*2.5, sample.B2/f*2.5, sample.B1/f*2.5, sample.dataMask];
        }
    """
  }
)

Demo order

We prepared a demo order that is free of charge (no quota is used) for service testing. This order does not require a Planet API key. Except for the order name, it must be used exactly as given here, otherwise it is not a demo order anymore. After sending the request, extract the order id as shown above in order to confirm the demo order. Follow the other steps to request the PlanetScope sample image.

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
payload = {
    "name": "planet products",
    "input": {
        "provider": "PLANET",
        "planetApiKey": "",
        "bounds": {
             "geometry": {
                "type": "Polygon",
                "coordinates": [
                  [
                    [
                      15.825815,
                      46.714048
                    ],
                    [
                      15.813988,
                      46.707248
                    ],
                    [
                      15.832682,
                      46.703062
                    ],
                    [
                      15.839931,
                      46.711694
                    ],
                    [
                      15.835353,
                      46.716664
                    ],
                    [
                      15.825815,
                      46.714048
                    ]
                  ]
               ]
            }
        },
        "data": [
            {
                "itemType": "PSScene4Band",
                "productBundle": "analytic",
                "harmonizeTo": "NONE",
                "itemIds": [
                    "20190427_093734_25_105d",
                    "20190427_093732_22_105d"
                ]
            }
        ]
    }
}
response = oauth.post(url, json=payload)
response.raise_for_status()
order = response.json()

Pleiades and SPOT data import

Search

Simple Search

To search for Pleiades data, set data.constellation to "PHR", and for SPOT data, set it to "SPOT". In both cases provider must be set to "AIRBUS".

url = "https://services.sentinel-hub.com/api/v1/dataimport/search"
query = {
    "provider": "AIRBUS",
    "bounds": {
        "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  15.825815,
                  46.714048
                ],
                [
                  15.813988,
                  46.707248
                ],
                [
                  15.832682,
                  46.703062
                ],
                [
                  15.839931,
                  46.711694
                ],
                [
                  15.835353,
                  46.716664
                ],
                [
                  15.825815,
                  46.714048
                ]
              ]
            ]
          }
    },
    "data": [
        {
            "constellation": "PHR",
            "dataFilter": {
                "timeRange": {
                    "from":"2017-09-13T10:00:00.00Z",
                    "to":  "2017-09-13T11:00:00.00Z"
                }
            }
        }
    ]
}
response = oauth.post(url, json=query)
response.raise_for_status()
results = response.json()

To get product ids:

item_ids = [feature["properties"]["id"] for feature in results["features"]]

Please note: Airbus search can return products that don't overlap with the given area of interest. However, orders that include such non-overlapping products are rejected by Airbus. Therefore, Sentinel Hub automatically filters out those products from simple search and when ordering products using a query. Native search, on the other hand, functions purely as a proxy search, thus we don't filter products nor modify responses in other ways.

Native Search

This native search is equivalent to the above simple search. Note the added Airbus-specific field processingLevel.

url = "https://services.sentinel-hub.com/api/v1/dataimport/nativesearch"
payload = {
    "provider": "AIRBUS",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              15.825815,
              46.714048
            ],
            [
              15.813988,
              46.707248
            ],
            [
              15.832682,
              46.703062
            ],
            [
              15.839931,
              46.711694
            ],
            [
              15.835353,
              46.716664
            ],
            [
              15.825815,
              46.714048
            ]
         ]
      ]
    },
    "constellation": "PHR",
    "acquisitionDate": "[2017-09-13T10:00:00.000Z,2017-09-13T11:00:00.000Z]",
    "processingLevel" : "ALBUM,SENSOR"
}
response = oauth.post(url, json=payload)
response.raise_for_status()
results = response.json()

To get product ids:

item_ids = [feature["properties"]["id"] for feature in results["features"]]

To get info on how to use the native search, you can check this Airbus guide.

Thumbnail

After searching for data, you can check the thumbnail of each item by entering the item id into the url of the thumbnail request. The example below requests a thumbnail for Pleiades data. To request a thumbnail for SPOT data, replace the string AIRBUS_PLEIADES in the url with AIRBUS_SPOT.

item_id = '6701559b-e11e-43f9-b395-ac04f193a83b' 
# or get it from search results: item_id = item_ids[0]
url = f"https://services.sentinel-hub.com/api/v1/dataimport/collections/AIRBUS_PLEIADES/products/{item_id}/thumbnail"
response = oauth.get(url)

The thumbnail can be displayed in Python using:

import io
from PIL import Image
image_bytes = io.BytesIO(response.content)
Image.open(image_bytes)

Order

To order Pleaides data, set input.data.constellation to "PHR", and for SPOT data, set it to "SPOT". In both cases provider must be set to "AIRBUS".

Order products

To order the import of the products, which we got as a result of search and are stored in the variable item_ids:

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
payload = {
    "name": "airbus products",
    "input": {
        "provider": "AIRBUS",
        "bounds": {
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            15.825815,
                            46.714048
                        ],
                        [
                            15.813988,
                            46.707248
                        ],
                        [
                            15.832682,
                            46.703062
                        ],
                        [
                            15.839931,
                            46.711694
                        ],
                        [
                            15.835353,
                            46.716664
                        ],
                        [
                            15.825815,
                            46.714048
                        ]
                    ]
                ]
            }
        },
        "data": [
            {
                "constellation": "PHR",
                "products": [
                    {
                        "id": item_ids[0]
                    }
                ]
            }
        ]
    }
}
response = oauth.post(url, json=payload)
response.raise_for_status()
results = response.json()

Order using query

Another way to order data is using search query, in this case using query from above:

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
payload = {
    "name": "airbus query",
    "input": query
}
response = oauth.post(url, json=payload)
response.raise_for_status()
order = response.json()

To extract the order id from the response:

order_id = order['id']

To extract the cost in square kilometers:

sqkm = order['sqkm']

Confirm the order

Confirming the order will subtract the ordered area in km² from your quota.

To initiate import, confirm the order:

url = f"https://services.sentinel-hub.com/api/v1/dataimport/orders/{order_id}/confirm"
response = oauth.post(url)
response.raise_for_status()

Get order information

url = f"https://services.sentinel-hub.com/api/v1/dataimport/orders/{order_id}"
response = oauth.get(url)
response.raise_for_status()
order = response.json()

To extract the order status:

status = order['status']

To extract the BYOC collection ID:

collection_id = order['collectionId']

List all your orders

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
response = oauth.get(url)
response.raise_for_status()
response.json()

Access Pleiades data in a BYOC collection and process a truecolor image

This is a normal Process API request that uses a BYOC collectionId that can be fetched from the get order information request.

response = oauth.post('https://services.sentinel-hub.com/api/v1/process',
  headers={"Authorization" : "Bearer <your_access_token>"},
  json={
    'input': {
        "bounds": {
            "properties": {
                "crs": "http://www.opengis.net/def/crs/EPSG/0/32633"
            },
            "bbox": [562218,5174019,564201,5172501]
        },
        "data": [{
            "type": "byoc-<collectionId>",
            "dataFilter": {
                "timeRange": {
                    "from": "2017-09-13T00:00:00Z",
                    "to": "2017-09-13T23:59:59Z"
                }
            }
        }
        ]
    },
    "output": {
        "width": 512,
        "height": 512
    },
    "evalscript": """
        //VERSION=3
        function setup() {
            return {
                input: ["B0", "B1", "B2", "dataMask"],
                output: { bands: 4 }
            };
        }
        var f = 2000;
        function evaluatePixel(sample) {
            return [sample.B2/f, sample.B1/f, sample.B0/f, sample.dataMask];
        }
    """
  }
)

WorldView data import

Search

Simple Search

url = "https://services.sentinel-hub.com/api/v1/dataimport/search"
query = {
  "provider": "MAXAR",
  "bounds": {
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            15.81,
            46.70
          ],
          [
            15.84,
            46.70
          ],
          [
            15.84,
            46.72
          ],
          [
            15.81,
            46.72
          ],
          [
            15.81,
            46.70
          ]
        ]
      ]
    }
  },
  "data": [
    {
      "productBands": "4BB",
      "dataFilter": {
        "timeRange": {
          "from": "2020-11-06T00:00:00.0Z",
          "to": "2020-11-06T23:59:59.9Z"
        }
      }
    }
  ]
}
response = oauth.post(url, json=query)
response.raise_for_status()
results = response.json()

To get product ids:

item_ids = [feature["catalogID"] for feature in results["features"]]

Native Search

This native search is equivalent to the above simple search.

url = "https://services.sentinel-hub.com/api/v1/dataimport/nativesearch"
payload = {
    "provider": "MAXAR",
    "startDate": "2020-11-06",
    "endDate": "2020-11-07",
    "aoiInGeoJson": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            15.81,
            46.70
          ],
          [
            15.84,
            46.70
          ],
          [
            15.84,
            46.72
          ],
          [
            15.81,
            46.72
          ],
          [
            15.81,
            46.70
          ]
        ]
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    "geometry": "true"
}
response = oauth.post(url, json=payload)
response.raise_for_status()
results = response.json()

To get product ids:

item_ids = [feature["catalogID"] for feature in results["features"]]

Thumbnail

After searching for data, you can check the thumbnail of each item by entering the item id into the url of the thumbnail request:

item_id = '1040010063790D00' 
# or get it from search results: item_id = item_ids[0]
url = f"https://services.sentinel-hub.com/api/v1/dataimport/collections/MAXAR_WORLDVIEW/products/{item_id}/thumbnail"
response = oauth.get(url)

The thumbnail can be displayed in Python using:

import io
from PIL import Image
image_bytes = io.BytesIO(response.content)
Image.open(image_bytes)

Order

To order WorldView data, set provider to "MAXAR".

Order products

To order the import of the products, which we got as a result of search and are stored in the variable item_ids:

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
payload = {
  "name": "My WorldView order",
  "input": {
    "provider": "MAXAR",
    "bounds": {
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              15.81,
              46.70
            ],
            [
              15.84,
              46.70
            ],
            [
              15.84,
              46.72
            ],
            [
              15.81,
              46.72
            ],
            [
              15.81,
              46.70
            ]
          ]
        ]
      }
    },
    "data": [{
      "productBands": "4BB",
      "selectedImages": item_ids
    }]
  }
}
response = oauth.post(url, json=payload)
response.raise_for_status()
order = response.json()

Order using query

Another way to order data is using search query, in this case using the query from above:

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
payload = {
    "name": "My WorldView order using query",
    "input": query
}
response = oauth.post(url, json=payload)
response.raise_for_status()
order = response.json()

To extract the order id from the response:

order_id = order['id']

To extract the cost in square kilometres:

sqkm = order['sqkm']

Confirm the order

Confirming the order will subtract the ordered area in km² from your quota. To initiate import, confirm the order:

url = f"https://services.sentinel-hub.com/api/v1/dataimport/orders/{order_id}/confirm"
response = oauth.post(url)
response.raise_for_status()

Get order information

url = f"https://services.sentinel-hub.com/api/v1/dataimport/orders/{order_id}"
response = oauth.get(url)
response.raise_for_status()
order = response.json()

To extract the order status:

status = order['status']

To extract the BYOC collection ID:

collection_id = order['collectionId']

List all your orders

url = "https://services.sentinel-hub.com/api/v1/dataimport/orders"
response = oauth.get(url)
response.raise_for_status()
response.json()

Access WorldView data in a BYOC collection and process a truecolor image

This is a normal Process API request that uses a BYOC collectionId that can be fetched from the get order information request. More examples are available here.

url = 'https://services.sentinel-hub.com/api/v1/process'
payload = {
    'input': {
        "bounds": {
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  15.81,
                  46.70
                ],
                [
                  15.84,
                  46.70
                ],
                [
                  15.84,
                  46.72
                ],
                [
                  15.81,
                  46.72
                ],
                [
                  15.81,
                  46.70
                ]
              ]
            ]
          }
        },
        "data": [{
            "type": "byoc-991fe3be-4d19-4d9f-9941-879da0a5c3b3",
            "dataFilter": {
                "timeRange": {
                  "from": "2020-11-06T00:00:00.0Z",
                  "to": "2020-11-06T23:59:59.9Z"
                }
            }
        }
      ]
    },
    "output": {
        "width": 512,
        "height": 512
    },
    "evalscript": """
        //VERSION=3
        function setup() {
            return {
                input: ["Red", "Green", "Blue", "dataMask"],
                output: { bands: 4 }
            };
        }
        var f = 2000;
        function evaluatePixel(sample) {
            return [sample.Red/f, sample.Green/f, sample.Blue/f, sample.dataMask];
        }
    """
  }
response = oauth.post(url, json=payload)
response.raise_for_status()