PLScenes (Planet Labs Scenes/Catalog API)

(GDAL/OGR >= 2.0 for v0 API, and GDAL/OGR >= 2.1 for v1 API)

This driver can connect to Planet Labs Scenes v0/Catalog v1 API. GDAL/OGR must be built with Curl support in order for the PLScenes driver to be compiled.

The driver supports read-only operations to list scenes and their metadata as a vector layer per scene type/catalog ("ortho" for example). It can also access raster scenes.

Dataset name syntax

The minimal syntax to open a datasource is :
PLScenes:[options]

Additional optional parameters can be specified after the ':' sign. Currently the following one is supported :

If several parameters are specified, they must be separated by a comma.

Open options

The following open options are available :

Configuration options

The following configuration options are available :

Attributes

v0 API

The scene metadata are retrieved into the following feature fields for the "ortho" layer :

NameTypeDescription
idStringScene unique identifier.
acquiredDateTimeThe time that image was taken in UTC.
camera.bit_depthIntegerBit depth with which the image was taken onboard the satellite. Currently 8 or 12.
camera.color_modeStringThe color mode of the image as taken by the satellite. Currently "RGB" or "Monochromatic".
camera.exposure_timeIntegerThe exposure time in microseconds.
camera.gainIntegerThe analog gain with which the image was taken.
camera.tdi_pulsesIntegerThe number of pulses used for time delay and integration on the CCD. Currently 0 (if TDI was not used), 4, 6, or 12.
cloud_cover.estimatedRealThe estimated percentage of the image covered by clouds. Decimal 0-100.
data.products.analytic.fullStringURL to download scene GeoTIFF of the "analytic" product.
data.products.visual.fullStringURL to download scene GeoTIFF of the "visual" product.
file_sizeIntegerThe size of the full image in bytes.
image_statistics.gsdRealThe ground sample distance (distance between pixel centers measured on the ground) of the image in meters.
image_statistics.image_qualityStringImage quality category for scene. One of 'test', 'standard', or 'target'.
image_statistics.snrRealThe estimated signal to noise ratio. Decimal > 0. Values greater than or equal to 50 are considered excellent quality. Values less than 50 and greater than or equal to 20 are considered adequate quality. Values less than 20 are considered poor quality.
links.fullStringURL to download scene GeoTIFF (same content as data.products.visual.full currently)
links.selfStringURL to scene information
links.square_thumbnailStringURL to image thumbnail
links.thumbnailStringLink to image square thumbnail
sat.altRealThe altitude of the satellite when the image was taken in kilometers.
sat.idStringA unique identifier for the satellite that captured this image.
sat.latRealThe latitude of the satellite when the image was taken in degrees.
sat.lngRealThe longitude of the satellite when the image was taken in degrees.
sat.off_nadirRealThe angle off nadir in degrees at which the image was taken.
strip_idRealA unique float identifier for the set of images taken sequentially be the same satellite.
sun.altitudeRealThe altitude (angle above horizon) of the sun from the imaged location at the time of capture in degrees.
sun.azimuthRealThe azimuth (angle clockwise from north) of the sun from the imaged location at the time of capture in degrees.
sun.local_time_of_dayRealThe local sun time at the imaged location at the time of capture (0-24).
For other layers / scene types, additional attributes may be retrieved.

v1 API

For the v1 API, the layer field definition is built dynamically from the catalog specification. The links to downloadable products are in asset_XXXXX_product_link attributes where XXXXX is the asset category id, when they are active. Otherwise they should be activated by sending a POST request to the URL in the asset_XXXXX_activate_link attribute (what the raster driver does automatically)

The details about the layer field description are given in the FIELDS_DESCRIPTION metadata item as a JSon serialized object. The keys are the OGR field names, and the value is an object that contains the definition of each field, with the following attributes :

For example:

