Filtering & Pagination

Master advanced query techniques to find exactly the photos you need.

Basic Filtering

Filter by Rover

# Single rover
curl "...?rovers=curiosity"

# Multiple rovers
curl "...?rovers=curiosity,perseverance"

Filter by Camera

# Single camera
curl "...?cameras=NAVCAM"

# Multiple cameras
curl "...?cameras=NAVCAM,FHAZ,RHAZ"

Filter by Date

# By sol range
curl "...?sol_min=1000&sol_max=1100"

# By Earth date range
curl "...?date_min=2024-01-01&date_max=2024-01-31"

# Single date (min = max)
curl "...?date_min=2024-01-15&date_max=2024-01-15"

Combining Filters

Combine multiple filters with &. All filters use AND logic.

# Curiosity NAVCAM photos from Sol 1000
curl "...?rovers=curiosity&cameras=NAVCAM&sol_min=1000&sol_max=1000"

# All rovers, high-res photos from January 2024
curl "...?date_min=2024-01-01&date_max=2024-01-31&min_width=1920&sample_type=Full"

Advanced Filters

Location-Based Queries

Filter by rover position using site/drive coordinates:

# Exact location
curl "...?site=79&drive=1204"

# Location range (rover's journey)
curl "...?site_min=70&site_max=80"

# Proximity search (within radius)
curl "...?site=79&drive=1204&location_radius=5"

Mars Time Queries

Filter by Mars local time when photos were taken:

# Morning photos (6 AM - 10 AM Mars time)
curl "...?mars_time_min=M06:00:00&mars_time_max=M10:00:00"

# Golden hour (sunrise/sunset)
curl "...?mars_time_golden_hour=true"

Image Quality Filters

# High resolution only
curl "...?min_width=1920&min_height=1080"

# Specific sample type
curl "...?sample_type=Full"

# Aspect ratio range (widescreen)
curl "...?aspect_ratio_min=1.5&aspect_ratio_max=2.0"

Camera Angle Queries

Filter by mast camera orientation:

# Horizon shots (elevation near 0)
curl "...?mast_elevation_min=-5&mast_elevation_max=5"

# Looking down (negative elevation)
curl "...?mast_elevation_max=-30"

# Specific compass direction (azimuth 0-360)
curl "...?mast_azimuth_min=90&mast_azimuth_max=180"  # East to South

Sorting Results

Use the sort parameter to order results. Prefix with - for descending order.

# Newest first (default)
curl "...?sort=-date_taken_utc"

# Oldest first
curl "...?sort=date_taken_utc"

# By sol (ascending)
curl "...?sort=sol"

# Multiple sort fields
curl "...?sort=-earth_date,camera"

Sort Field	Description
date_taken_utc	Capture time in UTC (default, descending)
earth_date	Earth date taken
sol	Mission sol number
camera	Camera name
id	Photo ID
created_at	When the photo was added to the archive
rating	Average community rating
rating_count	Number of ratings

Pagination

Results are paginated. Use page andper_page to navigate.

# First page, 25 items (default)
curl "...?page=1"

# Second page, 50 items per page
curl "...?page=2&per_page=50"

# Maximum page size (100)
curl "...?per_page=100"

Pagination Response

Every response includes pagination metadata and navigation links:

{
  "data": [...],
  "meta": {
    "total_count": 15234,
    "returned_count": 25
  },
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 610
  },
  "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=610"
  }
}

Tip

Use the URLs in links for navigation. They preserve your filters and sorting.

Field Selection

Control response size by selecting specific fields or using presets.

Field Set Presets

Preset	Includes
minimal	id, sol, medium image only
standard	Basic photo data + all image sizes (default)
extended	Standard + location, dimensions, Mars time
scientific	All telemetry, camera angles, coordinates
complete	Everything including raw NASA data

# Use preset
curl "...?field_set=minimal"

# Custom field selection
curl "...?fields=id,sol,earth_date,images"

# Include related resources
curl "...?include=rover,camera"

Common Query Patterns

Latest Photos from All Active Rovers

curl "...?rovers=curiosity,perseverance&sort=-earth_date&per_page=20&include=rover,camera"

High-Quality Panoramic Candidates

curl "...?sample_type=Full&mast_elevation_min=-5&mast_elevation_max=5&min_width=1920&cameras=NAVCAM,MAST"

Golden Hour Beauty Shots

curl "...?mars_time_golden_hour=true&rovers=curiosity&sample_type=Full&sort=-earth_date"

Rover Journey Through Location Range

curl "...?rovers=perseverance&site_min=1&site_max=50&field_set=extended&sort=sol"

Next Steps

Photos Reference →Complete parameter documentation
Rate Limits →Optimize your API usage