basePath: /basemaps/v1
consumes:
  - application/json
definitions:
  APIError:
    description: >-
      An APIError communicates both general and field-specific errors. General
      errors include issues with core API usage as well as conflicts that
      involve more than one field. Field-specific errors correspond to an
      individual query parameter or request body attribute. Errors referencing
      nested fields will be dot-delimited (e.g. user.groups.0.name).
    properties:
      field:
        additionalProperties:
          $ref: '#/definitions/Errors'
        type: object
      general:
        $ref: '#/definitions/Errors'
    required:
      - general
      - field
    type: object
  Error:
    properties:
      message:
        description: A descriptive error message.
        type: string
    type: object
  Errors:
    description: A list of Errors.
    items:
      $ref: '#/definitions/Error'
    type: array
  GridContext:
    description: The grid context.
    properties:
      quad_size:
        description: The size of the square quad in pixels.
        type: integer
      resolution:
        description: The resolution of the maximum zoom level in meters.
        type: number
    type: object
  Mosaic:
    description: >-
      A Mosaic is an object that includes the core metadata for a mosaic that is
      published on the platform. A Mosaic object may have additional fields
      depending on its `product_type`.
    properties:
      _links:
        $ref: '#/definitions/MosaicLinks'
      bands:
        description: The number of bands in this mosaic.
        type: integer
      bbox:
        description: The bounding box representing the extent of the mosaic.
        items:
          format: float64
          type: number
        type: array
      coordinate_system:
        description: The coordinate system of this mosaic.
        type: string
      datatype:
        description: The type of data (byte, uint16, float32, etc).
        type: string
      first_acquired:
        description: >-
          The acquisition date of the oldest scene that contributed to this
          mosaic.
        format: date-time
        type: string
      grid:
        $ref: '#/definitions/GridContext'
      id:
        description: Mosaic identifier.
        format: uuid
        type: string
      interval:
        description: The interval of the mosaic.
        type: string
      item_types:
        description: The item types in this mosaic.
        items:
          type: string
        type: array
      last_acquired:
        description: >-
          The acquisition date of the newest scene that contributed to this
          mosaic.
        format: date-time
        type: string
      level:
        description: The maximum zoom level in XYZ scheme.
        type: integer
      name:
        description: A unique name for this mosaic.
        type: string
      product_type:
        description: >-
          The product type of this mosaics, currently supported is "timelapse",
          "basemap".
        type: string
      quad_download:
        description: Your quad download permission for this mosaic.
        type: boolean
    required:
      - bbox
      - coordinate_system
      - first_acquired
      - last_acquired
      - product_type
      - name
    type: object
  MosaicLinks:
    properties:
      _self:
        description: RFC 3986 URI representing the location of this object.
        type: string
      quads:
        description: RFC 3986 URI quad listing inside this mosaic.
        type: string
      tiles:
        description: XYZ tiles template link.
        type: string
    type: object
  MosaicListLinks:
    properties:
      _next:
        description: >-
          RFC 3986 URI representing the location of the next page of results.
          Omitted when there are no results, or the current page is the last.
        type: string
      _self:
        description: RFC 3986 URI representing the location of this object.
        type: string
    type: object
  MosaicListPage:
    properties:
      _links:
        $ref: '#/definitions/MosaicListLinks'
      mosaics:
        items:
          $ref: '#/definitions/Mosaic'
        type: array
    type: object
  MosaicSeries:
    description: >-
      A Mosaic Series is a container to group mosaics that have a specific
      criteria. This can be likened to a filter on top of mosaics, where a
      series can be defined as a TOI/AOI on a set timelapse mosaics.
    properties:
      _links:
        $ref: '#/definitions/MosaicSeriesLinks'
      first_acquired:
        description: >-
          The acquisition date of the oldest scene that contributed to this
          series.
        format: date-time
        type: string
      id:
        description: Mosaic series identifier.
        format: uuid
        type: string
      interval:
        description: The interval for the mosaics in the series.
        type: string
      last_acquired:
        description: >-
          The acquisition date of the newest scene that contributed to this
          series.
        format: date-time
        type: string
      name:
        description: A human readable name for this series.
        type: string
      product_type:
        description: The type of product this mosaic is.
        enum:
          - basemap
          - timelapse
          - l3m
        type: string
      selector:
        type: string
    required:
      - interval
      - name
      - product_type
    type: object
  MosaicSeriesLinks:
    properties:
      _self:
        description: RFC 3986 URI representing the location of this object.
        type: string
      mosaics:
        description: RFC 3986 URI to the mosaics inside this mosaic series.
        type: string
    type: object
  MosaicSeriesListLinks:
    properties:
      _next:
        description: >-
          RFC 3986 URI representing the location of the next page of results.
          Omitted when there are no results, or the current page is the last.
        type: string
      _self:
        description: RFC 3986 URI representing the location of this object.
        type: string
    type: object
  MosaicSeriesListPage:
    properties:
      _links:
        $ref: '#/definitions/MosaicSeriesListLinks'
      series:
        items:
          $ref: '#/definitions/MosaicSeries'
        type: array
    type: object
  MosaicSeriesMosaicsLinks:
    properties:
      _self:
        description: RFC 3986 URI representing the location of this object.
        type: string
    type: object
  MosaicSeriesMosaicsListPage:
    properties:
      _links:
        $ref: '#/definitions/MosaicSeriesMosaicsLinks'
      mosaics:
        items:
          $ref: '#/definitions/Mosaic'
        type: array
    type: object
  Quad:
    properties:
      _links:
        properties:
          _self:
            description: RFC 3986 URI representing the canonical location of this object.
            type: string
          download:
            description: RFC 3986 URI representing the canonical quad download location.
            type: string
          items:
            description: >-
              RFC 3986 URI representing the canonical location of the items make
              up the quad.
            type: string
          thumbnail:
            description: >-
              RFC 3986 URI representing the canonical location of the item
              thumbnail image.
            type: string
        type: object
      bbox:
        description: The bounding box representing the extent of the quad.
        items:
          format: float64
          type: number
        type: array
      id:
        description: Quad identifier.
        type: string
      percent_covered:
        description: The percentage of the GeoTIFF pixels that are not no-data values.
        format: float
        type: number
    required:
      - id
      - bbox
      - percent_covered
      - _links
    type: object
  QuadItem:
    properties:
      item_id:
        description: Planet item id.
        type: string
      item_type:
        description: Planet item type.
        type: string
      link:
        description: RFC 3986 URI representing the location of this item details.
        type: string
    type: object
  QuadItems:
    properties:
      items:
        items:
          $ref: '#/definitions/QuadItem'
        type: array
    type: object
  QuadListLinks:
    properties:
      _next:
        description: >-
          RFC 3986 URI representing the location of the next page of results.
          Omitted when there are no results, or the current page is the last.
        type: string
      _self:
        description: RFC 3986 URI representing the canonical location of this object.
        type: string
    type: object
  QuadListPage:
    properties:
      _links:
        $ref: '#/definitions/QuadListLinks'
      items:
        items:
          $ref: '#/definitions/Quad'
        type: array
    type: object
  Search:
    description: >-
      Search is a valid GeoJSON Polygon or MultiPolygon with 1500 or fewer
      vertices.
    example:
      coordinates:
        - - - -122.430755
            - 37.830635
          - - -122.430755
            - 37.822746
          - - -122.415158
            - 37.822746
          - - -122.415158
            - 37.830635
          - - -122.430755
            - 37.830635
      type: Polygon
    type: object
