Ordering Basemaps

last updated: March 27, 2024

You can order Basemaps—analysis-ready mosaics—through the Orders API. To read about the different kinds of Basemaps and their specifications, see the Planet Basemaps Product Specification. To discover individual Basemaps, use the Basemaps API, select them in Planet Explorer, or view your Basemaps in the Basemap Viewer.

Warning

NICFI Basemaps can only be ordered from the Orders API by those with Level 2 NICFI access. For information on accessing NICFI Basemaps for Level 0 and 1 access, please see the NICFI DATA Program User Guide.

Use the power of the Orders API to download and stream Basemaps in cases where you want to:

  • Order mosaic quads in bulk
  • Get metadata for quad and scene identification
  • Download data for analysis based on an area of interest (AoI)
  • Reproject, resample, and rescale imagery to a projected coordinate system and resolution
  • Merge quads and associated metadata to produce a single GeoTIFF file
  • Deliver data to object stores in the cloud and download cloud-optimized GeoTIFFs

The following sections introduce the basics of ordering Basemaps through the Orders API:

Quad limit on Basemap orders

If no merge tool is specified, Basemap orders may contain up to 500 quads (defined either by area or quad ID). When the merge tool is used, the merged output must be less than 425 megapixels (approximately equal to the area of 25 quads with pixel dimensions 4096x4096).

Order Basemaps by area of interest (AoI)

To order Basemaps based on an area of interest, you need:

  • Your area of interest (AoI)
  • Your Basemap name
  • Your API Key (you can retrieve this from your account settings)

Get your Basemap name

Before you begin to make calls with the Orders API, you need the Basemap mosaic name for the Basemap you want to order. This ID is the value for the mosaic_name field in an order object.

You can get the ID of the Basemap you want to order through several Planet interfaces. The following section describes how to get your Basemap mosaic name in Planet Explorer, a web app, or alternatively through the Basemap API call.

Method 1: Get your Basemap name through Planet Explorer

To pick a Basemap using Planet Explorer, select a Basemap from the dropdown menu in the lower left corner.

Note

If you don't have access to basemaps, you see a message confirming that in the lower right corner. Select "Get Access" to sign up for basemaps or speak with your customer service manager.

Once you've selected a Basemap, the Explorer updates to include that Basemap in the view.

Select the search icon and time cadence, for example monthly or quarterly. Then select one of the resulting Basemap mosaic names, such as "global_monthly_2022_05_mosaic". When you do select it, that ID is automatically copied to your clipboard.

That's the value you will be passing into the Orders API.

Method 2: Get your Basemap name through the Basemap API

Another way to get your Basemap mosaic name is to use the Basemap APIs to retrieve the Basemap you want and the quad IDs.

Get the Basemaps API URL

Get the base URL you will need to communicate with the Basemap API service:

  1. Go to the Basemap API reference.
  2. Under List Mosaics, select GET /mosaics.

A dropdown UI element appears with the URL for retrieving Basemap mosaics:

https://api.planet.com/basemaps/v1/mosaics

This is the base URL to send a request and get a list of mosaics.

Search for the mosaic name

Set the Basemap API URL and your Planet API key.

BASEMAP_API_URL = 'https://api.planet.com/basemaps/v1/mosaics'
auth = HTTPBasicAuth(PLANET_API_KEY, '')
basemapServiceResponse = requests.get(url=BASEMAP_API_URL, auth=auth)

Print out the resulting Basemaps.

basemaps = basemapServiceResponse.raise_for_status()
if basemapServiceResponse.status_code != 204:
    basemaps = json.loads(basemapServiceResponse.text)
print(basemaps)

Pick the name from the list returned of the Basemap you want to order and use it as the mosaic_name value when ordering your Basemap.

Creating a Basemaps order

To order Basemaps through the Orders API:

  • Create an order object that describes the Basemap you want and the area of interest (AoI) to cover.
  • POST the Orders request.
  • Poll for success and then download the Basemap.

Example order query JSON block

Create a JSON object with a name for your order and a source_type of basemaps. Include in the product field the mosaic_name of the Basemap you want to order. Provide the geometry for your Area of Interest (AoI).

order_params = {
   "name": "Basemap order with geometry",
   "source_type": "basemaps",
   "products": [
      {
         "mosaic_name": "global_monthly_2022_01_mosaic",
         "geometry":{
         "type": "Polygon",
         "coordinates":[
            [
            [4.607406, 52.353994],
            [4.680005, 52.353994],
            [4.680005, 52.395523],
            [4.607406, 52.395523],
            [4.607406, 52.353994]
            ]
         ]
         }
      }
   ]
}

Example POST request

Your REST API request must include the following values:

  • Your Planet API key
  • The Orders API REST URL: https://api.planet.com/compute/ops/orders/v2
  • A content-type header for your JSON object
  • The order query JSON block (see the above example)
paramRes = requests.post(ORDERS_API_URL, data=json.dumps(order_params), auth=auth, headers=headers)

