A comprehensive Python SDK for the Nyx Astronomy API providing access to celestial objects, ephemeris calculations, astronomical events, and satellite tracking.
Installation#
bash
pip install nyx-client
Or with poetry:
bash
poetry add nyx-client
Quick Start#
Synchronous Usage#
python
from nyx_client import NyxClient
# Initialize client
client = NyxClient(api_key="your-api-key")
# List celestial objects
objects = client.objects.list(type="nebula")
for obj in objects.data:
print(f"{obj.name}: {obj.magnitude}")
# Search for objects
results = client.objects.search(q="Orion")
for result in results.data:
print(f"{result.object.name} (score: {result.score})")
# Get current position of Mars
position = client.ephemeris.position(
"mars",
latitude=34.0522,
longitude=-118.2437
)
print(f"Mars altitude: {position.data.horizontal.altitude}°")
# Get upcoming astronomical events
events = client.events.upcoming(limit=10)
for event in events.data:
print(f"{event.title} - {event.start_time}")
# Get ISS passes for a location
passes = client.satellites.get_passes(
latitude=40.7128,
longitude=-74.006,
satellite_id="25544"
)
for pass_ in passes.data:
print(f"ISS pass at {pass_.max_time}, max elevation: {pass_.max_elevation}°")
# Close the client when done
client.close()
Async Usage#
python
import asyncio
from nyx_client import AsyncNyxClient
async def main():
async with AsyncNyxClient(api_key="your-api-key") as client:
# List nebulae
objects = await client.objects.list(type="nebula", limit=5)
# Get Mars position
position = await client.ephemeris.position(
"mars",
latitude=34.0522,
longitude=-118.2437
)
# Get events
events = await client.events.upcoming(limit=5)
return objects, position, events
asyncio.run(main())
Context Manager#
python
with NyxClient(api_key="your-api-key") as client:
objects = client.objects.list()
# Client automatically closed
Configuration#
Environment Variables#
bash
export NYX_API_KEY="your-api-key"
export NYX_BASE_URL="https://api.nyx.io"
export NYX_TIMEOUT="30"
export NYX_DEBUG="false"
Programmatic Configuration#
python
from nyx_client import NyxClient, NyxConfig
from nyx_client.config import TimeoutConfig, RetryConfig
config = NyxConfig(
api_key="your-api-key",
base_url="https://api.nyx.io",
timeout=TimeoutConfig(
connect=10.0,
read=60.0,
write=30.0
),
retry=RetryConfig(
max_retries=3,
initial_delay=1.0,
max_delay=30.0
),
debug=True
)
client = NyxClient(config=config)
API Reference#
Objects API#
python
# List objects with filtering
objects = client.objects.list(
type="nebula",
catalog="messier",
constellation="Orion",
min_magnitude=0,
max_magnitude=10,
page=1,
limit=20
)
# Search objects
results = client.objects.search(q="Andromeda", limit=10)
# Get a specific object
obj = client.objects.get("messier-31")
Ephemeris API#
python
# Get ephemeris data over time
ephemeris = client.ephemeris.get(
object_id="mars",
latitude=34.0522,
longitude=-118.2437,
start_time="2024-01-01T00:00:00Z",
end_time="2024-01-02T00:00:00Z",
step="1h"
)
# Get current position
position = client.ephemeris.position(
"moon",
latitude=51.5074,
longitude=-0.1278
)
# Get rise/set times
times = client.ephemeris.rise_set(
"sun",
latitude=40.7128,
longitude=-74.006,
date="2024-06-21"
)
Events API#
python
# List events
events = client.events.list(
start_date="2024-01-01",
end_date="2024-12-31",
type="lunar_eclipse",
importance="major"
)
# Get upcoming events
upcoming = client.events.upcoming(limit=10)
# Get event types
types = client.events.types()
# Get specific event
event = client.events.get("event-123")
Satellites API#
python
# List satellites
satellites = client.satellites.list(
category="space_station",
status="active"
)
# Get satellite categories
categories = client.satellites.categories()
# Get passes for location
passes = client.satellites.get_passes(
latitude=40.7128,
longitude=-74.006,
days=7,
min_elevation=20,
visible_only=True
)
# Get specific satellite
satellite = client.satellites.get("25544") # ISS
# Get passes for specific satellite
iss_passes = client.satellites.get_passes_by_id(
"25544",
latitude=40.7128,
longitude=-74.006,
days=7
)
Error Handling#
python
from nyx_client import NyxClient
from nyx_client.exceptions import (
NyxApiError,
NyxAuthenticationError,
NyxRateLimitError,
NyxNotFoundError,
NyxTimeoutError,
NyxConnectionError,
)
client = NyxClient(api_key="your-api-key")
try:
obj = client.objects.get("nonexistent-object")
except NyxNotFoundError as e:
print(f"Object not found: {e.message}")
except NyxRateLimitError as e:
print(f"Rate limited. Retry after: {e.retry_after}s")
except NyxAuthenticationError as e:
print(f"Authentication failed: {e.message}")
except NyxTimeoutError as e:
print(f"Request timed out after {e.timeout}s")
except NyxConnectionError as e:
print(f"Connection failed: {e.message}")
except NyxApiError as e:
print(f"API error {e.status_code}: {e.message}")
Type Hints#
The client provides full type hints for all API responses:
python
from nyx_client import NyxClient
from nyx_client.types import CelestialObject, ObjectType
client = NyxClient(api_key="your-api-key")
# Type hints work with IDE autocompletion
objects = client.objects.list(type=ObjectType.NEBULA)
for obj in objects.data:
# IDE knows obj is CelestialObject
print(obj.name, obj.coordinates.ra, obj.coordinates.dec)
License#
MIT License - see LICENSE file for details.