Pixxel Archives API

openapi: 3.0.0
info:
  description: Swagger doc for Stargate
  title: stargate AOI Archives API
  contact:
    name: Team-Identity
    email: identity@pixxel.co.in
  version: v0.1.0
servers:
- url: https://api.pixxel.space
tags:
- name: Archives
paths:
  /v0/archives/collections:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns a list of all collections available under archives.
      tags:
      - Archives
      summary: List all collections
      operationId: ListCollections
      parameters:
      - description: Collection IDs
        name: ids
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cosmos.modifiedSuccessResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
      externalDocs:
        description: View developer guide to learn more
        url: /developer/orders/stac
  /v0/archives/collections/{cid}:
    get:
      security:
      - ApiKeyAuth: []
      description: Get a STAC collection by it's ID
      tags:
      - Archives
      summary: Get a collection
      operationId: GetCollectionById
      parameters:
      - description: Collection ID
        name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cosmos.originalCollectionSuccessResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
      externalDocs:
        description: View developer guide to learn more
        url: /developer/orders/stac
  /v0/archives/collections/{cid}/items:
    get:
      security:
      - ApiKeyAuth: []
      description: List of items present in a collection
      tags:
      - Archives
      summary: List items in a collection
      operationId: ListItemInCollection
      parameters:
      - description: Collection ID
        name: cid
        in: path
        required: true
        schema:
          type: string
      - description: Limit
        name: limit
        in: query
        schema:
          type: integer
      - description: Offset
        name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cosmos.FeatureCollection'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
      externalDocs:
        description: View developer guide to learn more
        url: /developer/orders/archive
  /v0/archives/collections/{cid}/items/{id}:
    get:
      security:
      - ApiKeyAuth: []
      description: Get a STAC item by it's collection and item ID
      tags:
      - Archives
      summary: Get item
      operationId: GetCollectionItemById
      parameters:
      - description: Collection ID
        name: cid
        in: path
        required: true
        schema:
          type: string
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cosmos.Item'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
      externalDocs:
        description: View developer guide to learn more
        url: /developer/orders/archive
  /v0/archives/search:
    post:
      security:
      - ApiKeyAuth: []
      description: Search for STAC items according to attributes of the item
      tags:
      - Archives
      summary: Search all items
      operationId: SearchItemInArchive
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cosmos.Search'
        description: Request Body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cosmos.FeatureCollection'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.ErrorResponse'
      externalDocs:
        description: View developer guide to learn more
        url: /developer/orders/search-archive
