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
    }