openapi: 3.0.2
info:
  title: Earth-Info-REST-API
  description: REST API services for public EarthInfo data.
  version: 1.5.0
  contact:
    name: IPF - Cloud City
    email: ipf-cloudcity@nga.mil
servers:
  - url: https://earth-info.nga.mil
    description: REST API services for public EarthInfo data.
paths:
  /apis/:
    get:
      summary: Returns OpenAPI specification for available EarthInfo REST APIs.
      responses:
        200:
          description: Success
          content:
            text/yaml:
              schema:
                type: string
  /apis/eopp:
    get:
      summary: Returns listing of EOPP (Earth Orientation Parameter Predictions) files available for the given year and format provided.
      parameters:
        - name: year
          in: query
          description: Year to query. Acceptable range for available data is 2009 until present.
          required: true
          schema:
            type: string
        - name: format
          in: query
          description: EOPP data format.
          required: true
          schema:
            type: string
            enum:
              - eopp
              - usaf
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  type: string
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/Unexpected'
  /apis/eopp-file:
    get:
      summary: Returns EOPP (Earth Orientation Parameter Predictions) file for the given year, format, and file name provided.
      parameters:
        - name: year
          in: query
          description: Year to query. Acceptable range for available data is 2009 until present.
          required: true
          schema:
            type: string
        - name: format
          in: query
          description: EOPP data format.
          required: true
          schema:
            type: string
            enum:
              - eopp
              - usaf
        - name: filename
          in: query
          description: Name of EOPP file to retrieve.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                type: string
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/Unexpected'
  /apis/eopp-meta:
    get:
      summary: Returns listing of EOPP (Earth Orientation Parameter Predictions) file names and date last modified, available for the given year and format provided.
      parameters:
        - name: year
          in: query
          description: Year to query. Acceptable range for available data is 2009 until present.
          required: true
          schema:
            type: string
        - name: format
          in: query
          description: EOPP data format.
          required: true
          schema:
            type: string
            enum:
              - eopp
              - usaf
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/EoppMetaData'
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/Unexpected'
  /php/gnss_s3.php:
    post:
      summary: Download ephemeris or EOPP data type selected for chosen timeframe.
      description: >
        Below are API requests using the ***curl*** command for each of the downloadable data sets.  In the syntax provided, values enclosed in ***\<example>*** will need to be replaced by user-desired values.  For example, ***\<MM-DD-YYYY>*** may be replaced with ***06-15-2022***.  When no data matches the request values, the following message will be returned: ***curl: (22) The requested URL returned error: 404***.


        ### GPS Ephemeris Center of Mass:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d 'datatype=GPS+Ephemeris+Center+of+Mass&start=<MM-DD-YYYY>&end=<MM-DD-YYYY>' -f -o center_of_mass.zip`

        ### GPS Ephemeris Antenna Phase Center (APC):

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d 'datatype=GPS+Ephemeris+Antenna+Phase+Center+%28APC%29&start=<MM-DD-YYYY>&end=<MM-DD-YYYY>' -f -o apc.zip`

        ### Earth Orientation Parameter Predictions/5-Line Format:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d 'datatype=Earth+Orientation+Parameter+Predictions%2F5-Line+Format&start=<MM-DD-YYYY>&end=<MM-DD-YYYY>' -f -o eopp_5_line.zip`

        ### Earth Orientation Parameter Predictions/USAF Format:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d 'datatype=Earth+Orientation+Parameter+Predictions%2FUSAF+Format&start=<MM-DD-YYYY>&end=<MM-DD-YYYY>' -f -o eopp_usaf.zip`

        ### Navdata:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d 'datatype=Navdata&start=<MM-DD-YYYY>&end=<MM-DD-YYYY>' -f -o navdata.zip`

        ### Clock State File:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d 'datatype=Clock+State+File&start=<MM-DD-YYYY>&end=<MM-DD-YYYY>' -f -o clock_file.zip`

        ### 9-Day Orbit Predictions - Center of Mass:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d '9dayOrbitPrediction=9dayOrbitPrediction' -f -o 9dayOrbitPrediction.zip`

        ### 30-Day Orbit Predictions - Center of Mass:

          `curl -X 'POST' 'https://earth-info.nga.mil/php/gnss_s3.php' -H 'accept: application/octet-stream' -H 'Content-Type: application/x-www-form-urlencoded' -d '30dayOrbitPrediction=30dayOrbitPrediction' -f -o 30dayOrbitPrediction.zip`
      requestBody:
        description: Payload of download request.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/FormsWithDateRange'
                - $ref: '#/components/schemas/9DayOrbitPrediction'
                - $ref: '#/components/schemas/30DayOrbitPrediction'
      responses:
        200:
          description: Data is successfully downloaded.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/Unexpected'
components:
  responses:
    BadRequest:
      description: The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modification.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The server has not found anything matching the Request-URI.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/Error'
    Unexpected:
      description: An unexpected error occured.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    EoppMetaData:
      description: EOPP meta data array
      type: array
      items:
        type: object
        properties:
          fileName:
            type: string
            example: 'EOPP1001.TXT'
          lastModified:
            type: string
            format: date-time
            example: '2021-11-05T14:50:46+00:00'
    FormsWithDateRange:
      description: Data type and date range to download
      type: object
      properties:
        datatype:
          description: Type of ephemeris or eopp data to download.
          type: string
          enum:
            - GPS Ephemeris Center of Mass
            - GPS Ephemeris Antenna Phase Center (APC)
            - Earth Orientation Parameter Predictions/USAF Format
            - Earth Orientation Parameter Predictions/5-Line Format
            - Navdata
            - Clock State File
        start:
          description: Start date of data to download.
          type: string
          format: date
          example: '2022-01-01'
        end:
          description: End date of data to download.
          type: string
          format: date
          example: '2022-01-01'
      required:
        - datatype
        - start
        - end
    9DayOrbitPrediction:
      description: 9 day orbit prediction download
      type: object
      properties:
        9dayOrbitPrediction:
          type: string
          enum:
            - 9dayOrbitPrediction
      required:
        - 9dayOrbitPrediction
    30DayOrbitPrediction:
      description: 30 day orbit prediction download
      type: object
      properties:
        30dayOrbitPrediction:
          type: string
          enum:
            - 30dayOrbitPrediction
      required:
        - 30dayOrbitPrediction
    Error:
      description: Error object
      type: object
      properties:
        statusCode:
          description: HTTP Status Code
          type: string
        message:
          description: Error Message
          type: string
      required:
        - statusCode
        - message
