pyspaceapis 0.4.0

A Python API Wrapper for retrieving astronomical data from multiple APIs! (e.g. NASA & SpaceX APIs)

| PySpaceAPI Wrapper! 🚀

PySpaceAPI is a fairly thin (for now at least) API wrapper, which aims to provide some more ease when it comes to retrieving astronomical data from available public APIs! The goal is to add support for all, if not as many endpoints as possible that fall within the scope of astronomical data. And possibly in the future add more functionality to the wrapper to achieve more than simply retrieving data and returning it as a python dict, as well as adding support for multiple other non-NASA APIs!

Currently, this wrapper contains nineteen endpoints (out of the many planned) from NASA, but there will be more in the future!

| Currently Supported Endpoints:

[!NOTE]

Most explanations and in-depth documentation seen here are provided by the official NASA APIs page.

Astronomy Picture of the Day (APOD)

"The full documentation for this API can be found in the APOD API GitHub repository"

• apod
  • "This endpoint structures the APOD imagery and associated metadata so that it can be repurposed for other applications."

Near Earth Object Web Service (Asteroids NeoWs)

"NeoWs (Near Earth Object Web Service) is a RESTful web service for near earth Asteroid information. With NeoWs a user can: search for Asteroids based on their closest approach date to Earth, lookup a specific Asteroid with its NASA JPL small body id, as well as browse the overall data-set."

• Neo - Feed

  • "Retrieve a list of Asteroids based on their closest approach date to Earth."

• Neo - Lookup

  • "Look up a specific Asteroid based on its NASA JPL small body (SPK-ID) ID"

• Neo - Browse

  • "Browse the overall Asteroid data-set"

Space Weather Database Of Notifications, Knowledge, Information (DONKI)

"The Space Weather Database Of Notifications, Knowledge, Information (DONKI) is a comprehensive on-line tool for space weather forecasters, scientists, and the general space science community. DONKI chronicles the daily interpretations of space weather observations, analysis, models, forecasts, and notifications provided by the Space Weather Research Center (SWRC), comprehensive knowledge-base search functionality to support anomaly resolution and space science research, intelligent linkages, relationships, cause-and-effects between space weather activities and comprehensive webservice API access to information stored in DONKI."

• Coronal Mass Ejection (CME)

  • Retrieves basic DONKI Coronal Mass Injection analyses (CMEs) within a specific time frame!

• Coronal Mass Ejection Analysis

  • Retrieves more robust analyses from DONKI Coronal Mass Injections (CMEs) within a specific time frame, accuracy, catalog, and/or keyword!

• Geomagnetic Storm (GST)

  • Retrieves DONKI Geomagnetic Storm analyses (GSTs) within a specific time frame!

• Interplanetary Shock (IPS)

  • Retrieves DONKI Interplanetary Shock analyses (IPSs) within a specific time frame, location, and/or catalog!

• Solar Flare (FLR)

  • Retrieves DONKI Solar Flare analyses (FLRs) within a specific time frame!

• Solar Energetic Particle (SEP)

  • Retrieves DONKI Solar Energetic Particle analyses (SEP) within a specific time frame!

• Magnetopause Crossing (MCP)

  • Retrieves DONKI Magnetopause Crossing analyses (MPC) within a specific time frame!

• Radiation Belt Enhancement (RBE)

  • Retrieves DONKI Radiation Belt Enhancement analyses (RBE) within a specific time frame!

• Hight Speed Stream (HSS)

  • Retrieves DONKI Hight Speed Stream analyses (HSS) within a specific time frame!

• WSA+EnlilSimulation

  • Retrieves DONKI WSA+EnlilSimulation analyses within a specific time frame!

• Notifications

  • Retrieve DONKI Notifications within a specific time frame and/or a notification type!

The Earth Observatory Natural Event Tracker (EONET)

"The Earth Observatory Natural Event Tracker (EONET) is a prototype web service with the goal of:

providing a curated source of continuously updated natural event metadata; providing a service that links those natural events to thematically-related web service-enabled image sources (e.g., via WMS, WMTS, etc.)."

• Events

  • Retrieve Earth Observatory Natural Event Tracker (EONET) events with up to eleven optional parameters. Such as: Source, category, status, limit, days, time frame, magnitude IDs and values, and a bounding box!

