About the API

EPIC Daily “Blue Marble” API

The EPIC API provides information on the daily imagery collected by DSCOVR's Earth Polychromatic Imaging Camera (EPIC) instrument. Uniquely positioned at the Earth-Sun Lagrange point, EPIC provides full disc imagery of the Earth and captures unique perspectives of certain astronomical events such as lunar transits using a 2048x2048 pixel CCD (Charge Coupled Device) detector coupled to a 30-cm aperture Cassegrain telescope.

Development of the EPIC API began in 2015, and is supported by the web development team for the Laboratory for Atmospheres in the Earth Sciences Division of the Goddard Space Flight Center.

API Version 2.0

Image metadata and key information regarding the natural color and the enhanced color imagery are provided by the JSON API and can be requested by date and for the most recent available date. A listing of all available dates can also be retrieved via the API for more granular control.

Querying the API

Parameter	Type	Default	Description
natural	string	Most Recent Natural Color	Retrieve metadata on the most recent date of natural color imagery.
natural/date	YYYY-MM-DD	Most Recent Available	Retrieve metadata for natural color imagery available for a given date.
natural/all	string	Dates for Natural Color	Retrieve a listing of all dates with available natural color imagery.
natural/available	string	Dates for Natural Color	Retrieve a listing of all dates with available natural color imagery.
enhanced	string	Most Recent Enhanced Color	Retrieve metadata on the most recent date of enhanced color imagery.
enhanced/date	YYYY-MM-DD	Most Recent Available	Retrieve metadata for enhanced color imagery for a given date.
enhanced/all	string	Dates for Enhanced Imagery	Retrieve a listing of all dates with available enhanced color imagery.
enhanced/available	string	Dates for Enhanced Imagery	Retrieve a listing of all dates with available enhanced color imagery.
aerosol	string	Most Recent Aerosol Index	Retrieve metadata on the most recent date of aerosol index imagery.
aerosol/date	YYYY-MM-DD	Most Recent Available	Retrieve metadata for aerosol index imagery for a given date.
aerosol/all	string	Dates for Aerosol Index	Retrieve a listing of all dates with available aerosol index imagery.
aerosol/available	string	Dates for Aerosol Index	Retrieve a listing of all dates with available aerosol index imagery.
cloud	string	Most Recent Cloud Fraction	Retrieve metadata on the most recent date of cloud fraction imagery.
cloud/date	YYYY-MM-DD	Most Recent Available	Retrieve metadata for cloud fraction imagery for a given date.
cloud/all	string	Dates for Cloud Fraction	Retrieve a listing of all dates with available cloud fraction imagery.
cloud/available	string	Dates for Cloud Fraction	Retrieve a listing of all dates with available cloud fraction imagery.

For this new version of the API, we have tried to maintain as much backward compatibility as possible to the original version of the API. In addition to the parameters provided above, the majority of the original API parameters should work as well. That backward compatibility may be phased out over time, so please plan accordingly.

Retrievable Metadata

The following information is available for every image in the collection:

image [name]
date
caption
centroid_coordinates
dscovr_j2000_position
lunar_j2000_position
sun_j2000_position
attitude_quaternions
coords

lat (Latitude)
lon (Longitude)
centroid_coordinates (Geographical coordinates that the satellite is looking at)
dscovr_j2000_position (Position of the satellite in space)
lunar_j2000_position (Position of the moon in space)
sun_j2000_position (Position of the sun in space)
attitude_quaternions (Satellite attitude)

Image Locations

All of our imagery is stored in an archival directory subdivided by collection, year, month, day, and image type. There are three separate image types available: full resolution PNG, half-resolution JPG, and thumbnails. Paths to imagery can be found using the following schema:

