概述

订阅API是Planet的下一代数据传递API。通过一个API调用,这种“订购搜索”功能允许您订阅图像和元数据集合的连续云交付,以满足您的项目过滤标准。

要创建订阅,可以指定图像过滤标准、光栅处理工具(包括剪辑)和云交付位置。然后,API将自动处理并交付所有符合您的订阅条件的条目,一旦它们被发布到目录中。

订阅API是Planet推荐的数据传输API,适用于需要稳定区域的日常图像的客户。

订阅模式

订阅请求有三个主块。

  • :描述用于定义订阅交付内容的数据产品和标准18bet体育平台。目前,目录支持源类型。它需要item_types.,Asset_types.和一个筛选,紧贴着一个Data API/快速搜索要求
  • 工具:描述了可以应用于杀害的光栅工具。目前,只有夹子得到支持。
  • 交付:描述订阅项目的谷歌云存储,亚马逊S3和Microsoft Azure云传送选项。

更多细节,工具, 和交付块参数在左侧导航页面中可用,或直接跳转到创建订阅示例请求在下面。

订阅状态

订阅API州

状态描述

  • 准备:订阅已成功提交并正在设置。
  • 等待:订阅的源开始时间(发表DateRangeFiltergt或者GTE.价值)尚未通过。交货尚未开始。
  • 活跃的:订阅的源开始时间已通过,它正在积极监控新目录发布事件和处理输出。交货可能正在进行中。
  • 完成:订阅的源代码时间(发表DateRangeFilterLT.或者LTE.值)已通过,所有物品都已交付。交付已停止。
  • 暂停:订阅策略或配额冲突。交付已停止。
  • 取消:用户取消订阅。交付已停止。
  • 失败的字体订阅有个问题。

订购未来的收藏和存档图像

订阅API目前支持交付未来的图像收藏。这意味着,开始时间(发表DateRangeFiltergt或者GTE.一个订阅的UTC值)必须是在未来(在订阅创建的时间之后),并且只有未来的图像集合将被交付。

我们称这种性质的订阅为“转发”订阅。

订阅API转发填充图

明年初,我们计划在订阅API中提供归档图像或“回填”支持。这将允许客户订购历史图像。订阅的开始日期可能是过去(在订阅创建时间之前),客户将能够仅订购存档图像,或者档案和未来的集合,如果订阅结束日期(发表DateRangeFilterLT.或者LTE.UTC值)是在未来。

订阅API转发填充和回填图

对档案图像感兴趣的客户可以继续通过订单的API

订阅API的限制

订阅API使用将限制为最大数量活跃的对每日交付的预期项目总数有上限的订阅。

  • 最大限度活跃的订阅:一个组织可以在一个活跃的状态。如果组织已经最大限度的数量,则可能无法创建一个新的订阅活跃的订阅。
  • 每天提供的预期项目总额:每天预期匹配和交付的项目总数全部活跃的订阅。如果每天交付的预期项目数量超过了组织的总限额,则不能创建新的订阅。
    • 为了估计订阅每天将交付的预期条目数,Subscriptions API使用数据API的搜索统计端点平均每日物品在过去7天内匹配。然后跨越这些数字活跃的订阅。
    • 如果他们将每日交付的最高限度交付的预期项目总数汇总,则无法创建新订阅。
    • 注意:在订阅创建时,请验证“每日交付的预期项目”。如果订阅发生以与给定日期相匹配,则订阅API不会人工限制项目交付。

默认情况下,客户将受以下限制:最大限度活跃的订阅:1,000每日提供的预计项目总数:1,000

如果您需要增加这些限制,请联系您的客户经理或support@planet.com。

创建一个订阅

基本订阅必须包括一个的名字,目录块(item_types.,Asset_types.,顶级和Filter., 一种GeometryFilter和一个发表DateRangeFiltergt或者GTE.将来的UTC值)交付块具有指定的云存储位置。订阅也支持SELECT工具

一旦满足所有项目筛选条件,并且所有请求的资产类型都已发布并可交付,订阅就会处理和交付项目。

示例请求

https://api.planet.com/subscriptions/v1//
{“姓名”:“basic_subscription”,“source”:{“type”:“catalog”,“参数”:{“item_types”:[psscene4band“,”asseT_types“:[”Analytic_sr“,”Analytic_xml“,“UDM2”],“筛选”:{“类型”:“AndFilter”,“config”:[【类型“:”daterangefilter“,”daterangefilter“,”field_name“:”发布“,”config“:{”gt“:”2020-07-31T00:00:00Z“,LTE”:“2020-08-31T00:00:00:00z”}},{“类型”:“geometryfilter”,“field_name”:“geometry”,“config”:{ “类型”: “多边形”, “坐标”:[[[-122.3984670639038,37.75459945618027],[-122.39546298980713,37.75459945618027],[-122.39546298980713,37.75768707689704],[-122.3984670639038,37.75768707689704],[-122.3984670639038,37.75459945618027]]]}},{ “类型”: “RangeFilter”, “FIELD_NAME”: “visible_percent”, “配置”:{ “GTE”:90}}]}}}, “工具”:[{ “类型”:“夹”, “参数”:{ “AOI”:{ “类型”: “多边形”, “坐标”:[[[-122.3984670639038,37.75459945618027],[-122.39546298980713,37.75459945618027],[-122.39546298980713,37.75768707689704],[-122.3984670639038,375768707689704],[-122.3984670639038,37.75459945618027]]]]}}],“交付”:{“类型”:“google_cloud_storage”,“参数”:{“桶”:“”,“凭据”“:”“}}}}

