EPIC API Reference¶

This page provides a breakdown of the aionasa EPIC module.

The documentation for NASA’s EPIC API can be found here.

Client¶

class aionasa.epic.EPIC(use_nasa_mirror=False, api_key='DEMO_KEY', session=None, rate_limiter=<default_rate_limiter>)¶

Client for NASA Earth Polychromatic Imaging Camera.

Parameters

use_nasa_mirror (bool) – Whether to use the api.nasa.gov mirror instead of epic.gsfc.nasa.gov
api_key (str) – NASA API key to be used by the client.
session (Optional[aiohttp.ClientSession]) – Optional ClientSession to be used for requests made by this client. Creates a new session by default.
rate_limiter (Optional[RateLimiter]) – Optional RateLimiter class to be used by this client. Uses the library’s internal global rate limiting by default.
..note:: – The api.nasa.gov mirror is rate limited (like other api.nasa.gov APIs). The API at epic.nasa.gov, however, is not, nor does it require an API key to use. These features will be ignored when using this API through epic.nasa.gov.

await enhanced_images(date: Optional[datetime.date] = None)¶

Retrieves metadata for enhanced color imagery for a given date. Defaults to most recent date.

Parameters: date (datetime.date) – The date to request data for.
Returns: Data returned by the API.
Return type: List[EarthImage]

await enhanced_listing()¶

Retrieve a listing of all dates with available enhanced color imagery.

Returns: The dates returned by the API.
Return type: List[datetime.date]

await natural_images(date: Optional[datetime.date] = None)¶

Retrieves metadata for natural color imagery for a given date. Defaults to most recent date.

Parameters: date (datetime.date) – The date to request data for.
Returns: Data returned by the API.
Return type: List[EarthImage]

await natural_listing()¶

Retrieve a listing of all dates with available natural color imagery.

Returns: The dates returned by the API.
Return type: List[datetime.date]

Data Class¶

class aionasa.epic.EarthImage(client, json, collection)¶

A NASA EPIC image asset. Accessible as a full-resolution PNG, half-resolution JPG, or a thumbnail JPG image.

client¶

The EPIC client that was used to retrieve this data.

Type: EPIC

json¶

The JSON data returned by the API.

Type: dict

png_url¶: The URL of the full-resolution PNG image.

jpg_url¶: The URL of the half-resolution JPEG image.

thumb_url¶: The URL of the thumbnail-size JPEG image.

date¶

The date this image was taken.

Type: datetime.Date

caption¶: The caption for this image.

image¶: The image name.

centroid_coordinates¶

Geographical coordinates that the satellite is looking at as a named tuple.

Type: EarthCoordinates

dscovr_j2000_position¶

Position of the satellite in space as a named tuple.

Type: J2000Coordinates

lunar_j2000_position¶

Position of the moon in space as a named tuple.

Type: J2000Coordinates

sun_j2000_position¶

Position of the sun in space as a named tuple.

Type: J2000Coordinates

attitude_quaternions¶

Satellite attitude as a named tuple.

Type: Attitude

await read(filetype='png')¶

Downloads the file associated with this Asset.

Parameters: url (str) – The URL to download the asset from, for subclasses with multiple options.
Returns: The file, downloaded from the URL.
Return type: bytes

await save(path=None, filetype='png')¶

Downloads the file associated with this Asset and saves to the requested path.

Parameters

url (str) – The URL to download the asset from, for subclasses with multiple options.
path – The file path at which to save the file. If None, saves the image to the working directory using the filename from the asset url.

Example Code¶

This is a sample script that will print out some data on all images from the most recent available date.

import asyncio
from aionasa import EPIC

async def main():
    async with EPIC() as epic:
        images = await epic.natural_images()
        for i, image in enumerate(images):
            print(f"Image {i+1} of {len(images)}\n"
                  f"Url: {image.png_url}\n"
                  f"Caption: {image.caption}\n")

if __name__ == "__main__":
    asyncio.run(main())