Site Name	Archive	Collection	Year	Month	Day	Image Type	File Name
https://epic.gsfc.nasa.gov	archive	natural	2016	10	31	png	epic_1b_20161031xxxx.png
https://epic.gsfc.nasa.gov	archive	natural	2016	10	31	jpg	epic_1b_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	natural	2016	10	31	thumbs	epic_1b_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	enhanced	2016	10	31	png	epic_RGB_20161031xxxx.png
https://epic.gsfc.nasa.gov	archive	enhanced	2016	10	31	jpg	epic_RGB_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	enhanced	2016	10	31	thumbs	epic_RGB_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	aerosol	2016	10	31	png	epic_uvai_20161031xxxx.png
https://epic.gsfc.nasa.gov	archive	aerosol	2016	10	31	jpg	epic_uvai_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	aerosol	2016	10	31	thumbs	epic_uvai_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	cloud	2016	10	31	png	epic_cloudfraction_20161031xxxx.png
https://epic.gsfc.nasa.gov	archive	cloud	2016	10	31	jpg	epic_cloudfraction_20161031xxxx.jpg
https://epic.gsfc.nasa.gov	archive	cloud	2016	10	31	thumbs	epic_cloudfraction_20161031xxxx.jpg

Note that the x's in the file name represent areas of variance.

Example Queries

https://epic.gsfc.nasa.gov/api/natural

https://epic.gsfc.nasa.gov/api/enhanced/date/2015-10-31

https://epic.gsfc.nasa.gov/api/natural/all

https://epic.gsfc.nasa.gov/archive/natural/2015/10/31/png/epic_1b_20151031074844.png

API Mirroring and CORS Support

The EPIC API is now also available through the api.nasa.gov service, which acts as a mirror for the EPIC API. The API will continue to remain available on this website as well. The added benefit of the mirroring service is to provide cross-origin resource sharing (CORS) support for imagery, should any applications require it.

Getting the Data

WGET:

wget https://epic.gsfc.nasa.gov/api/natural

PHP:

    $data_url = 'https://epic.gsfc.nasa.gov/api/natural';
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $data_url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $imageDataArray = json_decode(curl_exec($ch));

jQuery:

var meta = JSON.parse('https://epic.gsfc.nasa.gov/api/natural');

$.ajax('https://epic.gsfc.nasa.gov/api/natural', {
        success : function(iDataArr, stat, xhr) {
            // do something with the list
        }
    });

Getting the Imagery

PHP

    $month = '08';
    $day = 21;
    $year = '2017';

    $metadata = "https://epic.gsfc.nasa.gov/api/natural/date/{$year}-{$month}-{$day}";
    $meta = file_get_contents($metadata);   // get the metadata for that date and collection
    $arr = json_decode($meta);  // decode the metadata

    foreach($arr as $item) {
        $name = $item->image . '.png';
        $archive = "https://epic.gsfc.nasa.gov/archive/natural/{$year}/{$month}/{$day}/png/";

        $source = $archive . $name;
        $destination = '/path/to/downloads/' . $name;

        copy($source, $destination);    // download and copy the image
    }

The following information is about an older version of the API, and is only being provided for archival purposes.

API Version 1.0

The API URL can be utilized in two different ways: The most up-to-date list of images can be obtained by directing a REST consumer to:

https://epic.gsfc.nasa.gov/api/images.php

This will retrieve a list of the latest available images & metadata. The list of images available may vary from as little as one (or none) to as many as 20, or more.

Querying by Date(s)

Parameter	Type	Default	Description
date	YYYY-MM-DD	Most Recent Available	Retrieve metadata for all imagery available for a given date.
available_dates	string	All Available Dates	Retrieve a listing of all dates with available imagery.

Example queries

https://epic.gsfc.nasa.gov/api/images.php
https://epic.gsfc.nasa.gov/api/images.php?date=2015-10-31
https://epic.gsfc.nasa.gov/api/images.php?available_dates

OS X Automator Workflow

The Automator utility that comes bundled with OS X can work with the API. To use this example, create a new Automator workflow, so it looks like this: