definitions.yaml

###############################################################################
##                                                                           ##
##                                 DEFINITIONS                               ##
##                                                                           ##
##                     (c) Airbus Defense and Space Geo                      ##
##                                                                           ##
##                                                                           ##
##                    Contact: frederic.bages@airbus.com                     ##
##                                                                           ##
###############################################################################

info:
  title: Airbus Defense and Space Geo - Common Language Definitions
  description: |
    This document describes Airbus Defense and Space Geo common language definitions. Definitions are referenced from other Geo API specifications provided that their meaning and format is the same. 
    
  version: '1.0-alpha1'

###############################################################################
##                                                                           ##
##                           GENERAL CONFIGuRATION                           ##
##                                                                           ##
###############################################################################

consumes:
  - application/json

produces:
  - application/x-yaml

schemes:
  - https

host: airbusgeo.github.io

swagger: '2.0'

###############################################################################
##                                                                           ##
##                           OBJECTS DOCUMENTATION                           ##
##                                                                           ##
###############################################################################

definitions:


  # START ------------------ Airbus DS Geo dictionary ------------------- START


  Id:
    description: An internal identifier.
    type: string

  acquisitionDate:
    description: Acquisition date of the image in ISO 8601 format
    type: string
    format: ISO 8601

  cloudCover:
    description: Percentage of the image covered by cloud (0 - 100).
    type: integer
    
  constellation: 
    description: The type of satellite used to acquire the image (Pleiades or SPOT).
    type: string
    enum: 
    - Pleiades
    - SPOT
    - TerraSAR_X_Mission

  incidenceAngle:
    description: The incidence angle is the angle from the target point of view. It represents the angle between the ground normal and look direction from the satellite, combining the pitch and roll angles.
    type: number
    format: float

  snowCover: 
    description: Percentage of the image covered by snow (0 - 100).
    type: integer

  productType:
    description: A product type.
    type: string
    enum:
    - "PleiadesArchiveMono"
    - "PleiadesArchiveStereo"
    - "PleiadesArchiveTristereo"
    - "SPOTArchive1.5Mono"
    - "SPOTArchive1.5Stereo"
    - "SPOTArchive1.5Tristereo"
    - "SPOTArchive2.5BW"
    - "SPOTArchive2.5Color"
    - "SPOTArchive5BW"
    - "SPOTArchive5Color"
    - "SPOTArchive10BW"
    - "SPOTArchive10Color"
    - "SPOTArchive20Color"
    - "TSXArchiveHS"
    - "TSXArchiveSC"
    - "TSXArchiveSL"
    - "TSXArchiveST"
    - "TSXArchiveSM"
    - "TSXArchiveWS"
    - "WorldDEMArchiveStandard"
    - "WorldDEMArchiveCore"
    - "WorldDEMArchiveDTM"

  bbox:
    description: 'A bounding box definition. A bounding box is composed of 4 ordered values: the minimum X value, the minimum Y value, the maximum X value and the maximum Y value.'
    type: array
    example: [ -10.0, -10.0 , 10, 10 ]
    items:
      type: number
      minItems: 4
      maxItems: 4

  orbitDirection:
    description: "The satellite orbit direction during the acquisition."
    type: string
    enum:
    - ASCENDING
    - DESCENDING

  antennaLookDirection:
    description: "The antenna look direction during the acquisition."
    type: string
    enum:
    - LEFT
    - RIGTH

  illuminationAzimuthAngle:
    description: "Meam illumination/solar azimuth angle given in degrees."
    type: number
    format: float

  illuminationElevationAngle:
    description: "Mean illumination/solar elevation angle given in degrees."
    type: number
    format: float

  azimuthAngle:
    description: "Angle formed between the North and the satellite."
    type: number
    format: float

  # END   ------------------ Airbus DS Geo dictionary -------------------   END


  # START -------------- Airbus DS Geo request properties --------------- START


  in_polygon_wkt:
    description: "A POLYGON geometry in the Well-known text format. Example: POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"
    type: string
    format: 'WKT Geometric objects'
    example: 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'

  in_acquisitionDate_interval:
    description: "A date or date interval that must match the acquisition date. Example: [2017-01-01,2017-02-01[ to select all products acquired in January 2017. "
    type: string
    format: 'Interval of dates in ISO 8601'
    example: '[2017-01-01,2017-02-01['

  in_resolution_interval:
    description: "A number or number range that must match the resolution in meter. Example: 1.5] to select all products with a resolution inferior or equal to 1.5 meter."
    type: string
    format: 'Interval of resolution in meter'
    example: '[0.5,1.5]'

  in_incidenceAngle_interval:
    description: "A number or number range that must match the incidence angle in degrees. Example: 30] to select all products with an incidence angle inferior or equal to 30 degrees."
    type: string
    format: 'Interval of incidence angle in degrees'
    example: '[0,30]'

  in_cloudCover_interval:
    description: "A number or number range that must match the cloud coverage in percentage (min 0%, max 100%). Example: 10[ to select all products with a cloud coverage less than 10 percent."
    type: string
    format: 'Interval of cloud coverage in percent'
    example: "[0,15]"
    
  in_snowCover_interval:
    description: "A number or number range that must match the product snow coverage in percentage (min 0%, max 100%). Example: [50,90] to select all products with a partial snow coverage of at least 50 percent but no more than 90 percent."
    type: string
    format: 'Interval of cloud coverage in percent'
    example: '[0,15]'


  # END   -------------- Airbus DS Geo request properties ---------------   END


  # START ------------------- GeoJSON definitions ----------------------- START


  # The GeoJSON FeatureCollection is intended to be extended in API specifications with service specific features.
  # Example:
  #
  # GeoJSON FeatureCollection:
  #   description: GeoJSON FeatureCollection object.
  #   allOf:
  #   - $ref: 'https://airbusgeo.github.io/api-docs/definitions.yaml#/definitions/GeoJSON FeatureCollection'
  #   - type: object
  #     properties:
  #       features:
  #       description: the array of matching products as GeoJSON feature objects.
  #       type: array
  #       items:
  #          $ref: '#/definitions/GeoJSON Feature'
  GeoJSON FeatureCollection:
    description: 'A GeoJSON FeatureCollection object.'
    type: object
    properties:
      type:
        description: the result item type (always equals to "FeatureCollection")
        type: string
        enum: [ "FeatureCollection" ]


  # The GeoJSON Feature is intended to be extended in API specifications with service specific properties.
  # Example:
  #
  # GeoJSON Feature:
  #   description: GeoJSON feature object.
  #   allOf:
  #   - $ref: 'https://airbusgeo.github.io/api-docs/definitions.yaml#/definitions/GeoJSON Feature'
  #   - type: object
  #     properties:
  #       properties:
  #          $ref: '#/definitions/GeoJSON Feature Properties'
  GeoJSON Feature:
    description: A GeoJSON feature object.
    type: object
    properties:
      id:
        description: The internal identifier.
        type: string
      bbox:
        $ref: 'https://airbusgeo.github.io/api-docs/definitions.yaml#/definitions/bbox'
      geometry:
        $ref: 'https://airbusgeo.github.io/api-docs/definitions.yaml#/definitions/GeoJSON Geometry'
      type:
        description: The feature type (always equals to "Feature")
        type: string
        enum: [ "Feature" ]

  GeoJSON Geometry:
    description: A GeoJSON geometry describing the feature (point, polygon, multi-polygon, ...)
    type: object
    properties:
      type:
        description: The type of the geometry.
        type: string
        enum: ["Point","MultiPoint","LineString","MultiLineString","Polygon","MultiPolygon"]
      coordinates:
        description: the geometry coordinates; depends on the geometry type (see GeoJSON specification of Geometry objects).
        type: array
        items:
          $ref: '#/definitions/GeoJSON Point'

  GeoJSON Point:
    description: A GeoJSON point definition.
    type: array
    example: '[ 10, 10 ]'
    items:
      type: integer


  # END   ------------------- GeoJSON definitions -----------------------   END


  # START ----------------- OpenSearch definitions ---------------------- START


  # The OpenSearch Response is intended to be extended in API specifications with service specific properties.
  # Example:
  #
  # OpenSearch Response:
  #   description: 'OpenSearch response object in JSon format.'
  #   allOf:
  #   - $ref: 'https://airbusgeo.github.io/api-docs/definitions.yaml#/definitions/OpenSearch Response'
  #   - type: object
  #     properties:
  #       query:
  #          $ref: '#/definitions/OpenSearch Query'
  OpenSearch Response:
    description: 'OpenSearch response object in JSon format.'
    type: object
    properties:
      totalResults:
        description: The number of search results available for the current search.
        type: integer
      startIndex:
        description: The index of the first search result in the current set of search results.
        type: integer
      itemsPerPage:
        description: The number of search results returned per page.
        type: integer


  # END   ----------------- OpenSearch definitions ----------------------   END




        
###############################################################################
##                                                                           ##
##                         END POINTS DOCUMENTATION                          ##
##                                                                           ##
###############################################################################

paths:

  /api-docs/definitions.yaml:
    get:
      summary: Return all common Airbus DS Geo definitions in YAML format.
      description: |
        Definitions are based on the following specifications:
        * [GeoJSON](http://geojson.org/geojson-spec.html) version 1.0
        * [OpenSearch](http://www.opensearch.org/Specifications/OpenSearch/1.1) version 1.1 Draft 5
        * [OpenSearch Geo extension](http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1) version 1.0 Draft 1
        * [OpenSearch Time extension](http://www.opensearch.org/Specifications/OpenSearch/Extensions/Time/1.0/Draft_1) version 1.0 Draft 1
        * [OpenSearch for Earth Observation extension](https://portal.opengeospatial.org/files/65168) version of October 29th, 2014
        * [Earth Observation Metadata profile of Observations & Measurements](http://docs.opengeospatial.org/is/10-157r4/10-157r4.html) version 1.1
      responses:
        '200':
          description: Request successful