openapi: 3.0.3
info:
  title: NASA Asteroids NeoWs API
  description: |
    Near Earth Object Web Service - RESTful web service for near earth Asteroid information. Search asteroids
    by closest approach date (feed), look up a specific asteroid by NASA JPL small body ID, and browse the
    overall NeoWs dataset.
  version: '1.0'
  contact:
    name: NASA Open APIs
    url: https://api.nasa.gov/
  license:
    name: US Government Work (Public Domain)
    url: https://www.nasa.gov/multimedia/guidelines/index.html
servers:
- url: https://api.nasa.gov
  description: NASA Open API gateway via api.data.gov
security:
- ApiKeyAuth: []
paths:
  /neo/rest/v1/feed:
    get:
      summary: Get Near Earth Object Feed
      description: Retrieve a list of asteroids based on closest approach date to Earth. Maximum date range is 7 days.
      operationId: getNeoFeed
      tags:
      - Asteroids
      parameters:
      - name: start_date
        in: query
        description: Start date of the feed (YYYY-MM-DD). Defaults to today.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date of the feed (YYYY-MM-DD). Defaults to 7 days after start_date.
        schema:
          type: string
          format: date
      - name: api_key
        in: query
        required: true
        schema:
          type: string
          default: DEMO_KEY
      responses:
        '200':
          description: Feed of near earth objects keyed by date.
          content:
            application/json:
              schema:
                type: object
  /neo/rest/v1/neo/{asteroid_id}:
    get:
      summary: Lookup a Specific Asteroid by NeoWs ID
      operationId: getNeoLookup
      tags:
      - Asteroids
      parameters:
      - name: asteroid_id
        in: path
        required: true
        description: SPK-ID (small body identifier).
        schema:
          type: string
      - name: api_key
        in: query
        required: true
        schema:
          type: string
          default: DEMO_KEY
      responses:
        '200':
          description: Detailed asteroid record including orbital and close-approach data.
          content:
            application/json:
              schema:
                type: object
  /neo/rest/v1/neo/browse:
    get:
      summary: Browse the Overall Asteroid Dataset
      operationId: browseNeo
      tags:
      - Asteroids
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 0
      - name: size
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 20
      - name: api_key
        in: query
        required: true
        schema:
          type: string
          default: DEMO_KEY
      responses:
        '200':
          description: Paged list of near earth objects.
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key