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.

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.

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.

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.

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

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


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
        }
    });


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: