Understanding Mars Time
Mars has its own time system. Understanding it unlocks powerful query capabilities.
What is a Sol?
A solis one Martian day. It's slightly longer than an Earth day:
1 sol = 24 hours, 39 minutes, 35 seconds (Earth time)
Each rover mission counts sols from the day of landing, starting at Sol 0 or Sol 1. This means Sol 1000 for Curiosity is a completely different Earth date than Sol 1000 for Perseverance.
Rover Landing Dates
| Rover | Landing Date | Sol 1 | Status |
|---|---|---|---|
| Perseverance | February 18, 2021 | Feb 19, 2021 | Active |
| Curiosity | August 6, 2012 | Aug 7, 2012 | Active |
| Opportunity | January 25, 2004 | Jan 26, 2004 | Complete |
| Spirit | January 4, 2004 | Jan 5, 2004 | Complete |
Querying by Sol
Query photos from a specific sol or range of sols:
Single Sol
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?rovers=curiosity&sol_min=1000&sol_max=1000"Sol Range
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?rovers=perseverance&sol_min=100&sol_max=200"Tip
Use sol queries to follow a rover's journey chronologically. Each sol typically has 10-200 photos depending on the rover's activities that day.
Mars Local Time
Each photo includes the local Mars time when it was taken. The format is:
"date_taken_mars": "Sol-04728M14:23:45.528"This breaks down as:
Sol-04728- Mission sol numberM14:23:45- Mars local time (24-hour format).528- Fractional seconds
Query by Mars Time
Find photos taken at specific Mars local times:
# Photos taken during Mars morning (6 AM - 10 AM)
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?mars_time_min=M06:00:00&mars_time_max=M10:00:00"
# Photos taken during Mars noon (12 PM - 2 PM)
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?mars_time_min=M12:00:00&mars_time_max=M14:00:00"Golden Hour Photography
Just like on Earth, Mars has beautiful "golden hour" lighting during sunrise and sunset. Use the special mars_time_golden_hour filter:
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?mars_time_golden_hour=true&rovers=curiosity"This returns photos taken approximately 1 hour after sunrise or 1 hour before sunset on Mars.
Mars Golden Hour Times
- Morning: ~6:00 - 7:30 Mars time
- Evening: ~17:30 - 19:00 Mars time
(Varies by season and location on Mars)
When to Use Sol vs Earth Date
Use Sol When…
- •Following a rover's chronological journey
- •Comparing similar mission phases across rovers
- •Building mission timelines
- •Scientific analysis of rover activities
Use Earth Date When…
- •Finding "what did rovers see today?"
- •Comparing photos from the same Earth day
- •Building calendars or date-based UIs
- •News or media applications
Query by Earth Date
# Photos from a specific Earth date
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?date_min=2024-01-15&date_max=2024-01-15"
# Photos from a date range
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?date_min=2024-01-01&date_max=2024-01-31"Time Fields in Responses
Each photo includes multiple time fields:
{
"attributes": {
"sol": 4728,
"earth_date": "2025-11-24",
"date_taken_utc": "2025-11-24T14:23:45Z",
"date_taken_mars": "Sol-04728M14:23:45.528"
}
}| Field | Description |
|---|---|
| sol | Mission sol number (integer) |
| earth_date | Earth date (YYYY-MM-DD) |
| date_taken_utc | UTC timestamp when photo was taken |
| date_taken_mars | Mars local time with sol prefix |
Next Steps
- Filtering & Pagination →Combine time filters with other queries
- Photos Reference →Complete list of query parameters