openapi: 3.0.0
info:
  title: Reports API
  description: Access & Create Usage Reports
  version: 1.0.0
servers:
  - url: https://api.planet.com/reports/v1/
    description: API Server
components:
  schemas:
    Report:
      type: object
      properties:
        report_id:
          type: string
        contents:
          description: Link to one or more report files.
          type: array
          items:
            type: string
            format: url
        org_id:
          type: integer
        plan_id:
          type: integer
        data_date_start:
          type: string
          format: date
        data_date_end:
          type: string
          format: date
        report_type:
          $ref: '#/components/schemas/ReportType'
        num_rows:
          type: integer
        cadence:
          $ref: '#/components/schemas/Cadence'
        has_footprint:
          description: If true, report files contain geometry footprints.
          type: boolean
        _links:
          $ref: '#/components/schemas/ReportLinks'

    PVReport:
      type: object
      properties:
        report_id:
          type: string
        contents:
          description: Link to one or more PV report files.
          type: array
          items:
            type: string
            format: url
        org_id:
          type: integer
        plan_id:
          type: integer
        line_item_id:
          type: integer
        data_date_start:
          type: string
          format: date
        data_date_end:
          type: string
          format: date
        report_type:
          $ref: '#/components/schemas/ReportType'
        num_rows:
          type: integer
        cadence:
          $ref: '#/components/schemas/Cadence'
        has_footprint:
          description: If true, PV report files contain geometry footprints.
          type: boolean
        _links:
          $ref: '#/components/schemas/ReportLinks'

    SubOrgReport:
        allOf:
          - $ref: '#/components/schemas/SubOrgReportRequest'
          - type: object
            properties:
              report_id:
                type: string
                format: uuid
              status:
                type: string
                enum: 
                  - in_progress
                  - failed
                  - completed
              parent:
                description: parent organisation id
                type: integer
              requesting_user_id:
                type: integer
              contents:
                description: Link to one or more report files.
                type: array
                items:
                  type: string
                  format: url
              
    SubOrgReportRequest:
      type: object
      properties:
        report_type:
          $ref: '#/components/schemas/ReportType'
        cadence:
          $ref: '#/components/schemas/Cadence'
        toi:
          $ref: '#/components/schemas/TOI'
        suborgs:
          type: object
          properties:
            include:
              type: string
              enum: 
                - all
                - none
                - selected
            ids:
              type: array
              items: 
                type: integer
            
    Cadence:
      type: string
      enum:
        - daily
        - monthly
    
    Type:
      type: string
      enum:
        - scenes
        - basemaps

    Plan:
      type: string
      enum:
        - asset_premium_sqkm_v1_0
        - asset_preferred_sqkm_v1_0
        - asset_starter_sqkm_v1_0
        - asset_area_under_management_sqkm_v1_0
        - asset_charge_first_download_starter_sqkm_v1_0
        - asset_charge_first_download_preferred_sqkm_v1_0
        - asset_charge_first_download_premium_sqkm_v1_0

    ReportType:
      type: string
      enum:
        - detailed
        - summary
    
    PvReportType:
      type: string
      enum:
        - pv_detailed
        - billableaoi_detailed

    ReportLinks:
      type: object
      properties:
        self:
          type: string

    ListPage:
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
        _links:
          type: object
          properties:
            next:
              type: string
              format: url

    FootprintsReportRequest:
      type: object
      properties:
        aoi:
          $ref: '#/components/schemas/Geometry'
        toi:
          $ref: '#/components/schemas/TOI'
        org_id:
          type: integer
        plan_id:
          type: integer

    TOI:
      type: object
      description: Time of interest, the time window cannot be greater than 90 days, start date and end date included
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date

    FootprintsReportResponse:
      allOf:
        - $ref: '#/components/schemas/FootprintsReportRequest'
        - type: object
          properties:
            status_link:
              type: string
              format: url
            location:
              type: string
              format: url

    FootprintsReport:
      type: object
      properties:
        id:
          type: string
        report_date:
          type: string
          format: date
        report_type:
          $ref: '#/components/schemas/ReportType'
        usage_bucket:
          type: string
        org:
          type: integer
        package:
          type: integer
        plan:
          type: integer
        content_link:
          type: string
    
    FootprintsReportsListResponse:
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/FootprintsReport'

    Geometry:
      type: object
      description: Area of interest - GeoJSon geometry
      externalDocs:
        url: http://geojson.org/geojson-spec.html#geometry-objects
      oneOf:
        - $ref: '#/components/schemas/Polygon'
        - $ref: '#/components/schemas/MultiPolygon'

    Polygon:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: http://geojson.org/geojson-spec.html#id4
      properties:
        type:
          type: string
          enum:
            - Polygon
        coordinates:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/Point2D'
      additionalProperties: false

    MultiPolygon:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: http://geojson.org/geojson-spec.html#id6
      properties:
        type:
          type: string
          enum:
            - MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/Point2D'
      additionalProperties: false

    Point2D:
      type: array
      maxItems: 2
      minItems: 2
      items:
        type: number

    Error:
      type: object
      properties:
        message:
          description: A descriptive error message.
          type: string
      additionalProperties: false

    Errors:
      description: A list of Errors
      type: array
      items:
        $ref: '#/components/schemas/Error'

    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).
      type: object
      properties:
        field:
          additionalProperties:
            $ref: '#/components/schemas/Errors'
          type: object
        general:
          $ref: '#/components/schemas/Errors'
      additionalProperties: false
      required:
        - general
        - field
    
    Offset:
      type: integer
      minimum: 0

