EVOLUTION-MANAGER

Edit File: drv_plscenes_v1.html

<html>
<head>
<title>PLScenes (Planet Labs Scenes/Catalog API), V1 API</title>
</head>

<h1>PLScenes (Planet Labs Scenes/Catalog API), V1 API</h1>

GDAL/OGR &gt;= 2.1 for v1 API<p>

Note: this version of the API is deprecated. Please migrate to the
<a href="drv_plscenes_data_v1.html">Data V1 API</a>.<p>

The driver supports read-only operations to list scenes and their metadata
as a vector layer per scene catalog.
It can also access raster scenes.<p>

<h2>Dataset name syntax</h2>

The minimal syntax to open a datasource is : <pre>PLScenes:[options]</pre><p>

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

<ul>
<li> <b>version</b>=v1: To specify the API version to request. Defaults to data_v1 starting with GDAL 2.2 (v0 for older versions).</li>
<li> <b>api_key</b>=value: To specify the Planet API KEY. It is mandatory, unless
it is supplied through the open option API_KEY, or the configuration option PL_API_KEY.</li>
<li><b>follow_links</b>=YES/NO: Whether assets links should be followed for each scene (vector).
Getting assets links require a HTTP request per scene, which might be costly when
enumerating through a lot of products. Defaults to NO.</li>
<li> <b>scene</b>=scene_id: To specify the scene ID, when accessing raster data.
Optional for vector layer access.</li>
<li> <b>catalog</b>=name: To specify the item types name.
Optional for vector layer access. Mandatory for raster access.</li>
<li> <b>product_type</b>=value: To specify the asset type
(for raster fetching). Default is "visual". Optional for vector layer access.
If the option is not specified and the 'visual' asset category does not exist for the scene
(or if the value is set to 'list'), the returned dataset will have subdatasets
for the available asset categories.</li>
<li> <b>filter</b>=string: To specify an additional filter on the request URL (/items endpoint)
that will be only evaluated on server-side. Can be convenient for conditions that are not
easily expressed in OGR SQL. For example, to restrict to scenes whose visual asset
can be downloaded, use '_permissions=assets.visual:download'. It can also be a more
complex query expressed as a JSon filter to be evaluated by the Quick Search API(/quick-search endpoint)</li>
</ul>

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

<h2>Open options</h2>

The following open options are available :
<ul>
<li><b>VERSION</b>=v1: To specify the API version to request. Defaults to data_v1 starting with GDAL 2.2 (v0 for older versions).</li>
<li><b>API_KEY</b>=value: To specify the Planet API KEY.</li>
<li><b>FOLLOW_LINKS</b>=YES/NO: Whether assets links should be followed for each scene (API v1 and data v1 only, vector).
Getting assets links require a HTTP request per scene, which might be costly when
enumerating through a lot of products. Defaults to NO.</li>
<li><b>SCENE</b>=scene_id: To specify the scene ID, when accessing raster data.
Optional for vector layer access.</li>
<li> <b>CATALOG</b>=name: To specify the item types name.
Optional for vector layer access. Mandatory for raster access with v1 API.</li>
<li> <b>PRODUCT_TYPE</b>=value: To specify the asset type
(for raster fetching). Default is "visual". Optional for vector layer access.
If the option is not specified and the 'visual' asset category does not exist for the scene
(or if the value is set to 'list'), the returned dataset will have subdatasets
for the available asset categories.</li>
<li><b>RANDOM_ACCESS</b>=YES/NO: Whether raster should be accessed in random access mode
(but with potentially not optimal throughput). If NO, in-memory ingestion is done.
Default is YES.</li>
<li><b>ACTIVATION_TIMEOUT</b>=int: Number of seconds during which to wait for
asset activation (raster). Default is 3600.</li>
<li> <b>FILTER</b>=string: To specify an additional filter on the request URL (/items endpoint)
that will be only evaluated on server-side. Can be convenient for conditions that are not
easily expressed in OGR SQL. For example, to restrict to scenes whose visual asset
can be downloaded, use '_permissions=assets.visual:download'. It can also be a more
complex query expressed as a JSon filter to be evaluated by the Quick Search API(/quick-search endpoint)</li>
</ul>

