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: