openapi: 3.0.3
info:
  title: NASA NeoWs - Near Earth Object Web Service Browse API
  description: 'NASA Near Earth Object Web Service (NeoWs) REST API for searching and browsing near Earth asteroid information. Users can search for asteroids based on their closest approach date to Earth, look up a specific asteroid by NASA JPL small body (SPK-ID), and browse the overall dataset. Data originates from the NASA JPL Asteroid team (http://neo.jpl.nasa.gov/). Maintained by the SpaceRocks Team: David Greenfield, Arezu Sarvestani, Jason English, and Peter Baunach.

    '
  version: 1.0.0
  contact:
    name: NASA API Support
    url: https://api.nasa.gov/
  license:
    name: U.S. Government Public Domain
    url: https://www.usa.gov/developer-apis
servers:
- url: https://api.nasa.gov/neo/rest/v1
  description: NASA NeoWs production server
security:
- ApiKeyQuery: []
tags:
- name: Browse
paths:
  /neo/browse:
    get:
      operationId: browseAsteroids
      summary: Browse the overall near Earth object dataset
      description: 'Returns a paginated list of all near Earth objects in the NASA dataset. Use the page and size parameters to navigate through results.

        '
      tags:
      - Browse
      parameters:
      - name: page
        in: query
        required: false
        description: Zero-indexed page number.
        schema:
          type: integer
          default: 0
          example: 0
      - name: size
        in: query
        required: false
        description: Number of asteroids returned per page.
        schema:
          type: integer
          default: 20
          example: 20
      - name: api_key
        in: query
        required: false
        description: NASA API key. Defaults to DEMO_KEY if omitted.
        schema:
          type: string
          default: DEMO_KEY
      responses:
        '200':
          description: Successful response with paginated asteroid dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsteroidBrowseResponse'
        '403':
          description: Rate limit exceeded or invalid API key.
components:
  schemas:
    PageMetadata:
      type: object
      properties:
        size:
          type: integer
        total_elements:
          type: integer
        total_pages:
          type: integer
        number:
          type: integer
    AsteroidBrowseResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            next:
              type: string
              format: uri
            previous:
              type: string
              format: uri
            self:
              type: string
              format: uri
        page:
          $ref: '#/components/schemas/PageMetadata'
        near_earth_objects:
          type: array
          items:
            $ref: '#/components/schemas/NearEarthObject'
    OrbitalData:
      type: object
      description: Orbital mechanics parameters from JPL.
      properties:
        orbit_id:
          type: string
        orbit_determination_date:
          type: string
        first_observation_date:
          type: string
          format: date
        last_observation_date:
          type: string
          format: date
        data_arc_in_days:
          type: integer
        observations_used:
          type: integer
        orbit_uncertainty:
          type: string
        minimum_orbit_intersection:
          type: string
        jupiter_tisserand_invariant:
          type: string
        epoch_osculation:
          type: string
        eccentricity:
          type: string
        semi_major_axis:
          type: string
        inclination:
          type: string
        ascending_node_longitude:
          type: string
        orbital_period:
          type: string
        perihelion_distance:
          type: string
        perihelion_argument:
          type: string
        aphelion_distance:
          type: string
        perihelion_time:
          type: string
        mean_anomaly:
          type: string
        mean_motion:
          type: string
        equinox:
          type: string
        orbit_class:
          type: object
          properties:
            orbit_class_type:
              type: string
            orbit_class_description:
              type: string
            orbit_class_range:
              type: string
    NearEarthObject:
      type: object
      properties:
        id:
          type: string
          description: Internal identifier.
        neo_reference_id:
          type: string
          description: NASA JPL small body reference ID.
        name:
          type: string
          description: Common name of the asteroid.
        name_limited:
          type: string
          description: Short version of the asteroid name.
        designation:
          type: string
          description: Minor planet designation.
        nasa_jpl_url:
          type: string
          format: uri
          description: URL to the JPL Small-Body Database entry.
        absolute_magnitude_h:
          type: number
          description: Absolute magnitude (H) — a measure of intrinsic brightness.
        estimated_diameter:
          $ref: '#/components/schemas/EstimatedDiameter'
        is_potentially_hazardous_asteroid:
          type: boolean
          description: Whether this NEO is classified as potentially hazardous.
        is_sentry_object:
          type: boolean
          description: Whether this object is tracked by the Sentry impact monitoring system.
        close_approach_data:
          type: array
          items:
            $ref: '#/components/schemas/CloseApproach'
        orbital_data:
          $ref: '#/components/schemas/OrbitalData'
    CloseApproach:
      type: object
      properties:
        close_approach_date:
          type: string
          format: date
          description: Date of closest approach (YYYY-MM-DD).
        close_approach_date_full:
          type: string
          description: Full date and time of closest approach.
        epoch_date_close_approach:
          type: integer
          description: Unix epoch timestamp of closest approach.
        orbiting_body:
          type: string
          description: The body being orbited (e.g., Earth, Venus, Mars).
        relative_velocity:
          type: object
          properties:
            kilometers_per_second:
              type: string
            kilometers_per_hour:
              type: string
            miles_per_hour:
              type: string
        miss_distance:
          type: object
          properties:
            astronomical:
              type: string
            lunar:
              type: string
            kilometers:
              type: string
            miles:
              type: string
    DiameterRange:
      type: object
      properties:
        estimated_diameter_min:
          type: number
        estimated_diameter_max:
          type: number
    EstimatedDiameter:
      type: object
      properties:
        kilometers:
          $ref: '#/components/schemas/DiameterRange'
        meters:
          $ref: '#/components/schemas/DiameterRange'
        miles:
          $ref: '#/components/schemas/DiameterRange'
        feet:
          $ref: '#/components/schemas/DiameterRange'
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key