paths:
  /:
    get:
      tags:
        - Download Reports
      description: List reports, using and filtering logic based on parameters
      operationId: listReports
      summary: List Download Reports
      parameters:
        - name: org_id
          in: query
          description: ID of org to query, defaults to token claims
          schema:
            type: integer
        - name: plan_id
          in: query
          description: Include reports generated for the given Plan ID
          schema:
            type: integer
        - name: report_type
          in: query
          description: Report type
          schema:
            $ref: '#/components/schemas/ReportType'
        - name: cadence
          in: query
          description: Report cadence
          schema:
            type: string
            enum:
              - daily
              - monthly
        - name: start
          in: query
          description: Include reports on or after this date
          schema:
            type: string
            format: date
        - name: end
          in: query
          description: Include reports on or before this date
          schema:
            type: string
            format: date
        - name: page_size
          in: query
          description: Number of records to return per page, defaults to 50.
          schema:
            type: integer
        - name: after
          in: query
          description: Paging navigation - specifies ID of report to start listing from.
          schema:
            type: string
        - name: offset
          in: query
          description: Number of results to skip in a query
          schema:
            $ref: '#/components/schemas/Offset'
      responses:
        200:
          description: List of Reports matching filter criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPage'

  /{id}:
    get:
      tags:
        - Download Reports
      description: Get a report by ID
      operationId: getReport
      summary: Get a Download Report
      parameters:
        - name: id
          in: path
          description: ID of report to get
          required: true
          schema:
            type: string
      responses:
        200:
          $ref: '#/components/schemas/Report'
  
  /{id}/content/{part}:
    get:
      tags:
        - Download Reports
      description: Download a report
      operationId: getReportContent
      summary: Get a Download Report's content
      parameters:
        - name: id
          description: ID of report to get
          in: path
          required: true
          schema:
            type: string
        - name: part
          description: Part of report to get
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Report contents
          content:
            text/csv:
              schema:
                type: string

  /pv/:
    get:
      tags:
        - PV Reports
      description: List PV reports, using filtering logic based on parameters
      operationId: listPVReports
      summary: List PV Reports
      parameters:
        - name: org_id
          in: query
          description: ID of org to query, defaults to token claims
          schema:
            type: integer
        - name: plan_id
          in: query
          description: Include PV reports generated for the given Contract ID
          schema:
            type: integer
        - name: line_item_id
          in: query
          description: Include PV reports generated for the given Line Item ID
          schema:
            type: integer
        - name: report_type
          in: query
          description: PV report type
          schema:
            $ref: '#/components/schemas/PvReportType'
        - name: cadence
          in: query
          description: PV report cadence _Please note that no monthly reports are created for the pv_detailed report_type. A list of monthly pv_detailed reports will always be empty_
          schema:
            $ref: '#/components/schemas/Cadence'
        - name: start
          in: query
          description: Include PV reports on or after this date
          schema:
            type: string
            format: date
        - name: end
          in: query
          description: Include PV reports on or before this date
          schema:
            type: string
            format: date
        - name: page_size
          in: query
          description: Number of records to return per page, defaults to 50 for PV reports.
          schema:
            type: integer
        - name: after
          in: query
          description: Paging navigation - specifies ID of PV report to start listing from.
          schema:
            type: string
        - name: offset
          in: query
          description: Number of results to skip in a query
          schema:
            $ref: '#/components/schemas/Offset'
      responses:
        200:
          description: List of PV Reports matching filter criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPage'

  /pv/{reportId}:
    get:
      tags:
        - PV Reports
      description: Get a PV report by ID
      operationId: getPVReport
      summary: Get a PV Report
      parameters:
        - name: reportId
          in: path
          description: ID of the PV report to get
          required: true
          schema:
            type: string
      responses:
        200:
          $ref: '#/components/schemas/PVReport'

  /downloads/suborgs:
    post:
      tags:
        - Downloads Reports (Sub Orgs)
      description: Request to generate a download usage report of "all" or "selected" Suborganizations of the Organization the requesting user belongs to.
      operationId: createSuborgReport
      summary: Create a SubOrg Download Report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubOrgReportRequest'
      responses:
        201:
          $ref: '#/components/schemas/SubOrgReport'
        
  /downloads/suborgs/{id}:
    get:
      tags:
        - Downloads Reports (Sub Orgs)
      description: Get a sub org report by ID
      operationId: getSubOrgReport
      summary: SubOrg Download Report
      parameters:
        - name: id
          in: path
          description: ID of sub org report
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          $ref: '#/components/schemas/SubOrgReport'

  /downloads/suborgs/{id}/content/{part}:
    get:
      tags:
        - Downloads Reports (Sub Orgs)
      description: Download a report
      operationId: getSubOrgDownloadReportContent
      summary: SubOrg Download Report's Content
      parameters:
        - name: id
          description: ID of suborg report to get
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: part
          description: Part of report to get
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: SubOrg Report contents as csv
          content:
            text/csv:
              schema:
                type: string

  /plans/{planID}/tiles/usage:
    get:
      tags:
        - Tiles Streaming Reports
      description: Download tiles usage report
      operationId: getTilesUsageReport
      summary: Get Tiles Usage Report
      parameters:
        - name: planID
          in: path
          description: ID of plan to request the report (you can find this ID in the Accounts Page)
          required: true
          schema:
            type: integer
        - name: start
          in: query
          description: The report will include results after this date (YYYY-MM-DD)
          required: true
          schema:
            type: string
            format: date
        - name: end
          in: query
          description: The report will include results before this date (YYYY-MM-DD)
          required: true
          schema:
            type: string
            format: date
        - name: include_user
          in: query
          description: If true, the report will contains the user
          required: true
          schema:
            type: boolean
        - name: interval
          in: query
          description: Report cadence, can be daily or monthly
          required: true
          schema:
            $ref: '#/components/schemas/Cadence'
        - name: type
          in: query
          description: Optional filter by tile type, can be scenes or basemaps
          required: false
          schema:
            $ref: '#/components/schemas/Type'
        - name: include_subject
          in: query
          description: If true, the report will include the subject for every streaming event
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: Subscriptions report
          content:
            text/csv:
              schema:
                type: string
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /tasking/{contractId}/usage:
    get:
      tags:
        - Tasking Reports
      description: Download a usage report for a tasking contract
      operationId: getTaskingUsageReport
      summary: Get Tasking Usage Report
      parameters:
        - name: contractId
          description: tasking contract ID (pl-number)
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
          description: Max. number of rows to return
        - name: exclude
          in: query
          schema:
            type: string
          description: Column headers to be excluded from the CSV report. Include the query param for each column
      responses:
        200:
          description: Tasking contract usage report contents as csv
          content:
            text/csv:
              schema:
                type: string

  /footprints/{planId}:
    get:
      tags:
        - Footprints Reports
      description: Returns the download footprints geometry reports generated for the given Plan ID
      operationId: getFootprintsReports
      summary: Get Footprints Usage Reports
      parameters:
        - name: planId
          in: path
          description: ID of the plan
          required: true
          schema:
            type: integer
      responses:
        200:
          description: List of footprints reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FootprintsReportsListResponse'
                
  /footprints/{planId}/{reportId}:
    get:
      tags:
        - Footprints Reports
      description: Returns the download footprints report generated for the given Plan ID and Report Id
      operationId: getFootprintsReport
      summary: Get a single Footprints Usage Report
      parameters:
        - name: planId
          in: path
          description: ID of the plan
          required: true
          schema:
            type: integer
        - name: reportId
          in: path
          description: ID of the requested report
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Footprint geometry generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Geometry'