{
  "id":{
    "description":"Identifier of this Item.",
    "type":"string",
    "src_field":"id",
    "server_queryable":true
  },
  "self_link":{
    "description":"RFC 3986 URI representing the canonical location of this object.",
    "type":"string",
    "src_field":"_links._self",
    "server_queryable":false
  },
  "assets_link":{
    "description":"RFC 3986 URI representing the canonical location of the Assets subcollection.",
    "type":"string",
    "src_field":"_links.assets",
    "server_queryable":false
  },
  "published":{
    "description":"The RFC 3339 timestamp at which this Item was added to the Catalog.",
    "format":"date-time",
    "type":"string",
    "src_field":"properties.published",
    "server_queryable":true
  },
  "acquired":{
    "description":"The RFC 3339 acquisition time of underlying image.",
    "format":"date-time",
    "type":"string",
    "src_field":"properties.catalog::acquired",
    "server_queryable":true
  },
  "black_fill":{
    "description":"Ratio of image containing artificial black fill due to clipping to actual data.",
    "format":"float",
    "maximum":1.000000,
    "minimum":0.000000,
    "type":"number",
    "src_field":"properties.catalog::black_fill",
    "server_queryable":true
  },
  "cloud_cover":{
    "description":"Ratio of the image covered by clouds to that which is uncovered.",
    "format":"float",
    "maximum":1.000000,
    "minimum":0.000000,
    "type":"number",
    "src_field":"properties.catalog::cloud_cover",
    "server_queryable":true
  },
  "grid_cell":{
    "description":"The grid cell identifier of the gridded Item.",
    "type":"string",
    "src_field":"properties.catalog::grid_cell",
    "server_queryable":true
  },
  "provider":{
    "description":"Name of the imagery provider.",
    "enum":[
      "planetscope",
      "rapideye",
      "landsat",
      "sentinel"
    ],
    "type":"string",
    "src_field":"properties.catalog::provider",
    "server_queryable":true
  },
  "resolution":{
    "description":"Pixel resolution of the Item image(s) in meters.",
    "format":"float",
    "minimum":0.000000,
    "type":"number",
    "src_field":"properties.catalog::resolution",
    "server_queryable":true
  },
  "satellite_id":{
    "description":"Globally unique identifier of the satellite that acquired the underlying image.",
    "type":"string",
    "src_field":"properties.catalog::satellite_id",
    "server_queryable":true
  },
  "strip_id":{
    "description":"Identifier of the Item's parent strip.",
    "type":"string",
    "src_field":"properties.catalog::strip_id",
    "server_queryable":true
  },
  "sun_azimuth":{
    "description":"Angle from the True North to the Sun Vector projected on the horizontal plane in degrees.",
    "format":"float",
    "maximum":360.000000,
    "minimum":0.000000,
    "type":"number",
    "src_field":"properties.catalog::sun_azimuth",
    "server_queryable":true
  },
  "sun_elevation":{
    "description":"Elevation angle of the sun in degrees.",
    "format":"float",
    "maximum":90.000000,
    "minimum":0.000000,
    "type":"number",
    "src_field":"properties.catalog::sun_elevation",
    "server_queryable":true
  },
  "usable_data":{
    "description":"Ratio of the usable to unusable portion of the image due to cloud cover or black fill.",
    "format":"float",
    "maximum":1.000000,
    "minimum":0.000000,
    "type":"number",
    "src_field":"properties.catalog::usable_data",
    "server_queryable":true
  },
  "view_angle":{
    "description":"Spacecraft across-track off-nadir viewing angle used for imaging, in degrees with \"+\" being East and \"-\" being West.",
    "format":"float",
    "maximum":25.000000,
    "minimum":-25.000000,
    "type":"number",
    "src_field":"properties.catalog::view_angle",
    "server_queryable":true
  },
  "asset_visual_self_link":{
    "description":"RFC 3986 URI representing the canonical location of this asset.",
    "type":"string",
    "src_field":"\/assets.visual._links._self",
    "server_queryable":false
  },
  "asset_visual_permissions":{
    "items":{
      "enum":[
        "download"
      ],
      "type":"string"
    },
    "type":"array",
    "uniqueItems":true,
    "src_field":"\/assets.visual._permissions",
    "server_queryable":false
  },
  "asset_visual_activate_link":{
    "description":"If present, RFC 3986 URI indicating where an authenticated user may trigger activation of this AssetFile via a POST request. A 202 response indicates the activation request has been accepted. A 204 response indicates the AssetFile is already active. After successful activation, this AssetFile will have a non-empty location.",
    "type":"string",
    "src_field":"\/assets.visual.files._links.activate",
    "server_queryable":false
  },
  "asset_visual_expires_at":{
    "description":"If present, RFC 3339 timestamp indicating when this AssetFile will become inactive and will require reactivation.",
    "format":"date-time",
    "type":"string",
    "src_field":"\/assets.visual.files.expires_at",
    "server_queryable":false
  },
  "asset_visual_product_link":{
    "description":"If present, RFC 3986 URI that indicates a location that will yield image data. Consult the documentation of the AssetFile type to understand how to use this URI.",
    "type":"string",
    "src_field":"\/assets.visual.files.location",
    "server_queryable":false
  },
  "asset_visual_product_link_status":{
    "description":"Current status of the AssetFile. \"inactive\" indicates that the AssetFile is not currently available for download, but may be after activation. \"activating\" indicates the AssetFile is currently undergoing activation, and may be available for download shortly. \"active\" indicates the AssetFile has been activated, and may currently be available for download if the authentication context permits.",
    "enum":[
      "inactive",
      "activating",
      "active"
    ],
    "type":"string",
    "src_field":"\/assets.visual.files.status",
    "server_queryable":false
  },
  "asset_visual_mimetype":{
    "description":"The MIME type of the underlying asset file.",
    "type":"string",
    "src_field":"\/assets.visual.mimetype",
    "server_queryable":false
  },
  "asset_analytic_self_link":{
    "description":"RFC 3986 URI representing the canonical location of this asset.",
    "type":"string",
    "src_field":"\/assets.analytic._links._self",
    "server_queryable":false
  },
  "asset_analytic_permissions":{
    "items":{
      "enum":[
        "download"
      ],
      "type":"string"
    },
    "type":"array",
    "uniqueItems":true,
    "src_field":"\/assets.analytic._permissions",
    "server_queryable":false
  },
  "asset_analytic_activate_link":{
    "description":"If present, RFC 3986 URI indicating where an authenticated user may trigger activation of this AssetFile via a POST request. A 202 response indicates the activation request has been accepted. A 204 response indicates the AssetFile is already active. After successful activation, this AssetFile will have a non-empty location.",
    "type":"string",
    "src_field":"\/assets.analytic.files._links.activate",
    "server_queryable":false
  },
  "asset_analytic_expires_at":{
    "description":"If present, RFC 3339 timestamp indicating when this AssetFile will become inactive and will require reactivation.",
    "format":"date-time",
    "type":"string",
    "src_field":"\/assets.analytic.files.expires_at",
    "server_queryable":false
  },
  "asset_analytic_product_link":{
    "description":"If present, RFC 3986 URI that indicates a location that will yield image data. Consult the documentation of the AssetFile type to understand how to use this URI.",
    "type":"string",
    "src_field":"\/assets.analytic.files.location",
    "server_queryable":false
  },
  "asset_analytic_product_link_status":{
    "description":"Current status of the AssetFile. \"inactive\" indicates that the AssetFile is not currently available for download, but may be after activation. \"activating\" indicates the AssetFile is currently undergoing activation, and may be available for download shortly. \"active\" indicates the AssetFile has been activated, and may currently be available for download if the authentication context permits.",
    "enum":[
      "inactive",
      "activating",
      "active"
    ],
    "type":"string",
    "src_field":"\/assets.analytic.files.status",
    "server_queryable":false
  },
  "asset_analytic_mimetype":{
    "description":"The MIME type of the underlying asset file.",
    "type":"string",
    "src_field":"\/assets.analytic.mimetype",
    "server_queryable":false
  }
}

