Retrieve the results produced by pipeline intervals - either scoped to a single pipeline or across all pipelines - including per-interval status, cost, probability of collection, band metadata, and the analytics and metadata download URLs used to deliver each delivered image.
openapi: 3.0.3
info:
title: SkyWatch EarthCache API
description: >-
The EarthCache API gives developers a single, provider-agnostic interface to
discover, price, order, and deliver commercial satellite imagery and
geospatial data. Create an archive Search over historical imagery, stand up a
Pipeline that monitors an area of interest and delivers imagery on a
schedule, retrieve interval results with analytics and metadata download
URLs, estimate cost, manage reusable output configurations and saved
locations, and subscribe to platform events via callback URIs. All requests
are authenticated with an `x-api-key` header. Imagery is billed per square
kilometre with resolution-based purchase minimums.
This description is authored by API Evangelist for the apis.io network and is
grounded in SkyWatch's public EarthCache API specification
(v1.7, https://api-docs.earthcache.com/). It is not an official SkyWatch
artifact.
version: '1.7'
contact:
name: SkyWatch Support
url: https://skywatch.com/support
email: support@skywatch.com
servers:
- url: https://api.skywatch.co/earthcache
description: EarthCache production
security:
- ApiKey: []
tags:
- name: Archive Search
description: Query historical imagery and retrieve matching search results.
- name: Pipelines
description: Standing orders that monitor an AOI and deliver imagery on a schedule.
- name: Interval Results
description: Results and delivery URLs produced by pipeline intervals.
- name: Cost Estimation
description: Estimate the cost of locations, intervals, and pipelines.
- name: Outputs
description: Reusable output configurations - format, bands, and mosaicking.
- name: Locations
description: Reusable server-side areas of interest from KML or GeoJSON.
- name: Subscriptions
description: Callback-based subscriptions to EarthCache platform events.
paths:
/archive/search:
post:
tags:
- Archive Search
summary: Create a search
operationId: createArchiveSearch
description: >-
Creates an asynchronous archive search over historical imagery for an
area of interest and date window and returns the search id used to
retrieve results.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Search created.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchCreated'
'400':
description: Invalid search request.
/archive/search/{id}/search_results:
get:
tags:
- Archive Search
summary: Get search results
operationId: getArchiveSearchResults
description: >-
Returns the results of a previously created search. Returns 202 while the
search is still processing and 200 with results once complete.
parameters:
- $ref: '#/components/parameters/SearchId'
responses:
'200':
description: Search results.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResults'
'202':
description: Search still processing; retry after a short delay.
/pipelines:
get:
tags:
- Pipelines
summary: List pipelines
operationId: listPipelines
responses:
'200':
description: A list of pipelines.
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineList'
post:
tags:
- Pipelines
summary: Create a pipeline
operationId: createPipeline
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRequest'
responses:
'201':
description: Pipeline created.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
delete:
tags:
- Pipelines
summary: Delete multiple pipelines
operationId: deletePipelines
description: Delete multiple pipelines by id.
responses:
'204':
description: Pipelines deleted.
/pipelines/{id}:
get:
tags:
- Pipelines
summary: Get a pipeline
operationId: getPipeline
parameters:
- $ref: '#/components/parameters/PipelineId'
responses:
'200':
description: The pipeline.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
patch:
tags:
- Pipelines
summary: Update a pipeline
operationId: updatePipeline
parameters:
- $ref: '#/components/parameters/PipelineId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRequest'
responses:
'200':
description: Pipeline updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
delete:
tags:
- Pipelines
summary: Delete a pipeline
operationId: deletePipeline
parameters:
- $ref: '#/components/parameters/PipelineId'
responses:
'204':
description: Pipeline deleted.
/pipelines/{id}/interval_results:
get:
tags:
- Interval Results
summary: List interval results for a pipeline
operationId: listPipelineIntervalResults
description: >-
The most common method of accessing pipeline results - lists the interval
results produced by a single pipeline, including delivery URLs.
parameters:
- $ref: '#/components/parameters/PipelineId'
responses:
'200':
description: A list of interval results.
content:
application/json:
schema:
$ref: '#/components/schemas/IntervalResultList'
/pipelines/calculate:
post:
tags:
- Cost Estimation
summary: Calculate pipeline cost and probability of collection
operationId: calculatePipeline
description: >-
Calculate the cost of the area and intervals of a pipeline, and the
probability of collection for any tasking intervals.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRequest'
responses:
'200':
description: Calculated pipeline cost estimate.
content:
application/json:
schema:
$ref: '#/components/schemas/CostEstimate'
/price/calculate:
post:
tags:
- Cost Estimation
summary: Calculate price of a location and intervals
operationId: calculatePrice
description: >-
Calculate the cost of a specified location and intervals, taking purchase
minimums and pre-purchase discounts into account.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PriceRequest'
responses:
'200':
description: Calculated price.
content:
application/json:
schema:
$ref: '#/components/schemas/CostEstimate'
/price/{resolution}:
get:
tags:
- Cost Estimation
summary: Get price information
operationId: getPrice
description: Get price information for the caller's plan and an optional resolution.
parameters:
- name: resolution
in: path
required: true
description: Resolution band (for example low, medium, high, very_high).
schema:
type: string
responses:
'200':
description: Price information.
content:
application/json:
schema:
$ref: '#/components/schemas/CostEstimate'
/interval_results:
get:
tags:
- Interval Results
summary: List all interval results
operationId: listIntervalResults
description: List interval results across all of the caller's pipelines.
responses:
'200':
description: A list of interval results.
content:
application/json:
schema:
$ref: '#/components/schemas/IntervalResultList'
/outputs:
get:
tags:
- Outputs
summary: List outputs
operationId: listOutputs
description: List the reusable output configurations available to the caller.
responses:
'200':
description: A list of outputs.
content:
application/json:
schema:
$ref: '#/components/schemas/OutputList'
/outputs/{id}:
get:
tags:
- Outputs
summary: Get an output
operationId: getOutput
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: The output configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/Output'
/locations:
get:
tags:
- Locations
summary: List locations
operationId: listLocations
responses:
'200':
description: A list of saved locations.
post:
tags:
- Locations
summary: Create a location
operationId: createLocation
description: >-
Create a saved location from KML or GeoJSON, abstracted into a reusable
server-side instance referenced by id.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
responses:
'201':
description: Location created.
/locations/{id}:
get:
tags:
- Locations
summary: Fetch a location
operationId: getLocation
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: The location.
patch:
tags:
- Locations
summary: Update a location
operationId: updateLocation
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
responses:
'200':
description: Location updated.
delete:
tags:
- Locations
summary: Delete a location
operationId: deleteLocation
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Location deleted.
/subscriptions:
get:
tags:
- Subscriptions
summary: List subscriptions
operationId: listSubscriptions
responses:
'200':
description: A list of subscriptions.
post:
tags:
- Subscriptions
summary: Create a subscription
operationId: createSubscription
description: >-
Register a callback URI to receive events from the EarthCache platform.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
responses:
'201':
description: Subscription created.
/subscriptions/{id}:
post:
tags:
- Subscriptions
summary: Update a subscription
operationId: updateSubscription
description: Update subscription properties such as callback_uri and status.
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
responses:
'200':
description: Subscription updated.
delete:
tags:
- Subscriptions
summary: Delete a subscription
operationId: deleteSubscription
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Subscription deleted.
/subscriptions/{id}/sample:
post:
tags:
- Subscriptions
summary: Send subscription samples
operationId: sampleSubscription
description: Send sample event payloads to the subscription's callback URI.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Sample sent.
/callbacks:
get:
tags:
- Subscriptions
summary: List callbacks
operationId: listCallbacks
description: >-
Returns a list of callback invocations over the last 3 months (the
retention period).
responses:
'200':
description: A list of callback invocations.
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
parameters:
SearchId:
name: id
in: path
required: true
description: The id of the search.
schema:
type: string
PipelineId:
name: id
in: path
required: true
description: The id of the pipeline.
schema:
type: string
schemas:
GeoJSON:
type: object
description: A GeoJSON geometry (typically a Polygon) describing the AOI.
properties:
type:
type: string
example: Polygon
coordinates:
type: array
items: {}
SearchRequest:
type: object
required:
- location
- start_date
- end_date
properties:
location:
$ref: '#/components/schemas/GeoJSON'
start_date:
type: string
format: date
end_date:
type: string
format: date
resolution:
type: array
items:
type: string
example:
- low
coverage:
type: number
interval_length:
type: integer
order_by:
type: array
items:
type: string
example:
- resolution
SearchCreated:
type: object
properties:
data:
type: object
properties:
id:
type: string
SearchResults:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
product_name:
type: string
source:
type: string
resolution:
type: number
cost:
type: number
preview_url:
type: string
format: uri
thumbnail_url:
type: string
format: uri
start_time:
type: string
format: date-time
PipelineRequest:
type: object
required:
- name
- start_date
- end_date
- aoi
- output
properties:
name:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
budget_per_km2:
type: number
max_cost:
type: number
cloud_cover_percentage:
type: number
min_aoi_coverage_percentage:
type: number
resolution_low:
type: number
resolution_high:
type: number
interval:
type: string
example: 1d
result_delivery:
type: object
properties:
max_latency:
type: string
example: 0d
priorities:
type: array
items:
type: string
example:
- latest
- highest_resolution
- lowest_cost
aoi:
$ref: '#/components/schemas/GeoJSON'
output:
type: object
properties:
id:
type: string
format:
type: string
example: geotiff
mosaic:
type: string
example: 'off'
tags:
type: array
items:
type: object
properties:
label:
type: string
value:
type: string
status:
type: string
example: active
sources:
type: object
properties:
include:
type: array
items:
type: string
example:
- Pleiades
- Spot
- PlanetScope
- Sentinel-2
Pipeline:
allOf:
- $ref: '#/components/schemas/PipelineRequest'
- type: object
properties:
id:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
PipelineList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Pipeline'
Band:
type: object
properties:
name:
type: string
data_type:
type: string
unit:
type: string
spectral_wavelength:
type: number
no_data_value:
type: number
raster_width:
type: number
raster_height:
type: number
IntervalResult:
type: object
properties:
id:
type: string
output_id:
type: string
pipeline_id:
type: string
status:
type: string
message:
type: string
interval:
type: string
total_interval_cost:
type: number
probability_of_collection:
type: number
results:
type: array
items:
type: object
properties:
analytics_url:
type: string
format: uri
metadata_url:
type: string
format: uri
capture_time:
type: string
format: date-time
metadata:
type: object
properties:
bands:
type: array
items:
$ref: '#/components/schemas/Band'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
IntervalResultList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/IntervalResult'
Output:
type: object
required:
- id
- name
- provider
properties:
id:
type: string
name:
type: string
description:
type: string
private:
type: boolean
cover_image:
type: object
properties:
url:
type: string
format: uri
alt_text:
type: string
provider:
type: object
required:
- name
properties:
name:
type: string
logo_url:
type: string
format: uri
OutputList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Output'
Location:
type: object
properties:
name:
type: string
geometry:
$ref: '#/components/schemas/GeoJSON'
CostEstimate:
type: object
properties:
cost:
type: number
currency:
type: string
example: USD
area_km2:
type: number
probability_of_collection:
type: number
Subscription:
type: object
required:
- callback_uri
properties:
id:
type: string
callback_uri:
type: string
format: uri
status:
type: string
example: active