components:
  schemas:
    cosmos.originalCollectionSuccessResponse:
      type: object
      properties:
        created_at:
          type: string
          example: '2023-08-06T20:46:56.815552Z'
        description:
          type: string
          example: A collection description
        extent:
          type: object
          properties:
            spatial:
              type: object
              properties:
                bbox:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
            temporal:
              type: object
              properties:
                interval:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
        id:
          type: string
          example: pixxel-dd2
        license:
          type: string
          example: proprietary
        links:
          type: array
          items:
            $ref: '#/components/schemas/cosmos.Link'
        providers:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
                example: Pixxel is a space data company
              name:
                type: string
                example: Pixxel
              roles:
                type: array
                items:
                  type: string
                example:
                - producer
              url:
                type: string
                example: https://pixxel.space
        stac_extensions: {}
        stac_version:
          type: string
          example: 0.1.0
        summaries: {}
        title:
          type: string
          example: Pixxel-DD01
        type:
          type: string
          example: Collection
        updated_at:
          type: string
          example: '2023-08-06T20:46:56.815552Z'
    cosmos.Geometry:
      type: object
      properties:
        type:
          description: The type of the geometry
          allOf:
          - $ref: '#/components/schemas/cosmos.GeometryType'
          x-order: '30'
          example: Polygon
        coordinates:
          x-order: '31'
    cosmos.RasterBand:
      type: object
      properties:
        nodata:
          description: The nodata value of the band
          type: number
          example: -9999
        offset:
          description: The offset of the band
          type: number
          example: 0
        scale:
          description: The scale of the band
          type: number
          example: 1
        spatial_resolution:
          description: The spatial resolution of the band in meters
          type: number
          example: 10
    common.Error:
      type: object
      properties:
        code:
          type: string
        details: {}
        message:
          type: string
    cosmos.GeometryType:
      type: string
      enum:
      - Point
      - MultiPoint
      - LineString
      - MultiLineString
      - Polygon
      - MultiPolygon
      - GeometryCollection
      x-enum-varnames:
      - GeometryPoint
      - GeometryMultiPoint
      - GeometryLineString
      - GeometryMultiLineString
      - GeometryPolygon
      - GeometryMultiPolygon
      - GeometryCollection
    cosmos.Item:
      type: object
      required:
      - id
      properties:
        id:
          description: The unique identifier of the item
          type: string
          x-order: '10'
          example: 20201211_223832_CS25
        type:
          description: The type of the item
          type: string
          x-order: '11'
          example: Feature
        collection:
          description: The collection the item belongs to
          type: string
          x-order: '12'
          example: simple-collection_2
        stac_version:
          description: The version of the STAC specification
          type: string
          x-order: '13'
          example: 1.0.0
        stac_extensions:
          description: The extensions used in the item
          type: array
          items:
            type: string
          x-order: '14'
          example:
          - https://stac-extensions.github.io/eo/v1.0.0/schema.json
          - https://stac-extensions.github.io/projection/v1.0.0/schema.json
          - https://stac-extensions.github.io/view/v1.0.0/schema.json
        bbox:
          description: The bounding box of the item
          type: array
          items:
            type: string
          x-order: '15'
          example:
          - '172.91173669923782'
          - '1.3438851951615003'
          - '172.95469614953714'
          - '1.3690476620161975'
        geometry:
          description: The geometry of the item
          allOf:
          - $ref: '#/components/schemas/cosmos.Geometry'
          x-order: '16'
        properties:
          allOf:
          - $ref: '#/components/schemas/cosmos.Properties'
          x-order: '17'
        assets:
          description: "Example\n```\n{\n\t\"B091\": {\n\t\t\"href\": \"<path_to_asset>\",\n     \"type\": \"image/tiff\",\n     \"roles\": [\"data\"],\n     \"title\": \"B091\",\n     \"eo:bands\": [\n\t\t\t{\n\t\t\t\t\"fwhm\": 0,\n             \"name\": \"B091\",\n             \"solar_irradiance\": 1984.75,\n             \"center_wavelength\": 490,\n             \"common_name\": \"red\",\n         }\n\t\t],\n     \"raster:bands\": [\n         {\n             \"scale\": 0.00002,\n             \"nodata\": 0,\n         \t\"offset\": 0,\n         \t\"spatial_resolution\": 30\n       \t}\n\t\t]\n\t},\n\t\"B013\": {\n\t\t\"href\": \"<path_to_asset>\",\n    \t\"type\": \"image/png\",\n    \t\"roles\": [\"data\"],\n    \t\"title\": \"B013\",\n    \t\"eo:bands\": [\n    \t\t{\n\t\t\t\t\"fwhm\": 0,\n            \t\"name\": \"B013\",\n            \t\"common_name\": \"blue\",\n            \t\"solar_irradiance\": 1965.25,\n            \t\"center_wavelength\": 493\n        \t}\n    \t],\n    \t\"raster:bands\": [\n     \t{\n            \t\"scale\": 0.00002,\n            \t\"nodata\": 0,\n            \t\"offset\": 0,\n            \t\"spatial_resolution\": 30\n        \t}\n    \t]\n  }\n}                                                                                                                                                                                                              // The properties of the item"
          type: object
          additionalProperties:
            $ref: '#/components/schemas/cosmos.Asset'
          x-order: '18'
        links:
          description: The links of the item
          type: array
          items:
            $ref: '#/components/schemas/cosmos.Link'
          x-order: '19'
    cosmos.Asset:
      type: object
      properties:
        eo:bands:
          description: "Example\n```\n[\n\t{\n\t\t\"fwhm\": 0,\n\t\t\"name\": \"B013\",\n\t\t\"common_name\": \"blue\",\n\t\t\"solar_irradiance\": 1965.25,\n\t\t\"center_wavelength\": 493\n\t}\n]"
          type: array
          items:
            $ref: '#/components/schemas/cosmos.EoBand'
        href:
          description: The HREF of the asset
          type: string
          example: https://example.com/asset.tif
        raster:bands:
          description: "Example\n```\n[\n\t{\n\t\t\"scale\": 0.00002,\n\t\t\"nodata\": 0,\n\t\t\"offset\": 0,\n\t\t\"spatial_resolution\": 30\n\t}\n]"
          type: array
          items:
            $ref: '#/components/schemas/cosmos.RasterBand'
        roles:
          description: The roles of the asset (e.g., "data", "metadata")
          type: array
          items:
            type: string
          example:
          - data
          - metadata
        title:
          description: A human-readable title for the asset
          type: string
          example: Example Asset Title
        type:
          description: The MIME type of the asset
          type: string
          example: image/tiff
    cosmos.Link:
      type: object
      required:
      - href
      - rel
      properties:
        href:
          description: The URL or reference the link points to
          type: string
          example: https://example.com
        rel:
          description: The relationship of the link (e.g., "self", "parent", "child")
          type: string
          example: self
        title:
          description: A human-readable title for the link
          type: string
          example: Example Link Title
        type:
          description: The MIME type of the linked resource (e.g., "application/json")
          type: string
          example: application/json
    cosmos.Properties:
      type: object
      properties:
        altitude:
          description: The altitude of the sensor in meters
          type: number
          example: 700
        constellation:
          description: The constellation name
          type: string
          example: TD1
        created:
          description: The date and time the item was created
          type: string
          example: '2022-01-01T10:00:00Z'
        datetime:
          type: string
          example: '2022-06-15T12:00:00Z'
        description:
          description: A description of the item
          type: string
          example: Example description of the dataset
        eo:cloud_cover:
          description: The percentage of the image covered by clouds
          type: number
          example: 23.5
        gsd:
          description: The ground sample distance in meters
          type: number
          example: 30
        instruments:
          description: The instruments used
          type: array
          items:
            type: string
          example:
          - VNIR
        license:
          description: The license of the item
          type: string
          example: CC-BY-4.0
        platform:
          description: The platform name
          type: string
          example: TD1
        proj:code:
          description: The EPSG code of the projection
          type: string
          example: EPSG:4326
        proj:shape:
          description: The shape of the projection
          type: array
          items:
            type: integer
          example:
          - 10980
          - 10980
        proj:transform:
          description: the affine transform coefficients
          type: array
          items:
            type: number
          example:
          - 0
          - 10
          - 500000
          - 0
          - -10
          - 1000000
        rd:anomalous_pixels:
          description: The percentage of anomalous pixels
          type: number
          example: 0.01
        rd:earth_sun_distance:
          description: The distance between the Earth and the Sun
          type: number
          example: 1
        rd:product_level:
          description: The product level
          type: string
          example: L2A
        rd:sat_id:
          description: The satellite ID
          type: string
          example: SAT-123
        rd:type:
          description: The type of radiometric data
          type: string
          example: Reflectance
        sci:doi:
          description: The DOI of the scientific publication
          type: string
          example: 10.1234/sci_doi
        startdatetime:
          type: string
          example: '2022-01-01T00:00:00Z'
        title:
          description: The title of the item
          type: string
          example: Example Title
        updated:
          description: The date and time the item was last updated
          type: string
          example: '2022-06-01T10:00:00Z'
        view:off_nadir:
          description: The angle between the sensor and the vertical
          type: number
          example: 5
        view:scene_center_lat:
          description: The latitude of the center of the scene
          type: number
          example: 12.3456
        view:scene_center_lon:
          description: The longitude of the center of the scene
          type: number
          example: -76.5432
        view:sun_azimuth:
          description: The angle between the sun and the north
          type: number
          example: 135
        view:sun_elevation:
          description: The angle between the sun and the horizon
          type: number
          example: 45
    cosmos.EoBand:
      type: object
      properties:
        center_wavelength:
          description: The center wavelength of the band in micrometers
          type: number
          example: 0.443
        common_name:
          description: The common name of the band (e.g., "coastal", "blue", "green")
          type: string
          example: coastal
        fwhm:
          description: The full width at half maximum (FWHM) of the band in micrometers
          type: number
          example: 0.027
        name:
          description: The unique name of the band
          type: string
          example: B01
        solar_irradiance:
          description: The solar irradiance at the top of the atmosphere for the band in W/m²/μm
          type: number
          example: 1901
    common.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/common.Error'
    cosmos.Search:
      type: object
      properties:
        bbox:
          description: 'Only features that have a geometry that intersects the bounding box are selected. The bounding box is provided as four numbers:


            Lower left corner, coordinate axis 1

            Lower left corner, coordinate axis 2

            Upper right corner, coordinate axis 1

            Upper right corner, coordinate axis 2

            The coordinate reference system of the values is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate reference system is specified in the parameter bbox-crs.


            For WGS84 longitude/latitude the values are in most cases the sequence of minimum longitude, minimum latitude, maximum longitude and maximum latitude. However, in cases where the box spans the antimeridian the first value (west-most box edge) is larger than the third value (east-most box edge).


            If a feature has multiple spatial geometry properties, it is the decision of the server whether only a single spatial geometry property is used to determine the extent or all relevant geometries.


            Example: The bounding box of the New Zealand Exclusive Economic Zone in WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented in JSON as [160.6, -55.95, -170, -25.89] and in a query as bbox=160.6,-55.95,-170,-25.89'
          type: array
          items:
            type: number
          example:
          - 3
          - 4
          - 5
          - 6
        collections:
          description: Array of Collection IDs to include in the search for items. Only Item objects in one of the provided collections will be searched.
          type: array
          items:
            type: string
        datetime:
          description: 'Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.


            Examples:


            A date-time: "2018-02-12T23:20:50Z"

            A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"

            Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

            Only features that have a temporal property that intersects the value of datetime are selected.


            If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.'
          type: string
          example: 2020-04-05T11:56:49.865Z/2023-06-05T11:56:49.865Z
        ids:
          type: array
          items:
            type: string
        intersects:
          description: 'pointGeoJSON (object) or multipointGeoJSON (object) or linestringGeoJSON (object) or multilinestringGeoJSON (object) or polygonGeoJSON (object) or multipolygonGeoJSON (object) or geometrycollectionGeoJSON (object) (geometryGeoJSON)

            The optional intersects parameter filters the result Items in the same was as bbox, only with a GeoJSON Geometry rather than a bbox.'
          allOf:
          - $ref: '#/components/schemas/cosmos.Geometry'
        limit:
          type: integer
          default: 10
          example: 10
        offset:
          type: integer
          example: 0
        query:
          description: "a query object to search/filter according to the properites of the stac-item\n `\"query\": {\n   \"cloudcover\": {\n       \"gt\": 0,\n       \"lt\": 10\n   },\n   \"bands\": {\n       \"eq\": [\n           \"RGB\",\n           \"B001\",\n           \"B002\"\n       ]\n   }\n  },`"
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
        sortby:
          description: "a sortby object to sort the items by the properties of the stac-item\n\"sortby\": [\n{\n    \"field\": \"properties->>'datetime'\",\n    \"direction\": \"desc\"\n}\n]"
          type: array
          items:
            type: object
            additionalProperties:
              type: string
    cosmos.modifiedSuccessResponse:
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/cosmos.originalCollectionSuccessResponse'
    cosmos.FeatureCollection:
      type: object
      properties:
        type:
          description: The type of the collection
          type: string
          x-order: '1'
          example: FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/cosmos.Item'
          x-order: '2'
        links:
          type: array
          items:
            $ref: '#/components/schemas/cosmos.Link'
          x-order: '3'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header