Overlap Object

Overlap details are only provided if searching by a bounding box (or polygon in the future), it will be absent if searching by a point. The Overlap object has the following structure:

{
  "area": 0,
  "percent": {
    "scene": 0,
    "search": 0
  },
  "polygon": []
}

field	data type	purpose
area	number	area in sq km of the overlap between search and result
percent (scene)	number	percent of the whole scene the polygon represents
percent (search)	number	percent of the original search area (if bounding box) the AOI represents, will be -1 for a point search, and may be greater than 100% if the original search is less than the suppliers minimum order
polygon	[][]number	polygon of overlap area. This polygon is what will be ordered if the supplier supports ordering an area of interest

Pricing Object

Regardless of search criteria, we endeavor to provide a price for your area of interest rather than purchasing the whole scene.
To enable this, when your search by a point, or for less than a suppliers minimum order, we construct an area of interest that will meet this minimum order to provide the minimum price.
For this reason it is critically important that you review the polygon found in overlap.polygon. As this will be the polygon ordered from the supplier if they support AOI ordering.
Many suppliers require different licencing or pricing to licence additional seats to the imagery, as well as allowing purchase of whole scenes, or just the Area Of Interest (AOI), this object provides details for the different pricing options.
All pricing is provided in US cents.
The contents of the pricing object has the following structure:

{
  "base": 0,
  "seats": [
      {
          "min": 0,
          "max": 0,
          "additional": 0
      }
  ]
}

field	data type	purpose
base	number	the base static price for the imagery, this is the portion the image will always cost
seats	array	A list of details for the amount the price changes by for additional seats
min	number	minimum number of seats to which this price range applies
max	number	maximum number of seats to which this price range applies (0 represents no maximum)
additional	number	the additional price to be paid in this range

Many suppliers require different licencing or pricing to licence additional seats to the imagery.
All imagery will cost its base price, and purchases with additional seats may attract additional charges, described by this structure.
If the seats array is empty, no additional charge is applicable for any seat number.
If the seats array is populated, each object represents pricing for a range of seats, and the matching objects additional amount to be added to base for purchasing this imagery. Note: add only the matching seats cases additional amount, do not aggregate from lower seat counts.
The applicable entry is one where the required number of seats is: - greater than or equal to that entry's min value, and - less than or equal to that entries max value, or that entries max value is 0 (representing no upper bounds)
When purchasing the imagery, the amount charges to the requesting users account, will be base + additional for the appropriate seats entry. Where the appropriate pricing object is selected by your order request (see order endpoint documentation).

Annotations

The annotations field is there to inform you of any issues processing your request for the given scene. It includes non fatal errors and information on how they were handled which may affect your ordering of the imagery.
Annotations only appear for a handful of notable cases. To this end, all annotations begin with a 4 letter message code, followed by a colon ":" and a space before a human readable message.
The currently returned annotations are:

PONT: Your Point search was enlarged to an area centered on your search to meet the suppliers Minimum Order Quantity of sqkm

Returned when a point search was performed, to explain where the overlap area and polygon came from. The imagery ordered will be the polygon found in overlap.polygon

ENLR: The intersection of your search area and this scene was less than the suppliers minimum order of sqkm, the AOI was enlarged to meet the minimum order

Returned when an AOI is inflated to meet the minimum order, or the intersection of a search area and the scene must be inflated to meet the minimum order. The imagery ordered will be the polygon found in overlap.polygon which may differ from the provided search area, but will always include the portion of the image that is/is part of the AOI.

NAOI: This supplier does not support AOI imagery ordering

This supplier does not support Area Of Interest orders, The overlap.polygon is informative about the search with regard to the scene. Any pricing provided is for the scene as a whole which is what will be provided when ordering this scene.

COVR: Your AOI covers this whole scene. Pricing is for the whole scene

The provided Area Of Interest covers the whole scene, the overlap.polygon is likely to match the bounding polygon. Pricing provided is for the whole scene.

Ordering Scenes or Areas of Interest

From version 2020-12 and onwards, the pricing provided by a search result is always for the searched Area Of Interest, or a minimum order containing it.
Ordering the search ID will always order a trimmed scene if it is smaller than the scene and the supplier supports AOI ordering (see search result annotations).
As a result the trim parameter of the order request from prior versions is now depreciated and will be ignored if included in requests. Integrators are encouraged to remove the trim parameter to avoid any future conflicts or revised requirements.

Version 1.0.0:

Initial version of API, supported:

• search imagery
• order imagery
• orders list
• order get
• order
• resource get

Version 1.1.0:

Internal update for platform update:

• added signature management internal api
• added admin pages to manage orders

Version 1.2.0:

Added SI Imaging as an imagery supplier/vendor

Version 1.3.0:

Added signup procedure for non activated accounts

Version 2.0.0:

AOI ordering for imagery
Search response structure changed:

• added sceneID field
• added annotations
• field - changed overlap to object with children:
  • area
  • percent
  • polygon
• Changed price field to include new field aoi which also contains pricing information for AOI order

Order object changes:

• added trim field

Version 2.0.1:

Added new resource types:

• `img_jp2` for JPEG Core 200 format imagery, and
• `meta_bundle` for aggregated or otherwise bundled metadata

Version 2.0.2:

Updated order status labels to clarify state ('manual' for awaiting supplier non-automated response caused confusion)

Version 2.0.3:

Added additional resource types for scene geometry:

• geo_json for geometry defined in the geoJSON standard
• geo_kml for geometry defined in Keyhole Markup Language (KML)
• geo_shp for bundled shapefiles and their metadata (zip file containing shp, shx, dbf and prj files)
• geo_bundle for geometry of a unknown or miscellaneous format provided by the supplier

Version 2020-12:

• Change in version number format (2020-12 rather than 3.0.0.
• Coordinates in a point are reversed order to be [long, lat] to be consistent with geoJSON and similar formats as an X, Y format.
• API account delete functionality.
• Webhook events now have a wrapper to their payload to support future planned usage
• MOQ ordering; all searches return an AOI price, increased to the supplier minimum order if it was less than it. This causes several dependent changes:
  • overlap field is always included and includes the polygon that will be ordered
  • overlap.percent is now an object with two fields search and scene
  • price is now a single pricing object that provides the AOI price, scene pricing is no longer provided
  • remove trim as an ordering parameter