• Events GeoJSON

  • Retrieve Earth Observatory Natural Event Tracker (EONET) GeoJSON events with up to eleven optional parameters. Such as: Source, category, status, limit, days, time frame, magnitude IDs and values, and a bounding box!

• Categories

  • "Categories are the types of events by which individual events are cataloged. Categories can be used to filter the output of the Categories API and the Layers API. The acceptable categories can be accessed via the categories JSON."

• Layers

  • "A Layer is a reference to a specific web service (e.g., WMS, WMTS) that can be used to produce imagery of a particular NASA data parameter. Layers are mapped to categories within EONET to provide a category-specific list of layers (e.g., the ‘Volcanoes’ category is mapped to layers that can provide imagery in true color, SO2, aerosols, etc.). Web services come in a variety of flavors, so it is not possible to include all of the necessary metadata here that is required to construct a properly-formulated request (URL). The full list of layers can be accessed via the layers JSON."

| Installing The Package:

This package can be installed via PIP or installed manually via the release downloads on GitHub!

Due to a conflict with an apparent non-existent package on PyPI, the installation name is slightly different than the one used for everything else.

PIP Install:

shell

pip install pyspaceapis

Manual Install:

shell

pip install "PATH\TO\pyspaceapis-0.4.0-py3-none-any.whl"

Dependencies can be viewed on Line #8 in 'pyproject.toml'.

| Using The Package:

As noted above, this wrapper is very much so in the early stages and supports just 19 NASA API endpoints at the moment. However, I am working to constantly and consistently add more!

All methods currently return a python dict. This will be changed if it is found to be a problem, or an annoyance for users. However, I have not found a reason to do so yet.

To access these, input your NASA API key or leave the parameter empty to use the NASA Demo Key.

python

from pyspaceapi import NASAClient


# This uses the Demo Key by default
client = NASAClient()

After this, you are ready to make requests to the NASA endpoints!

Example API Request:

This program will search the NASA Astronomy Picture of the Day endpoint and return a python dict containing the data of a single random APOD entry!

python

from pyspaceapi import NASAClient


# Replace 'DEMO_KEY' if you plan to use your own NASA API key!
client = NASAClient("DEMO_KEY")

# Get one random APOD entry
data = client.apod(count=1)
print(data)

The program will then return and print a dict containing the retrieved data!

The output:

console

[{'copyright': '\n\nJohannes Schedler\n(Panther Observatory)\n\n', 'date': '2005-06-07', 'explanation': 'Galaxies abound in this cosmic scene, a well chosen telescopic view toward the northern constellation of Ursa Major. Most noticeable are the striking pair of spiral galaxies - NGC 3718 (above, right) and NGC 3729 (below center) - a mere 52 million light-years distant. In particular, NGC 3718 has dramatic dust lanes sweeping through its bright central region and extensive but faint spiral arms. Seen about 150 thousand light-years apart, these two galaxies are likely interacting gravitationally, accounting for the warped and peculiar appearance of NGC 3718. While a careful study of the deep image reveals a number of fainter and more distant background galaxies, another remarkable galaxy grouping known as Hickson Group 56 can be found just to the right of NGC 3718. Hickson Group 56 contains five interacting galaxies and lies over 400 million light-years away.', 'hdurl': 'https://apod.nasa.gov/apod/image/0506/ngc3718etc_schedler_full.jpg', 'media_type': 'image', 'service_version': 'v1', 'title': 'Galaxies in View', 'url': 'https://apod.nasa.gov/apod/image/0506/ngc3718etc_schedler_c38.jpg'}]

Process finished with exit code 0

Debug Tools:

Along with the endpoint methods, I have included another separate module named: 'debugtools' which contains just one tool for now, being the 'time_this' decorator!

Usage would appear something like this:

python

from pyspaceapi.debugtools import time_this
from time import sleep


@time_this
def do_something():
    sleep(1.7)
    print("Did something!")


do_something()

The output:

console

Did something!


(Finished in: 1.7000 seconds.)

| Final Notes:

Since this package/wrapper is still very early, please expect there to possibly be some bugs or other weirdness! If anything of the like is noticed in which you'd like fixed, or you have any suggestions, please be sure to make a submission in the GitHub repository, and I will attempt to make implementations as soon as possible!

✅ Pull Requests are also welcome!