Photos API Reference
GET /api/v2/photos
Overview
Query Mars rover photos with powerful filtering, sorting, and pagination. This is the primary endpoint for accessing the photo database.
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos?rovers=curiosity&per_page=10&include=rover,camera"Query Parameters
Basic Filters
| Parameter | Type | Description |
|---|---|---|
| rovers | string | Comma-separated: curiosity, perseverance, opportunity, spirit |
| cameras | string | Comma-separated camera names: NAVCAM, FHAZ, RHAZ, MAST, etc. |
| sol_min | integer | Minimum sol number |
| sol_max | integer | Maximum sol number |
| date_min | string | Minimum Earth date (YYYY-MM-DD) |
| date_max | string | Maximum Earth date (YYYY-MM-DD) |
Location Filters
| Parameter | Type | Description |
|---|---|---|
| site | integer | Exact site number |
| drive | integer | Exact drive number |
| site_min / site_max | integer | Site range for journey tracking |
| location_radius | integer | Proximity search radius (requires site + drive) |
Mars Time Filters
| Parameter | Type | Description |
|---|---|---|
| mars_time_min | string | Minimum Mars local time (MHH:MM:SS) |
| mars_time_max | string | Maximum Mars local time (MHH:MM:SS) |
| mars_time_golden_hour | boolean | Filter for sunrise/sunset photos |
Image Quality Filters
| Parameter | Type | Description |
|---|---|---|
| min_width / min_height | integer | Minimum image dimensions |
| sample_type | string | Full, Subframe, or Thumbnail |
| aspect_ratio_min / max | number | Aspect ratio range (width/height) |
Camera Angle Filters
| Parameter | Type | Description |
|---|---|---|
| mast_elevation_min / max | number | Camera vertical angle (-90 to +90 degrees) |
| mast_azimuth_min / max | number | Camera compass direction (0-360 degrees) |
Pagination & Sorting
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | integer | 1 | Page number |
| per_page | integer | 25 | Items per page (max 100) |
| sort | string | -date_taken_utc | Sort field (prefix - for desc) |
Response Control
| Parameter | Type | Description |
|---|---|---|
| include | string | Include related resources: rover, camera |
| field_set | string | Field preset: minimal, standard, extended, scientific, complete |
| fields | string | Custom field selection (comma-separated) |
| image_sizes | string | Which sizes to include: small, medium, large, full |
| exclude_images | boolean | Return metadata only (no image URLs) |
Response Format
{
"data": [
{
"id": 2544294,
"type": "photo",
"attributes": {
"nasa_id": "1533956",
"sol": 4728,
"earth_date": "2025-11-24",
"date_taken_utc": "2025-11-24T14:23:45Z",
"date_taken_mars": "Sol-04728M14:23:45.528",
"images": {
"small": "https://mars.nasa.gov/..._320.jpg",
"medium": "https://mars.nasa.gov/..._800.jpg",
"large": "https://mars.nasa.gov/..._1200.jpg",
"full": "https://mars.nasa.gov/..._full.jpg"
},
"dimensions": { "width": 1920, "height": 1080 },
"sample_type": "Full",
"title": "Sol 4728: Navigation Camera",
"caption": "This image was taken by...",
"credit": "NASA/JPL-Caltech",
"location": {
"site": 79,
"drive": 1204,
"coordinates": { "x": 35.4, "y": 22.5, "z": -9.4 }
},
"telemetry": {
"mast_azimuth": 156.098,
"mast_elevation": -10.165
}
},
"relationships": {
"rover": {
"id": "curiosity",
"type": "rover",
"attributes": { "name": "Curiosity", "status": "active" }
},
"camera": {
"id": "NAVCAM",
"type": "camera",
"attributes": { "full_name": "Navigation Camera" }
}
}
}
],
"meta": {
"total_count": 682660,
"returned_count": 1,
"timestamp": "2025-11-25T12:00:00Z"
},
"pagination": {
"page": 1,
"per_page": 25,
"total_pages": 27307
},
"links": {
"self": "https://api.marsvista.dev/api/v2/photos?page=1",
"next": "https://api.marsvista.dev/api/v2/photos?page=2",
"first": "https://api.marsvista.dev/api/v2/photos?page=1",
"last": "https://api.marsvista.dev/api/v2/photos?page=27307"
}
}Note: Image Availability
The small, medium, and large image sizes are only available for Perseverance. For Curiosity, Spirit, and Opportunity, only full is available.
Photo Statistics
GET /api/v2/photos/stats
Get aggregate statistics about photos, grouped by camera, rover, or sol.
curl -H "X-API-Key: YOUR_KEY" \
"https://api.marsvista.dev/api/v2/photos/stats?group_by=camera&rovers=curiosity"Query Parameters
| Parameter | Type | Description |
|---|---|---|
| group_by | string | Grouping dimension: camera, rover, or sol |
| rovers | string | Filter by rover(s) |
| cameras | string | Filter by camera(s) |
| sol_min / sol_max | integer | Filter by sol range |
Response Format
{
"data": {
"total_photos": 682660,
"period": {
"from": "2012-08-06",
"to": "2025-11-24"
},
"groups": [
{
"key": "NAVCAM",
"count": 89234,
"percentage": 13.07,
"avg_per_sol": 18.9
},
{
"key": "MAST",
"count": 156789,
"percentage": 22.96,
"avg_per_sol": 33.2
}
]
},
"meta": {
"returned_count": 7,
"timestamp": "2025-11-25T12:00:00Z"
}
}Group Fields
| Field | Type | Description |
|---|---|---|
| key | string | Group identifier (camera name, rover slug, or sol number) |
| count | integer | Number of photos in this group |
| percentage | number | Percentage of total photos (0-100) |
| avg_per_sol | number | Average photos per sol (only for rover grouping) |
| earth_date | string | Earth date (only for sol grouping) |
Related Endpoints
- GET /api/v2/rovers →List all rovers
- GET /api/v2/cameras →List all cameras
- Error Handling →Error response formats