info:
  description: An API to interact with Mosaics generated on Planet's platform.
  title: Planet Mosaics API
  version: '1.0'
parameters:
  pAcquiredBetween:
    description: Acquired between comma separated dates or date-times
    in: query
    name: acquired__between
    type: string
  pAcquiredGt:
    description: Acquired greater than date or date-time
    in: query
    name: acquired__gt
    type: string
  pAcquiredLt:
    description: Acquired less than date or date-time
    in: query
    name: acquired__lt
    type: string
  pMosaicId:
    description: Mosaic identifier.
    in: path
    name: mosaic_id
    required: true
    type: string
  pQuadId:
    description: Quad identifier.
    in: path
    name: quad_id
    required: true
    type: string
  pSeriesId:
    description: Series identifier.
    in: path
    name: series_id
    required: true
    type: string
paths:
  /mosaics:
    get:
      description: List all accessible mosaics.
      operationId: listMosaics
      parameters:
        - description: Integer representing a specific page of results.
          in: query
          name: _page
          type: integer
        - description: Number of results to return per page.
          in: query
          name: _page_size
          type: integer
        - description: >-
            If provided, returns up to one result that exactly matches the
            provided value.
          in: query
          name: name__is
          type: string
        - description: >-
            If provided, returns only results that contain the fragment,
            case-insensitive.
          in: query
          name: name__contains
          type: string
      responses:
        '200':
          description: List of mosaics.
          schema:
            $ref: '#/definitions/MosaicListPage'
        '401':
          $ref: '#/responses/Forbidden'
        default:
          $ref: '#/responses/General'
      summary: List Mosaics
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}:
    get:
      description: Get a mosaic by id.
      operationId: getMosaic
      parameters:
        - $ref: '#/parameters/pMosaicId'
      responses:
        '200':
          description: Mosaic details.
          schema:
            $ref: '#/definitions/Mosaic'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Get Mosaic
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/grid:
    get:
      description: Get extended mosaic metadata by id.
      operationId: getMosaicGrid
      parameters:
        - $ref: '#/parameters/pMosaicId'
      responses:
        '200':
          description: Extended mosaic details.
          schema:
            $ref: '#/definitions/GridContext'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Get Mosaic Grid
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/quads:
    get:
      description: List of quad download links for a mosaic.
      operationId: getQuadDownloadLinks
      parameters:
        - $ref: '#/parameters/pMosaicId'
        - description: Comma separated bounding box in degrees as lx,ly,ux,uy.
          in: query
          name: bbox
          required: true
          type: string
        - description: If true, only return quad download links.
          in: query
          name: minimal
          type: boolean
        - description: Integer representing a specific page of results.
          in: query
          name: _page
          type: string
        - description: Number of results to return per page.
          in: query
          name: _page_size
          type: integer
      responses:
        '200':
          description: List of quad download links.
          schema:
            $ref: '#/definitions/QuadListPage'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: List Mosaic Quads
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/quads/search:
    post:
      description: List of quad download links for a mosaic.
      operationId: createQuadSearch
      parameters:
        - $ref: '#/parameters/pMosaicId'
        - description: Search request
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/Search'
        - description: If true, only return quad download links.
          in: query
          name: minimal
          type: boolean
        - description: Number of results to return per page.
          in: query
          name: _page_size
          type: integer
      responses:
        '302':
          description: 302 redirect to results.
          headers:
            Location:
              type: string
        '400':
          $ref: '#/responses/BadRequest'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Create a Mosaic Quad search
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/quads/search/{search_id}:
    get:
      description: List of quad download links for a mosaic.
      operationId: getQuadSearchLinks
      parameters:
        - $ref: '#/parameters/pMosaicId'
        - description: search id.
          in: path
          name: search_id
          required: true
          type: string
        - description: If true, return only download link.
          in: query
          name: minimal
          type: boolean
        - description: Integer representing a specific page of results.
          in: query
          name: _page
          type: string
        - description: Number of results to return per page.
          in: query
          name: _page_size
          type: integer
      responses:
        '200':
          description: List of quad download links.
          schema:
            $ref: '#/definitions/QuadListPage'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Quad Search Results
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/quads/{quad_id}:
    get:
      description: Get mosaic quad by id.
      operationId: getQuad
      parameters:
        - $ref: '#/parameters/pMosaicId'
        - $ref: '#/parameters/pQuadId'
      responses:
        '200':
          description: Mosaic quad details.
          schema:
            $ref: '#/definitions/Quad'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Get Mosaic Quad
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/quads/{quad_id}/full:
    get:
      description: Get a full quad download URL quad id.
      operationId: getQuadDownload
      parameters:
        - $ref: '#/parameters/pMosaicId'
        - $ref: '#/parameters/pQuadId'
      responses:
        '302':
          description: 302 redirect to quad download.
          headers:
            Location:
              type: string
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Get Mosaic Quad URL
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/quads/{quad_id}/items:
    get:
      description: List items that contributed to a quad.
      operationId: getQuadItems
      parameters:
        - $ref: '#/parameters/pMosaicId'
        - $ref: '#/parameters/pQuadId'
      responses:
        '200':
          description: List of items.
          schema:
            $ref: '#/definitions/QuadItems'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: List Mosaic Quad Items
      tags:
        - Basemaps and Mosaics
  /mosaics/{mosaic_id}/tiles:
    get:
      description: Get TileJSON for Mosaic. See https://github.com/mapbox/tilejson-spec
      operationId: getMosaicTileJSON
      parameters:
        - $ref: '#/parameters/pMosaicId'
      responses:
        '200':
          description: Gets a single Mosaic extended record.
          schema:
            type: object
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Get Mosaic TileJSON
      tags:
        - Basemaps and Mosaics
  /series:
    get:
      description: List all mosaic series available to the authenticated user.
      operationId: listSeries
      parameters:
        - description: Integer representing a specific page of results.
          in: query
          name: _page
          type: integer
        - description: Number of results to return per page.
          in: query
          name: _page_size
          type: integer
        - description: >-
            If provided, returns up to one result that exactly matches the
            provided value.
          in: query
          name: name__is
          type: string
        - description: >-
            If provided, returns only results that contain the fragment,
            case-insensitive.
          in: query
          name: name__contains
          type: string
        - $ref: '#/parameters/pAcquiredBetween'
        - $ref: '#/parameters/pAcquiredGt'
        - $ref: '#/parameters/pAcquiredLt'
      responses:
        '200':
          description: A list of mosaic series.
          schema:
            $ref: '#/definitions/MosaicSeriesListPage'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: List Mosaic Series
      tags:
        - Basemaps and Mosaics
  /series/{series_id}:
    get:
      description: Get a mosaic series by id.
      operationId: getSeries
      parameters:
        - $ref: '#/parameters/pSeriesId'
      responses:
        '200':
          description: Mosaic Series details.
          schema:
            $ref: '#/definitions/MosaicSeries'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: Get Mosaic Series
      tags:
        - Basemaps and Mosaics
  /series/{series_id}/mosaics:
    get:
      description: List mosaics in this series.
      operationId: getSeriesMosaics
      parameters:
        - $ref: '#/parameters/pSeriesId'
        - $ref: '#/parameters/pAcquiredBetween'
        - $ref: '#/parameters/pAcquiredGt'
        - $ref: '#/parameters/pAcquiredLt'
      responses:
        '200':
          description: List of mosaics in this series.
          schema:
            $ref: '#/definitions/MosaicSeriesMosaicsListPage'
        '401':
          $ref: '#/responses/Forbidden'
        '404':
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/General'
      summary: List Series' Mosaics
      tags:
        - Basemaps and Mosaics
produces:
  - application/json
responses:
  BadRequest:
    description: Invalid request.
    schema:
      $ref: '#/definitions/APIError'
  Forbidden:
    description: Access denied - insufficient privileges.
    schema:
      $ref: '#/definitions/Error'
  General:
    description: Other error.
    schema:
      $ref: '#/definitions/Error'
  NotFound:
    description: Item not found.
    schema:
      $ref: '#/definitions/Error'
schemes:
  - https
swagger: '2.0'