Geometry

The footprint of each scene is reported as a MultiPolygon with a longitude/latitude WGS84 coordinate system (EPSG:4326).

Filtering

The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes the same for simple attribute filters set with SetAttributeFilter(). Note that not all attributes support all comparison operators. Refer to comparator column in Metadata properties

Paging

Features are retrieved from the server by chunks of 1000 by default (and this is the maximum value accepted by the server). This number can be altered with the PLSCENES_PAGE_SIZE configuration option.

Vector layer (scene metadata) examples

  • Listing all scenes available (with the rights of the account) :
    ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value
    
    or
    ogrinfo -ro -al "PLScenes:api_key=some_value"
    
    or
    ogrinfo -ro -al "PLScenes:" --config PL_API_KEY some_value
    

  • Listing all scenes available under a point of (lat,lon)=(40,-100) :
    ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -spat -100,40,-100,40
    

  • Listing all scenes available within a bounding box (lat,lon)=(40,-100) to (lat,lon)=(39,-99)
    ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -spat -100,40,-99,39
    

  • Listing all scenes available matching criteria :
    ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -where "acquired >= '2015/03/26 00:00:00' AND \"cloud_cover.estimated\" < 10"
    

  • List all downloadable scenes (API v1):
    ogrinfo -ro -al -q "PLScenes:" -oo VERSION=v1 -oo API_KEY=some_value -oo FILTER='_permissions=assets:download'
    
  • List scenes matching a filter using Quick Search API (API v1):
    ogrinfo -ro -al -q "PLScenes:" -oo VERSION=v1 -oo API_KEY=some_value -oo FILTER='{
      "filter": {
        "type": "OrFilter",
        "config": [
          {
            "field_name": "published",
            "config": {
              "gte": "2015-10-01T00:00:00Z"
            },
            "type": "DateRangeFilter"
          }
        ]
      }
    }'
    

    Raster access

    Scenes and their thumbnails can be accessed as raster datasets, provided that the scene ID is specified with the 'scene' parameter / SCENE open option. The product type (visual, analytic or thumb) can be specified with the 'product_type' parameter / PRODUCT_TYPE open option. The scene id is the content of the value of the 'id' field of the features of the 'ortho' vector layer.

    This functionality is a convenience wrapper of the API for fetching the scene GeoTIFF

    For API v1, the CATALOG open option must be specified. If the product is not already generated on the server, it will be activated, and the driver will wait for it to be available. The length of this retry can be configured with the ACTIVATION_TIMEOUT open option.

    Raster access examples

  • Displaying raster metadata :
    gdalinfo "PLScenes:scene=scene_id,product_type=analytic" -oo API_KEY=some_value
    
    or
    gdalinfo "PLScenes:" -oo API_KEY=some_value -oo SCENE=scene_id -oo PRODUCT_TYPE=analytic
    
    or with V1 API:
    gdalinfo "PLScenes:" -oo API_KEY=some_value -oo VERSION=v1 -oo CATALOG=catalog_name -oo SCENE=scene_id -oo PRODUCT_TYPE=analytic
    
  • Converting/downloading a whole file:
    gdal_translate "PLScenes:" -oo API_KEY=some_value -oo SCENE=scene_id \
                    -oo PRODUCT_TYPE=analytic -oo RANDOM_ACCESS=NO out.tif
    

    See Also