编辑订阅

您可以通过向以下端点提交完整的订阅请求来编辑订阅:

Put https://api.planet.com/subscriptions/v1/ 

订阅时等待状态,它可以完整编辑。订阅转换后活跃的,下面的块编辑将是不允许:

  • 更改item_types.
  • 更改发表DateRangeFiltergtGTE.价值

所有其他源筛选条件都可以编辑,只要订阅不超过每日交付的预期项目的限制。

重要的是,编辑只适用于未来的项目发布和交付。没有物品将被重新加工。如果需要根据更新的过滤器或工具规范重新排序存档项,则可以使用该项目搜索和订购存档项Data API订单的API

取消订阅

您可以取消订阅,以下请求:

发布https://api.planet.com/subscriptions/v1/1asubscription_id> cancel.

取消订阅后,不会交付其他项目(除了处理或交付中的任何项目除外)。取消的订阅无法转换为活跃的状态。取消中继续返回订阅得到订阅响应。

获取订阅

你可以通过下面的请求获得订阅列表:

获取https://api.planet.com/subscriptions/v1.

响应将包含订阅列表(包括取消订阅)。每个列出的订阅将包括原始订阅请求,订阅地位,创造了时间戳和更新时间戳。

控件按状态筛选订阅地位查询参数。例如,此API调用将返回所有订阅活跃的或者完成状态:

获取https://api.planet.com/subscriptions/v1?status=是rive& status=符合

您可以通过以下请求获取特定订阅的详细信息:

得到https://api.planet.com/subscriptions/v1/ < subscription_id >

获取订阅结果

结果目录类型订阅表示尝试处理和传递与订阅标准匹配的项目。您可以获得订阅结果的分页列表,以下要求:

得到https://api.planet.com/subscriptions/v1/ < subscription_id > /结果

响应将包括最近30天内创建的所有订阅结果的分页列表。超过30天的结果将不予退还。响应模式将包括:

  • ID:订阅结果的唯一ID。
  • 地位:结果项的交付状态。“结果状态”可以使用以下值之一:
    • 创造了:结果已经在系统中创建。对于目录源类型订阅,这意味着已发布与订阅相匹配的项。
    • 排队:结果是在队列中进行处理。
    • 处理:结果是在处理中。
    • 成功:结果已完成,输出已下发。
    • 失败的:结果已完成;输出无法传递。
  • 特性:
    • item_id.:结果的item_id。
    • item_types.:结果的item_type。
  • 创造了:生成结果的时间。为一个目录源类型订阅,这将是订阅确认新发布的项目的时间。
  • 更新:最后一次更新结果的时间。
  • 完成:结果到达结束状态的时间成功或者失败的
  • 错误:结果失败信息,包括a原因和数组细节
  • 输出:最终输出文件的目录。

您可以通过地位(即?status=processing)和by创造了,更新,或完成时间戳,使用Stac API时间戳和间隔约定:

  • DateTime:“2020-09-01T00:00:00Z”
  • A closed interval: "2020-09-01 t00: 00:00:00 z /2020-09-30T23:59:59Z"
  • 开启间隔:“2020-09-01 t00: 00:00:00 z /..”或“../2020-09-01 t00: 00:00:00 z”

例如,此API调用将返回所有订阅成功结果完成在2020年9月30日之前(并在过去30天内创建)。

得到https://api.planet.com/subscriptions/v1/b9ec5d6b - 8753 - 440 - 852 - c - 528188 f914d0/results?status=success&completed=../2020 - 09 - 30 - t00:00:00z

答案

{“_links”:{“_self”:“http://api.planet.com/subscriptions/v1/b9ec5d6b-8753-440a -852c-528188f914d0/51188f914d0/cesults”,“next”:“http://api.planet。com/subscriptions/v1/b9ec5d6b-8753-440a-852c-528188f914d0/results?page_marker=2020-09-16T23%3A32%3A37.501441Z" }, "results": [ { "id": "fa48f60d-160a-4714-a1f1-268e2fc96a58", "status": "success", "properties": { "item_id": "20200729_143245_ssc8d3_0001", "item_types": [ "PSScene4Band" ] }, "created": "2020-09-16T23:32:54.42402Z", "updated": "2020-09-16T23:32:56.536936Z", "completed": "2020-09-16T23:32:56.536936Z", "errors": null, "outputs": [ "b9ec5d6b-8753-440a-852c-528188f914d0/20200729_053412_88_105e/20200729_053412_88_105e_metadata.json", "b9ec5d6b-8753-440a-852c-528188f914d0/20200729_053412_88_105e/20200729_053412_88_105e_3B_AnalyticMS.tif" ] } ] }