Example result

If you print the result of the example POST request above, among other validating information, you see the state of the order and the geometry to be returned. In this example, the call to print:

print(paramRes.text)

displays the following JSON result:

{
    "_links": {
        "_self": "https://api.planet.com/compute/ops/orders/v2/2d56741a-8751-4cbe-a8b4-28525fc5de4d"
    },
    "created_on": "2022-07-07T22:19:22.414Z",
    "error_hints": [],
    "id": "2d56741a-8751-4cbe-a8b4-28525fc5de4d",
    "last_message": "Preparing order",
    "last_modified": "2022-07-07T22:19:22.414Z",
    "name": "basemap order with geometry",
    "products": [
        {
            "geometry": {
                "coordinates": [
                    [
                        [ 4.607406, 52.353994 ],
                        [ 4.680005, 52.353994 ],
                        [ 4.680005, 52.395523 ],
                        [ 4.607406, 52.395523 ],
                        [ 4.607406, 52.353994 ]
                    ]
                ],
                "type": "Polygon"
            },
            "mosaic_name": "global_monthly_2022_01_mosaic"
        }
    ],
    "source_type": "basemaps",
    "state": "queued"
}

Poll for success, then download

When your customized Basemap is ready to download the state changes to success. You can apply a typical poll for success, such as the one described in the Orders API Notebooks on Planet Labs Github. When the success state is returned, download individual files or deliver them to an object store on the cloud.

Example returned files

For each quad, the files delivered include the raster imagery, metadata files, and a zip of vector files. Here is a list of files typically returned for an example such as this:

File Name Bytes
1050-1374_metadata.json 906
1050-1374_ortho_udm.tif 129390
1050-1374_provenance_raster.tif 236725
1050-1374_quad.tif 36826371
1050-1374_provenance_vector.zip 22698
1050-1374_provenance_vector Files Zipped Bytes
L15-1050E-1374N.dbf 590
L15-1050E-1374N.prj 425
L15-1050E-1374N.shp 63604
L15-1050E-1374N.shx 116

Example metadata

The metadata file provides, among other things, details on the Basemap, the quad, the bounding box, and the link back to the individual composite scenes.

{
  "_links": {
    "_self": "https://api.planet.com/basemaps/v1/mosaics?api_key=af7c60b57fe74e3fab6997c0bd20dd8b"
  },
  "mosaics": [
    {
      "_links": {
        "_self": "https://api.planet.com/basemaps/v1/mosaics/8e14ee92-d07c-48eb-b490-8f95d275ef0e?api_key=af7c60b57fe74e3fab6997c0bd20dd8b",
        "quads": "https://api.planet.com/basemaps/v1/mosaics/8e14ee92-d07c-48eb-b490-8f95d275ef0e/quads?api_key=af7c60b57fe74e3fab6997c0bd20dd8b&bbox={lx},{ly},{ux},{uy}",
        "tiles": "https://tiles.planet.com/basemaps/v1/planet-tiles/queensland_visual_2022q2_mosaic/gmap/{z}/{x}/{y}.png?api_key=af7c60b57fe74e3fab6997c0bd20dd8b"
      },
      "bbox": [
        137.812499980916,
        -29.228890026438,
        153.808593728694,
        -8.92848706138
      ],
      "coordinate_system": "EPSG:3857",
      "datatype": "byte",
      "first_acquired": "2022-04-01T00:00:00.000Z",
      "grid": {
        "quad_size": 4096,
        "resolution": 4.777314267823516
      },
      "id": "8e14ee92-d07c-48eb-b490-8f95d275ef0e",
      "interval": "3 mons",
      "item_types": [
        "PSScene"
      ],
      "last_acquired": "2022-07-01T00:00:00.000Z",
      "level": 15,
      "name": "queensland_visual_2022q2_mosaic",
      "product_type": "timelapse",
      "quad_download": true
    }
  ]
}

Order Basemaps by quad IDs and deliver to cloud

A Basemap is made of a grid of GeoTIFF files called quads. You can order individual quads through the Orders API using the following steps:

  1. From the Basemaps API, get the Basemap mosaic_id and quad_ids that you want to deliver to the cloud.
  2. Create an order query JSON block that includes those IDs.
  3. POST the Orders request.
  4. Poll for success and then download the Basemap.

Get your Basemaps quad IDs using the Basemap API

To retrieve Basemap quads, you need the mosaic name of the Basemap (see Get your Basemap name, above).

Example Basemap packet

Create a JSON object that declares the Basemap you want the quad IDs for.

basemap_params = {
    'name__is': 'point_reyes_rolling_normalized_2020-04-30_mosaic'
}

Example GET request

Your REST API request must include the following values:

  • Your Planet API key
  • The Basemap API REST URL: https://api.planet.com/basemaps/v1/mosaics
  • A content-type header for your JSON object
  • The order query JSON block like the one in the example above
