| Name | pyspaceapis JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | A Python API Wrapper for retrieving astronomical data from multiple APIs and endpoints! |
| upload_time | 2025-10-21 00:30:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
space
api
multi-api
wrapper
data
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 📡 | 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:
> ### 💡
>
> *Most explanations and in-depth documentation
> seen here are provided by
> the [**official NASA APIs page**](https://api.nasa.gov)*.
### [**Astronomy Picture of the Day**](https://apod.nasa.gov/apod/astropix.html) (APOD)
"The full documentation for this
API can be found in
the [**APOD API GitHub
repository**](https://github.com/nasa/apod-api)"
- [**apod**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L32)
- "This endpoint structures the APOD
imagery and associated metadata so
that it can be repurposed
for other applications."
### [**Near Earth Object Web Service**](https://cneos.jpl.nasa.gov) (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**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L93)
- "Retrieve a list of Asteroids based on their closest approach date to Earth."
- [**Neo - Lookup**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L128)
- "Look up a specific Asteroid based on its [**NASA JPL small body (SPK-ID) ID**](http://ssd.jpl.nasa.gov/sbdb_query.cgi)"
- [**Neo - Browse**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L151)
- "Browse the overall Asteroid data-set"
### [**Space Weather Database Of Notifications, Knowledge, Information**](https://ccmc.gsfc.nasa.gov/tools/DONKI) (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**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L172) (CME)
- Retrieves basic DONKI Coronal Mass Injection analyses (CMEs)
within a specific time frame!
- [**Coronal Mass Ejection Analysis**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L208)
- Retrieves more robust analyses from DONKI Coronal Mass Injections (CMEs)
within a specific time frame, accuracy, catalog, and/or keyword!
- [**Geomagnetic Storm**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L284) (GST)
- Retrieves DONKI Geomagnetic Storm analyses (GSTs)
within a specific time frame!
- [**Interplanetary Shock**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L320) (IPS)
- Retrieves DONKI Interplanetary Shock analyses (IPSs)
within a specific time frame, location, and/or catalog!
- [**Solar Flare**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L370) (FLR)
- Retrieves DONKI Solar Flare analyses (FLRs)
within a specific time frame!
- [**Solar Energetic Particle**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L406) (SEP)
- Retrieves DONKI Solar Energetic Particle analyses (SEP)
within a specific time frame!
- [**Magnetopause Crossing**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L442) (MCP)
- Retrieves DONKI Magnetopause Crossing analyses (MPC)
within a specific time frame!
- [**Radiation Belt Enhancement**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L478) (RBE)
- Retrieves DONKI Radiation Belt Enhancement analyses (RBE)
within a specific time frame!
- [**Hight Speed Stream**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L514) (HSS)
- Retrieves DONKI Hight Speed Stream analyses (HSS)
within a specific time frame!
- [**WSA+EnlilSimulation**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L550)
- Retrieves DONKI WSA+EnlilSimulation analyses
within a specific time frame!
- [**Notifications**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L586)
- Retrieve DONKI Notifications within a specific time frame
and/or a notification type!
### [**The Earth Observatory Natural Event Tracker**](https://earthobservatory.nasa.gov) (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**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L630)
- 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**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L737)
- 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**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L844)
- "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**](https://eonet.gsfc.nasa.gov/api/v3/categories)."
- [**Layers**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L919)
- "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**](https://eonet.gsfc.nasa.gov/api/v3/layers)."
## | Installing The Package:
This package can be installed
directly from PyPI, or installed
manually via the .tar.gz or
.whl files!
As well, dependencies can be
viewed on [**Line #8 in
'pyproject.toml'**](pyproject.toml).
The PyPI project can also
be viewed by clicking this
link: https://pypi.org/project/pyspaceapis
> ### ⚠️
>
> Due to a conflict with
> an apparent non-existent package on
> PyPI, the name used for
> installation is *slightly* different than
> the one used when importing.
> Please be sure to correctly
> install `pyspaceapis`. The exact commands
> for installation can be copied
> below!
### Default Installation Method:
```
shell
pip install pyspaceapis
```
---
### Manual Installation Methods:
Using the .whl:
```
shell
pip install "PATH\TO\pyspaceapis-0.4.0-py3-none-any.whl"
```
Using the .tar.gz:
```
shell
pip install "PATH\TO\pyspaceapis-0.4.0.tar.gz"
```
*The .tar.gz and .whl files
will be made available as
well alongside each release for
those who prefer a manual
installation!*
## | 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 Near Earth Object Web
Service (NeoWs) endpoint and return
a python dict containing the
data of a single specified
asteroid ID!*
```
python
from pyspaceapi import NASAClient
# Replace 'DEMO_KEY' if you plan to use your own NASA API key!
client = NASAClient("DEMO_KEY")
# Search for a specified asteroid ID
data = client.neows_lookup(2001980)
print(data)
```
The program will then return
and print a dict containing
the retrieved data!
The output:
```
console
{'links': {'self': 'http://api.nasa.gov/neo/rest/v1/neo/2001980?api_key=DEMO_KEY'}, 'id': '2001980', 'neo_reference_id': '2001980', 'name': '1980 Tezcatlipoca (1950 LA)', 'name_limited': 'Tezcatlipoca', 'designation': '1980', 'nasa_jpl_url': 'https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html#/?sstr=2001980', 'absolute_magnitude_h': 13.81, 'estimated_diameter': {'kilometers': {'estimated_diameter_min': 4.5978518828, 'estimated_diameter_max': 10.2811093604}, 'meters': {'estimated_diameter_min': 4597.8518827937, 'estimated_diameter_max': 10281.1093604022}, 'miles': {'estimated_diameter_min': 2.8569718223, 'estimated_diameter_max': 6.3883832044}, 'feet': {'estimated_diameter_min': 15084.816371145, 'estimated_diameter_max': 33730.6748339819}}, 'is_potentially_hazardous_asteroid': False, 'close_approach_data': [], 'orbital_data': {'orbit_id': '921', 'orbit_determination_date': '2025-05-29 06:22:26', 'first_observation_date': '1950-06-19', 'last_observation_date': '2025-05-27', 'data_arc_in_days': 27371, 'observations_used': 8203, 'orbit_uncertainty': '0', 'minimum_orbit_intersection': '.245041', 'jupiter_tisserand_invariant': '3.996', 'epoch_osculation': '2461000.5', 'eccentricity': '.3647058342921514', 'semi_major_axis': '1.709394204644144', 'inclination': '26.86993780988122', 'ascending_node_longitude': '246.5426397033398', 'orbital_period': '816.3225014335094', 'perihelion_distance': '1.085968165105233', 'perihelion_argument': '115.4724980863188', 'aphelion_distance': '2.332820244183056', 'perihelion_time': '2461337.243438208260', 'mean_anomaly': '211.4954107695293', 'mean_motion': '.4410021766738259', 'equinox': 'J2000', 'orbit_class': {'orbit_class_type': 'AMO', 'orbit_class_description': 'Near-Earth asteroid orbits similar to that of 1221 Amor', 'orbit_class_range': '1.017 AU < q (perihelion) < 1.3 AU'}}, 'is_sentry_object': False}
```
---
### Timeout Handling:
If a request times out
after the initial default ten-second
timeout window, the wrapper will
retry two times by default,
once for fifteen seconds, and
then lastly, for thirty seconds.
This behavior can be overridden
in multiple ways to hopefully
fit any use case! This
can be done via the
`default_retry_delays` class parameter and further
customized via the `retry_delays` parameter
within each class method!
#### Default Retry Delays:
The `default_retry_delays` parameter will **NOT**
override the behavior of the
separate `retry_delays` parameter within each
class method if `retry_delays` is
specified. This allows for configuration
of the `default_retry_delays` AND the
`retry_delays` parameters at once without
causing conflicts.
Setting default retry delays:
```
python
from pyspaceapi import NASAClient
client = NASAClient(default_retry_delays=[5, 10, 15])
```
This, for example, will cause
the wrapper attempt to request
three times. Once for five
seconds, again for 10 seconds,
and then lastly, for fifteen
seconds. This is set to
[10, 15, 30] by default if not
specified.
#### Retry Delays (Class Method Specific):
Specifying the `retry_delays` parameter **WILL**
override the behavior of the
`default_retry_delays` class parameter, specified or
not. This means that you
can have multiple different requests
with timeout delays differing from
each other AND independent of
the default timeout delays without
causing conflict.
Example using default_retry_delays and retry_delays
simultaneously:
```
python
from pyspaceapi import NASAClient
# Specifies the default retry delays
client = NASAClient(default_retry_delays=[10, 20, 30])
# Will use 'default_retry_delays' since 'retry_delays' is unspecified
eonet_data = client.eonet_events()
# Will use 5, 10, and then 15 seconds
donki_data = client.donki_notifications(retry_delays=[5, 10, 15])
# Will use 2, 5, and then 7.5 seconds
neows_data = client.neows_browse(retry_delays=[2, 5, 7.5])
```
#### Timeout Prints:
Along with the main timeout
handling, I have also included
a `timeout_prints` class parameter, which
when set to True, will
enable the debug timeout prints.
This is set to false
by default.
Enabling the timeout prints:
```
python
from pyspaceapi import NASAClient
client = NASAClient(timeout_print=True)
```
The prints will appear as
such:
```
console
(Request timed out after 10 seconds. Retrying for 15 seconds.)
(Request timed out after 15 seconds. Retrying for 30 seconds.)
```
---
### Retrieving Headers:
There is also a method
of retrieving the HTTP header
data as a dict, containing
the current number of requests
remaining, and the total number
of requests for the API
key in-use via the `get_headers`
class method!
*This counter resets every hour
on a rolling basis!*
Retrieving header data:
```
python
from pyspaceapis import NASAClient
client = NASAClient("DEMO_KEY")
headers = client.get_headers()
print(headers)
```
This, by default with no
specified parameters, will return both
the remaining and total number
of requests as a dict!
This will appear like so:
```
console
{'rate_limit_remaining': '7', 'rate_limit_total': '10'}
```
Whether you only want the
remaining number, or the total
number can also be specified
via the `remaining_amount` and `total_amount`
parameters!
*More specifics about API key
rate limiting and amounts can
be read [**here**](https://api.nasa.gov), under the
"How Do I See My
Current Usage?" section.*
---
### Debug Tools:
Along with the endpoint methods,
I have included another separate
module named: [**`debugtools`**](https://github.com/Py-Kat/py-space-api/blob/1e1725859abd83743531d76eb4d592371f675054/pyspaceapi/debugtools.py) which contains
just one tool for now,
being the [**`time_this`**](https://github.com/Py-Kat/py-space-api/blob/1e1725859abd83743531d76eb4d592371f675054/pyspaceapi/debugtools.py#L5) 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!
Raw data
{
"_id": null,
"home_page": null,
"name": "pyspaceapis",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "space, api, multi-api, wrapper, data",
"author": null,
"author_email": "\"Kat (Py-Kat)\" <imhelvetika@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b2/c8/6292bc3b2188f6db7ad3373557aead9d625e2cb1687203ef212ddddbc0dc/pyspaceapis-0.5.0.tar.gz",
"platform": null,
"description": "# \ud83d\udce1 | PySpaceAPI Wrapper!\r\n\r\nPySpaceAPI is a fairly thin\r\n(for now at least) API\r\nwrapper, which aims to provide\r\nsome more ease when it\r\ncomes to retrieving astronomical data\r\nfrom available public APIs! The\r\ngoal is to add support\r\nfor all, if not as\r\nmany endpoints as possible that\r\nfall within the scope of\r\nastronomical data. And possibly in\r\nthe future add more functionality\r\nto the wrapper to achieve\r\nmore than simply retrieving data\r\nand returning it as a\r\npython dict, as well as\r\nadding support for multiple other\r\nnon-NASA APIs!\r\n\r\nCurrently, this wrapper contains **nineteen**\r\nendpoints (out of the many\r\nplanned) from NASA, but there\r\nwill be more in the\r\nfuture!\r\n\r\n## | Currently Supported Endpoints:\r\n\r\n> ### \ud83d\udca1\r\n> \r\n> *Most explanations and in-depth documentation\r\n> seen here are provided by \r\n> the [**official NASA APIs page**](https://api.nasa.gov)*.\r\n\r\n### [**Astronomy Picture of the Day**](https://apod.nasa.gov/apod/astropix.html) (APOD)\r\n\r\n\"The full documentation for this\r\nAPI can be found in\r\nthe [**APOD API GitHub\r\nrepository**](https://github.com/nasa/apod-api)\"\r\n\r\n - [**apod**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L32)\r\n - \"This endpoint structures the APOD\r\n imagery and associated metadata so\r\n that it can be repurposed\r\n for other applications.\"\r\n\r\n### [**Near Earth Object Web Service**](https://cneos.jpl.nasa.gov) (Asteroids NeoWs)\r\n\r\n\"NeoWs (Near Earth Object Web\r\nService) is a RESTful web\r\nservice for near earth Asteroid\r\ninformation. With NeoWs a user\r\ncan: search for Asteroids based\r\non their closest approach date\r\nto Earth, lookup a specific\r\nAsteroid with its NASA JPL\r\nsmall body id, as well\r\nas browse the overall data-set.\"\r\n\r\n - [**Neo - Feed**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L93)\r\n - \"Retrieve a list of Asteroids based on their closest approach date to Earth.\"\r\n\r\n\r\n - [**Neo - Lookup**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L128)\r\n - \"Look up a specific Asteroid based on its [**NASA JPL small body (SPK-ID) ID**](http://ssd.jpl.nasa.gov/sbdb_query.cgi)\"\r\n\r\n\r\n - [**Neo - Browse**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L151)\r\n - \"Browse the overall Asteroid data-set\"\r\n\r\n### [**Space Weather Database Of Notifications, Knowledge, Information**](https://ccmc.gsfc.nasa.gov/tools/DONKI) (DONKI)\r\n\r\n\"The Space Weather Database Of\r\nNotifications, Knowledge, Information (DONKI) is\r\na comprehensive on-line tool for\r\nspace weather forecasters, scientists, and\r\nthe general space science community.\r\nDONKI chronicles the daily interpretations\r\nof space weather observations, analysis,\r\nmodels, forecasts, and notifications provided\r\nby the Space Weather Research\r\nCenter (SWRC), comprehensive knowledge-base search\r\nfunctionality to support anomaly resolution\r\nand space science research, intelligent\r\nlinkages, relationships, cause-and-effects between space\r\nweather activities and comprehensive webservice\r\nAPI access to information stored\r\nin DONKI.\"\r\n\r\n - [**Coronal Mass Ejection**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L172) (CME)\r\n - Retrieves basic DONKI Coronal Mass Injection analyses (CMEs)\r\n within a specific time frame!\r\n\r\n\r\n - [**Coronal Mass Ejection Analysis**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L208)\r\n - Retrieves more robust analyses from DONKI Coronal Mass Injections (CMEs)\r\n within a specific time frame, accuracy, catalog, and/or keyword!\r\n \r\n\r\n - [**Geomagnetic Storm**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L284) (GST)\r\n - Retrieves DONKI Geomagnetic Storm analyses (GSTs)\r\n within a specific time frame!\r\n\r\n\r\n - [**Interplanetary Shock**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L320) (IPS)\r\n - Retrieves DONKI Interplanetary Shock analyses (IPSs)\r\n within a specific time frame, location, and/or catalog!\r\n\r\n\r\n - [**Solar Flare**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L370) (FLR)\r\n - Retrieves DONKI Solar Flare analyses (FLRs)\r\n within a specific time frame!\r\n\r\n\r\n - [**Solar Energetic Particle**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L406) (SEP)\r\n - Retrieves DONKI Solar Energetic Particle analyses (SEP)\r\n within a specific time frame!\r\n\r\n\r\n - [**Magnetopause Crossing**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L442) (MCP)\r\n - Retrieves DONKI Magnetopause Crossing analyses (MPC)\r\n within a specific time frame!\r\n\r\n\r\n - [**Radiation Belt Enhancement**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L478) (RBE)\r\n - Retrieves DONKI Radiation Belt Enhancement analyses (RBE)\r\n within a specific time frame!\r\n\r\n\r\n - [**Hight Speed Stream**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L514) (HSS)\r\n - Retrieves DONKI Hight Speed Stream analyses (HSS)\r\n within a specific time frame!\r\n\r\n\r\n - [**WSA+EnlilSimulation**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L550)\r\n - Retrieves DONKI WSA+EnlilSimulation analyses\r\n within a specific time frame!\r\n\r\n\r\n - [**Notifications**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L586)\r\n - Retrieve DONKI Notifications within a specific time frame\r\n and/or a notification type!\r\n\r\n### [**The Earth Observatory Natural Event Tracker**](https://earthobservatory.nasa.gov) (EONET)\r\n\r\n\"The Earth Observatory Natural Event\r\nTracker (EONET) is a prototype\r\nweb service with the goal\r\nof:\r\n\r\nproviding a curated source of\r\ncontinuously updated natural event metadata;\r\nproviding a service that links\r\nthose natural events to thematically-related\r\nweb service-enabled image sources (e.g., via WMS, WMTS, etc.).\"\r\n\r\n - [**Events**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L630)\r\n - Retrieve Earth Observatory Natural Event Tracker (EONET)\r\n events with up to eleven optional parameters. Such as: Source,\r\n category, status, limit, days, time frame, magnitude IDs\r\n and values, and a bounding box!\r\n\r\n\r\n - [**Events GeoJSON**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L737)\r\n - Retrieve Earth Observatory Natural Event Tracker (EONET)\r\n GeoJSON events with up to eleven optional parameters. Such as:\r\n Source, category, status, limit, days, time frame, magnitude IDs\r\n and values, and a bounding box!\r\n\r\n\r\n - [**Categories**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L844)\r\n - \"Categories are the types of events by which individual\r\n events are cataloged. Categories can be used to filter\r\n the output of the Categories API and the Layers API.\r\n The acceptable categories can be accessed via the [**categories JSON**](https://eonet.gsfc.nasa.gov/api/v3/categories).\"\r\n\r\n\r\n - [**Layers**](https://github.com/Py-Kat/py-space-api/blob/d2e1f2e4bef5e9aef19d35876546a359ee38f0d9/pyspaceapi/nasa.py#L919)\r\n - \"A Layer is a reference to a specific web service\r\n (e.g., WMS, WMTS) that can be used to produce imagery\r\n of a particular NASA data parameter. Layers are mapped\r\n to categories within EONET to provide a category-specific\r\n list of layers (e.g., the \u2018Volcanoes\u2019 category is mapped\r\n to layers that can provide imagery in true color, SO2,\r\n aerosols, etc.). Web services come in a variety of flavors,\r\n so it is not possible to include all of the necessary metadata\r\n here that is required to construct a properly-formulated request\r\n (URL). The full list of layers can be accessed via the [**layers JSON**](https://eonet.gsfc.nasa.gov/api/v3/layers).\"\r\n\r\n## | Installing The Package:\r\n\r\nThis package can be installed\r\ndirectly from PyPI, or installed\r\nmanually via the .tar.gz or\r\n.whl files!\r\n\r\nAs well, dependencies can be\r\nviewed on [**Line #8 in\r\n'pyproject.toml'**](pyproject.toml).\r\n\r\nThe PyPI project can also\r\nbe viewed by clicking this\r\nlink: https://pypi.org/project/pyspaceapis\r\n\r\n> ### \u26a0\ufe0f\r\n> \r\n> Due to a conflict with\r\n> an apparent non-existent package on\r\n> PyPI, the name used for\r\n> installation is *slightly* different than\r\n> the one used when importing.\r\n> Please be sure to correctly\r\n> install `pyspaceapis`. The exact commands\r\n> for installation can be copied\r\n> below!\r\n\r\n### Default Installation Method:\r\n\r\n```\r\nshell\r\n\r\npip install pyspaceapis\r\n```\r\n\r\n---\r\n\r\n### Manual Installation Methods:\r\n\r\nUsing the .whl:\r\n```\r\nshell\r\n\r\npip install \"PATH\\TO\\pyspaceapis-0.4.0-py3-none-any.whl\"\r\n```\r\n\r\nUsing the .tar.gz:\r\n```\r\nshell\r\n\r\npip install \"PATH\\TO\\pyspaceapis-0.4.0.tar.gz\"\r\n```\r\n\r\n*The .tar.gz and .whl files\r\nwill be made available as\r\nwell alongside each release for\r\nthose who prefer a manual\r\ninstallation!*\r\n\r\n## | Using The Package:\r\n\r\nAs noted above, this wrapper\r\nis very much so in\r\nthe early stages and supports\r\njust 19 NASA API endpoints\r\nat the moment. However, I\r\nam working to constantly and\r\nconsistently add more!\r\n\r\nAll methods currently return a\r\npython dict. This will be\r\nchanged if it is found\r\nto be a problem, or\r\nan annoyance for users. However,\r\nI have not found a\r\nreason to do so yet.\r\n\r\nTo access these, input your\r\nNASA API key or leave\r\nthe parameter empty to use\r\nthe NASA Demo Key.\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapi import NASAClient\r\n\r\n\r\n# This uses the Demo Key by default\r\nclient = NASAClient()\r\n```\r\n\r\nAfter this, you are ready\r\nto make requests to the\r\nNASA endpoints!\r\n\r\n### Example API Request:\r\n\r\n*This program will search the\r\nNASA Near Earth Object Web\r\nService (NeoWs) endpoint and return\r\na python dict containing the\r\ndata of a single specified\r\nasteroid ID!*\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapi import NASAClient\r\n\r\n\r\n# Replace 'DEMO_KEY' if you plan to use your own NASA API key!\r\nclient = NASAClient(\"DEMO_KEY\")\r\n\r\n# Search for a specified asteroid ID\r\ndata = client.neows_lookup(2001980)\r\nprint(data)\r\n```\r\n\r\nThe program will then return\r\nand print a dict containing\r\nthe retrieved data!\r\n\r\nThe output:\r\n\r\n```\r\nconsole\r\n\r\n{'links': {'self': 'http://api.nasa.gov/neo/rest/v1/neo/2001980?api_key=DEMO_KEY'}, 'id': '2001980', 'neo_reference_id': '2001980', 'name': '1980 Tezcatlipoca (1950 LA)', 'name_limited': 'Tezcatlipoca', 'designation': '1980', 'nasa_jpl_url': 'https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html#/?sstr=2001980', 'absolute_magnitude_h': 13.81, 'estimated_diameter': {'kilometers': {'estimated_diameter_min': 4.5978518828, 'estimated_diameter_max': 10.2811093604}, 'meters': {'estimated_diameter_min': 4597.8518827937, 'estimated_diameter_max': 10281.1093604022}, 'miles': {'estimated_diameter_min': 2.8569718223, 'estimated_diameter_max': 6.3883832044}, 'feet': {'estimated_diameter_min': 15084.816371145, 'estimated_diameter_max': 33730.6748339819}}, 'is_potentially_hazardous_asteroid': False, 'close_approach_data': [], 'orbital_data': {'orbit_id': '921', 'orbit_determination_date': '2025-05-29 06:22:26', 'first_observation_date': '1950-06-19', 'last_observation_date': '2025-05-27', 'data_arc_in_days': 27371, 'observations_used': 8203, 'orbit_uncertainty': '0', 'minimum_orbit_intersection': '.245041', 'jupiter_tisserand_invariant': '3.996', 'epoch_osculation': '2461000.5', 'eccentricity': '.3647058342921514', 'semi_major_axis': '1.709394204644144', 'inclination': '26.86993780988122', 'ascending_node_longitude': '246.5426397033398', 'orbital_period': '816.3225014335094', 'perihelion_distance': '1.085968165105233', 'perihelion_argument': '115.4724980863188', 'aphelion_distance': '2.332820244183056', 'perihelion_time': '2461337.243438208260', 'mean_anomaly': '211.4954107695293', 'mean_motion': '.4410021766738259', 'equinox': 'J2000', 'orbit_class': {'orbit_class_type': 'AMO', 'orbit_class_description': 'Near-Earth asteroid orbits similar to that of 1221 Amor', 'orbit_class_range': '1.017 AU < q (perihelion) < 1.3 AU'}}, 'is_sentry_object': False}\r\n\r\n```\r\n\r\n---\r\n\r\n### Timeout Handling:\r\n\r\nIf a request times out\r\nafter the initial default ten-second\r\ntimeout window, the wrapper will\r\nretry two times by default,\r\nonce for fifteen seconds, and\r\nthen lastly, for thirty seconds.\r\nThis behavior can be overridden\r\nin multiple ways to hopefully\r\nfit any use case! This\r\ncan be done via the\r\n`default_retry_delays` class parameter and further\r\ncustomized via the `retry_delays` parameter\r\nwithin each class method!\r\n\r\n#### Default Retry Delays:\r\n\r\nThe `default_retry_delays` parameter will **NOT**\r\noverride the behavior of the\r\nseparate `retry_delays` parameter within each\r\nclass method if `retry_delays` is\r\nspecified. This allows for configuration\r\nof the `default_retry_delays` AND the\r\n`retry_delays` parameters at once without\r\ncausing conflicts.\r\n\r\nSetting default retry delays:\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapi import NASAClient\r\n\r\n\r\nclient = NASAClient(default_retry_delays=[5, 10, 15])\r\n```\r\n\r\nThis, for example, will cause\r\nthe wrapper attempt to request\r\nthree times. Once for five\r\nseconds, again for 10 seconds,\r\nand then lastly, for fifteen\r\nseconds. This is set to\r\n[10, 15, 30] by default if not\r\nspecified.\r\n\r\n#### Retry Delays (Class Method Specific):\r\n\r\nSpecifying the `retry_delays` parameter **WILL**\r\noverride the behavior of the\r\n`default_retry_delays` class parameter, specified or\r\nnot. This means that you\r\ncan have multiple different requests\r\nwith timeout delays differing from\r\neach other AND independent of\r\nthe default timeout delays without\r\ncausing conflict.\r\n\r\nExample using default_retry_delays and retry_delays\r\nsimultaneously:\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapi import NASAClient\r\n\r\n\r\n# Specifies the default retry delays\r\nclient = NASAClient(default_retry_delays=[10, 20, 30])\r\n\r\n\r\n# Will use 'default_retry_delays' since 'retry_delays' is unspecified\r\neonet_data = client.eonet_events()\r\n\r\n# Will use 5, 10, and then 15 seconds\r\ndonki_data = client.donki_notifications(retry_delays=[5, 10, 15])\r\n\r\n# Will use 2, 5, and then 7.5 seconds\r\nneows_data = client.neows_browse(retry_delays=[2, 5, 7.5])\r\n```\r\n\r\n#### Timeout Prints:\r\n\r\nAlong with the main timeout\r\nhandling, I have also included\r\na `timeout_prints` class parameter, which\r\nwhen set to True, will\r\nenable the debug timeout prints.\r\nThis is set to false\r\nby default.\r\n\r\nEnabling the timeout prints:\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapi import NASAClient\r\n\r\n\r\nclient = NASAClient(timeout_print=True)\r\n```\r\n\r\nThe prints will appear as\r\nsuch:\r\n\r\n```\r\nconsole\r\n\r\n(Request timed out after 10 seconds. Retrying for 15 seconds.)\r\n\r\n(Request timed out after 15 seconds. Retrying for 30 seconds.)\r\n\r\n```\r\n\r\n---\r\n\r\n### Retrieving Headers:\r\n\r\nThere is also a method\r\nof retrieving the HTTP header\r\ndata as a dict, containing\r\nthe current number of requests\r\nremaining, and the total number\r\nof requests for the API\r\nkey in-use via the `get_headers`\r\nclass method!\r\n\r\n*This counter resets every hour\r\non a rolling basis!*\r\n\r\nRetrieving header data:\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapis import NASAClient\r\n\r\n\r\nclient = NASAClient(\"DEMO_KEY\")\r\n\r\nheaders = client.get_headers()\r\nprint(headers)\r\n```\r\n\r\nThis, by default with no\r\nspecified parameters, will return both\r\nthe remaining and total number\r\nof requests as a dict!\r\n\r\nThis will appear like so:\r\n\r\n```\r\nconsole\r\n\r\n{'rate_limit_remaining': '7', 'rate_limit_total': '10'}\r\n\r\n```\r\n\r\nWhether you only want the\r\nremaining number, or the total\r\nnumber can also be specified\r\nvia the `remaining_amount` and `total_amount`\r\nparameters!\r\n\r\n*More specifics about API key\r\nrate limiting and amounts can\r\nbe read [**here**](https://api.nasa.gov), under the\r\n\"How Do I See My\r\nCurrent Usage?\" section.*\r\n\r\n---\r\n\r\n### Debug Tools:\r\n\r\nAlong with the endpoint methods,\r\nI have included another separate\r\nmodule named: [**`debugtools`**](https://github.com/Py-Kat/py-space-api/blob/1e1725859abd83743531d76eb4d592371f675054/pyspaceapi/debugtools.py) which contains\r\njust one tool for now,\r\nbeing the [**`time_this`**](https://github.com/Py-Kat/py-space-api/blob/1e1725859abd83743531d76eb4d592371f675054/pyspaceapi/debugtools.py#L5) decorator!\r\n\r\nUsage would appear something\r\nlike this:\r\n\r\n```\r\npython\r\n\r\nfrom pyspaceapi.debugtools import time_this\r\nfrom time import sleep\r\n\r\n\r\n@time_this\r\ndef do_something():\r\n sleep(1.7)\r\n print(\"Did something!\")\r\n\r\n\r\ndo_something()\r\n```\r\n\r\nThe output:\r\n\r\n```\r\nconsole\r\n\r\nDid something!\r\n\r\n\r\n(Finished in: 1.7000 seconds.)\r\n\r\n```\r\n\r\n# | Final Notes:\r\n\r\nSince this package/wrapper is still\r\nvery early, please expect there\r\nto possibly be some bugs\r\nor other weirdness! If anything\r\nof the like is noticed\r\nin which you'd like fixed,\r\nor you have any suggestions,\r\nplease be sure to make\r\na submission in the GitHub\r\nrepository, and I will attempt\r\nto make implementations as soon\r\nas possible!\r\n\r\n\u2705 Pull Requests are also welcome!\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python API Wrapper for retrieving astronomical data from multiple APIs and endpoints!",
"version": "0.5.0",
"project_urls": {
"Repository": "https://github.com/Py-Kat/py-space-api"
},
"split_keywords": [
"space",
" api",
" multi-api",
" wrapper",
" data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "850faa00622bfe33dd0164422ce7a3b8ee98953c55b1ebdcb760eda28f77844a",
"md5": "a98557cd0df10c3bc98ee62e855395cd",
"sha256": "f4c66a80f1ea6482885609373e646dcbe7fd49b62a78a659a569d538f535787a"
},
"downloads": -1,
"filename": "pyspaceapis-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a98557cd0df10c3bc98ee62e855395cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15184,
"upload_time": "2025-10-21T00:30:09",
"upload_time_iso_8601": "2025-10-21T00:30:09.621928Z",
"url": "https://files.pythonhosted.org/packages/85/0f/aa00622bfe33dd0164422ce7a3b8ee98953c55b1ebdcb760eda28f77844a/pyspaceapis-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b2c86292bc3b2188f6db7ad3373557aead9d625e2cb1687203ef212ddddbc0dc",
"md5": "99eb2802b06c532f03ca77e8fe859631",
"sha256": "47c1f0e96c83348af21e1a9681f612842caef44ac98b59c19433816a54e68b18"
},
"downloads": -1,
"filename": "pyspaceapis-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "99eb2802b06c532f03ca77e8fe859631",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14573,
"upload_time": "2025-10-21T00:30:10",
"upload_time_iso_8601": "2025-10-21T00:30:10.470967Z",
"url": "https://files.pythonhosted.org/packages/b2/c8/6292bc3b2188f6db7ad3373557aead9d625e2cb1687203ef212ddddbc0dc/pyspaceapis-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 00:30:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Py-Kat",
"github_project": "py-space-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyspaceapis"
}