<h2>Configuration options</h2>

The following configuration options are available :
<ul>
<li><b>PL_API_KEY</b>=value: To specify the Planet API KEY.</li>
</ul>

<h2>Attributes</h2>

<p>The layer field definition is built dynamically from the catalog
specification. The links to downloadable products are
in <i>asset_XXXXX_product_link</i> 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 <i>asset_XXXXX_activate_link</i> attribute (what the raster driver
does automatically)</p>

<p>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 :
<ul>
<li><i>description</i>: string with human readable description of the filed</li>
<li><i>type</i>: e.g: string, number or integer</li>
<li><i>format</i> (optional): e.g. date-time, float, int32, ...</li>
<li><i>server_queryable</i>: true if filters on the property are forwarded to the server.
Otherwise the filter is evaluated on client side.</li>
<li><i>src_field</i>: path to the property from the root of the JSon Feature object.</li>
</ul>
For example:</p>
<pre>
{
  "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
  }
}
</pre>

<h3>Geometry</h3>

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

<h3>Filtering</h3>

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 <a href="https://www.planet.com/docs/v0/scenes/#metadata">Metadata properties</a> <p>

<h3>Paging</h3>

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

<h3>Vector layer (scene metadata) examples</h3>

<li>
Listing all scenes available (with the rights of the account) :
<pre>
ogrinfo -ro -al "PLScenes:" -oo VERSION=V1 -oo API_KEY=some_value
</pre>
or
<pre>
ogrinfo -ro -al "PLScenes:api_key=some_value"
</pre>
or
<pre>
ogrinfo -ro -al "PLScenes:" -oo VERSION=V1 --config PL_API_KEY some_value
</pre>
<p>

<li>
Listing all scenes available under a point of (lat,lon)=(40,-100) :
<pre>
ogrinfo -ro -al "PLScenes:" -oo VERSION=V1 -oo API_KEY=some_value -spat -100,40,-100,40
</pre>
<p>

<li>
Listing all scenes available within a bounding box (lat,lon)=(40,-100) to (lat,lon)=(39,-99)
<pre>
ogrinfo -ro -al "PLScenes:" -oo VERSION=V1 -oo API_KEY=some_value -spat -100,40,-99,39
</pre>
<p>

<li>
Listing all scenes available matching criteria :
<pre>
ogrinfo -ro -al "PLScenes:" -oo VERSION=V1 -oo API_KEY=some_value -where "acquired >= '2015/03/26 00:00:00' AND \"cloud_cover.estimated\" &lt; 10"
</pre>
<p>

<li>
List all downloadable scenes:
<pre>
ogrinfo -ro -al -q "PLScenes:" -oo VERSION=v1 -oo API_KEY=some_value -oo FILTER='_permissions=assets:download'
</pre>

<li>
List scenes matching a filter using Quick Search API:
<pre>
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"
      }
    ]
  }
}'
</pre>
<p>

<h2>Raster access</h2>

<p>Scenes 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, ...) 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.</p>

<p>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.</p>

<h3>Raster access examples</h3>

<li>
Displaying raster metadata :

<pre>
gdalinfo "PLScenes:" -oo API_KEY=some_value -oo VERSION=v1 -oo CATALOG=catalog_name -oo SCENE=scene_id -oo PRODUCT_TYPE=analytic
</pre>

<li>
Converting/downloading a whole file:

<pre>
gdal_translate "PLScenes:" -oo VERSION=v1 -oo API_KEY=some_value -oo SCENE=scene_id \
                 -oo CATALOG=catalog_name -oo PRODUCT_TYPE=analytic -oo RANDOM_ACCESS=NO out.tif
</pre>

<ul>
<li> <a href="drv_plscenes.html">General documentation page for PLScenes driver</a><p>
<li> <a href="frmt_plmosaic.html">Raster PLMosaic / Planet Mosaics API driver</a><p>
</ul>

</body>
</html>