auth = HTTPBasicAuth(PLANET_API_KEY, '')
BASEMAP_API_URL = 'https://api.planet.com/basemaps/v1/mosaics'
headers = {'content-type': 'application/json'}

basemap_params = {
    'name__is': 'point_reyes_rolling_normalized_2020-04-30_mosaic'
}

basemapServiceResponse = requests.get(url=BASEMAP_API_URL, params=basemap_params, auth=auth, headers=headers)

basemaps = basemapServiceResponse.raise_for_status()
if basemapServiceResponse.status_code != 204:
    basemaps = json.loads(basemapServiceResponse.text)
print(basemaps)

Example of getting quad IDs

After you have the Basemap, make a call to list the mosaic quads. In the reference for this call to list mosaic quads, notice the required fields are the mosaic ID and the bounding box.

mosaicID = basemaps['mosaics'][0]['id']
mosaicBbox = basemaps['mosaics'][0]['bbox']
mosaicBboxStr = ','.join(map(str, mosaicBbox))

quad_params = {
    'mosaic_id': mosaicID,
    'bbox': mosaicBboxStr,
}

Build the quads URL based on the base URL.

quads_url = "{}/{}/quads".format(BASEMAP_API_URL, mosaicID)
quadServiceResponse = requests.get(url=quads_url, params=quad_params, auth=auth, headers=headers)
quads = quadServiceResponse.json()
items = quads['items']

Iterate over quad to get the quad IDs.

quadIds = []
for i in items:
    quadId = i['id']
    quadIds.append(quadId)

Use the quadIds you just gathered to make the Orders API request to send the quads to the cloud, in the next section.

Deliver Basemaps quad to the cloud

In the reference, notice the required product fields are mosaic_name and quad_ids. These are the values you retrieved in the sections above. The order query JSON block should include that required information.

Because this example sends the ordered quads to cloud storage, the order query JSON block should also include the cloud delivery field.

Example order query JSON block

order_params = {
   "name":"basemap order with quad_ids",
   "source_type":"basemaps",
   "products":[
      {
         "mosaic_name":"point_reyes_rolling_normalized_2020-04-30_mosaic",
         "quad_ids": quadIds
      }
   ],
   "delivery":{
      "google_cloud_storage":{
         "bucket":"[your-orders-delivery-bucket]",
         "credentials":"[base64-encoded-credentials-for-service-agent…]",
         "path_prefix":"[optionalsubfolder/]"
      }
   }
}

Note

For more details on how to prepare the credentials and base64-encode the value for credentials, see Delivery to Google Cloud Storage.

Example POST request

Your REST API request must include the following values:

  • Your Planet API key
  • The Orders API REST URL: https://api.planet.com/compute/ops/orders/v2
  • A content-type header for your JSON object
  • The order query JSON block like the one in the example above
paramRes = requests.post(ORDERS_API_URL, data=json.dumps(order_params), auth=auth, headers=headers)

paramRes.raise_for_status()
if paramRes.status_code != 204:
    print(paramRes.text)

Poll for success, then review quads in the cloud. When your quads are uploaded to the cloud the GET request state changes to success. (You can apply a typical poll for success, such as described in the Orders API Notebooks on Planet Labs Github.) The quads were successfully delivered to the indicated cloud bucket. Visit that cloud interface to view your quads and associated metadata.

Customize your Basemaps with Order tools

Basemaps supports four Order API tools:

  • merge — merge basemaps into a larger study area
  • clip — for orders with a geometry block, clip a raster to an area of interest
  • reproject — resample a Basemap to a new projection area
  • bandmath — perform numpy-like operations on rasters

Order Type: Full or Partial

The Orders API supports two order types: full and partial.

  • full By default, if unspecified, all orders have an order_type of full. A full Basemaps order type will fail an order if any single quad is unavailable.
  • partial A partial order type delivers any available quads, excluding any items which are missing or which the requester lacks permissions to access.

The Orders API will always deliver all or none of the scenes in the quad. It will never deliver partial quads.

Example Request using order type, raster tools, and cloud delivery

POST https://api.planet.com/compute/ops/orders/v2

{
   "name": "basemap order with geometry",
   "source_type": "basemaps",
   "order_type":"partial",
   "products": [
       {
           "mosaic_name": "global_monthly_2022_01_mosaic",
           "geometry":{
               "type": "Polygon",
               "coordinates":[
                   [
                       [4.607406, 52.353994],
                       [4.680005, 52.353994],
                       [4.680005, 52.395523],
                       [4.607406, 52.395523],
                       [4.607406, 52.353994]
                   ]
               ]
           }
      }
  ],
    "tools": [
      {"merge": {}},
      {"clip": {}}
  ],
   "delivery":{
      "google_cloud_storage":{
         "bucket":"[your-orders-delivery-bucket]",
         "credentials":"[base64-encoded-credentials-for-service-agent…]",
         "path_prefix":"[optionalsubfolder/]"
      }
   }
}

Rate this guide: