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_area_under_management_sqkm_v1_0
        - asset_area_under_management_sqkm_v2_0
        - asset_preferred_sqkm_v1_0
        - asset_premium_sqkm_v1_0
        - asset_starter_sqkm_v1_0
        - on_demand_large_areas_v1
        - tasking_credits_v1_0
    QuotaStyle:
      type: string
      description: Plan definition ID used to filter download reports by quota style
      enum:
        - asset_area_under_management_sqkm_v1_0
        - asset_area_under_management_sqkm_v2_0
        - asset_preferred_sqkm_v1_0
        - asset_premium_sqkm_v1_0
        - asset_starter_sqkm_v1_0
        - on_demand_large_areas_v1
        - tasking_credits_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: quota_style
          in: query
          description: Filter reports by plan definition ID (quota style)
          schema:
            $ref: '#/components/schemas/QuotaStyle'
        - name: bucket_prn
          in: query
          description: Filter reports by usage bucket PRN
          schema:
            type: string
            example: prn:usage-api:bucket:7a02db3e-1d68-47bf-8219-97cfb6e0b3c8
        - 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'