Mars Data API

A REST API service that provides Mars elevation data and star map data based on coordinates (latitude and longitude) and optional time parameters.

Features

• Elevation Data: Get accurate Mars elevation data for any coordinates on the Martian surface
• Star Maps: Generate star maps visible from Mars for any location and time
• Time-Based Queries: Query star maps for past or future Mars dates, including seasonal effects
• Mars Astronomical Parameters: Incorporates Mars' axial tilt, seasonal dust storms, and orbital parameters
• Simple JSON API: Easy to integrate with any client application
• High Performance: Optimized for quick responses with caching mechanisms

Installation

Prerequisites

• Go 1.21 or higher
• Git

Getting Started

1. Clone the repository:

   git clone https://github.com/ProgramComputer/mars-data-api.git
   cd mars-data-api
   

2. Install dependencies:

   go mod tidy
   

3. Create a .env file with necessary configuration (see .env.example)

4. Download the MOLA data files:

   chmod +x download_mola_data.sh
   ./download_mola_data.sh
   

   This script will download Mars elevation data files from the PDS Geosciences Node at Washington University in St. Louis. The data files are quite large (130MB each) and may take some time to download.

5. Run the server:

   go run cmd/server/main.go
   

API Documentation

API Overview

The Mars Data API provides access to Mars elevation data and star map data based on coordinates (latitude and longitude) and optionally time parameters. It is designed to be easy to integrate with any client application.

Base URL: http://your-server-address:8080

API Endpoints

1. Get Elevation Data

Returns the elevation in meters for a specific location on Mars.

GET /api/elevation

Query Parameters

Parameter	Type	Required	Description
lat	float	Yes	Latitude in degrees (-90 to 90)
lon	float	Yes	Longitude in degrees (0 to 360 or -180 to 180)

Response Format

{
  "latitude": 18.65,
  "longitude": 226.2,
  "elevation": 21749.3,
  "timestamp": "2023-05-15T08:24:13Z"
}

Response Fields

Field	Type	Description
latitude	float	The latitude used for the query
longitude	float	The longitude used for the query
elevation	float	Elevation in meters above Mars datum
timestamp	string	ISO 8601 timestamp when the response was generated

Example Request

GET /api/elevation?lat=18.65&lon=226.2

Status Codes

Status Code	Description
200	Successful request
400	Invalid parameters
404	No elevation data available for the specified coordinates
503	Elevation service temporarily unavailable

2. Get Star Map Data

Returns stars visible from a specific location on Mars at a specific time.

GET /api/sky

Query Parameters

Parameter	Type	Required	Description
lat	float	Yes	Latitude in degrees (-90 to 90)
lon	float	Yes	Longitude in degrees (0 to 360 or -180 to 180)
time	float	No	Mars time in hours (0-24, where 0 is midnight). Default: current hour
date	string	No	Earth date in ISO8601 format (YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ) for past/future queries
mars_year	int	No	Mars year number (MY), e.g., 36 for current Mars year
mars_sol	int	No	Sol number within the Mars year
limit	int	No	Maximum number of stars to return. Default: 500

Note: For date-specific queries, you can use either:

• The date parameter with an Earth date
• Or a combination of mars_year and mars_sol parameters If neither is provided, the current date is used.

Response Format

{
  "latitude": -4.5895,
  "longitude": 137.4417,
  "time": 0,
  "mars_date": {
    "earth_date": "2023-05-15T08:24:13Z",
    "mars_sol": 753,
    "mars_year": 36,
    "solar_longitude": 127.8
  },
  "stars": [
    {
      "hip": 32349,
      "magnitude": -1.46,
      "altitude": 45.23,
      "azimuth": 123.45,
      "color": "#FFFFFF"
    },
    {
      "hip": 30438,
      "magnitude": -0.74,
      "altitude": 22.5,
      "azimuth": 215.3,
      "color": "#F6F5FF"
    },
    // More stars...
  ],
  "count": 325,
  "timestamp": "2023-05-15T08:24:13Z"
}

Response Fields

Field	Type	Description
latitude	float	The latitude used for the query
longitude	float	The longitude used for the query
time	float	The Mars time used for the query (0-24 hours)
mars_date	object	Mars date information
mars_date.earth_date	string	ISO8601 Earth date/time corresponding to the Mars date
mars_date.mars_sol	int	Sol number in the Mars year
mars_date.mars_year	int	Mars year (MY)
mars_date.solar_longitude	float	Solar longitude (Ls), indicating Mars season (0°=spring equinox, 90°=summer solstice, etc.)
stars	array	Array of visible stars
stars[].hip	int	Hipparcos catalog ID of the star
stars[].magnitude	float	Visual magnitude of the star (lower is brighter)
stars[].altitude	float	Degrees above horizon (negative if below)
stars[].azimuth	float	Degrees clockwise from north (0-360)
stars[].color	string	HTML color code representing star's color
count	int	Number of visible stars returned
timestamp	string	ISO 8601 timestamp when the response was generated

Example Requests

Current time star map:

GET /api/sky?lat=-4.5895&lon=137.4417

Night sky at a specific time:

GET /api/sky?lat=-4.5895&lon=137.4417&time=0

Star map for a specific Earth date:

GET /api/sky?lat=-4.5895&lon=137.4417&date=2030-01-01

Star map for a specific Mars year and sol:

GET /api/sky?lat=-4.5895&lon=137.4417&mars_year=36&mars_sol=500

Status Codes

Status Code	Description
200	Successful request
400	Invalid parameters
503	Star map service temporarily unavailable

3. Combined Data Endpoint

Returns both elevation and star data from a single endpoint, with filtering options.

GET /api/data

Query Parameters

Parameter	Type	Required	Description
lat	float	Yes	Latitude in degrees (-90 to 90)
lon	float	Yes	Longitude in degrees (0 to 360 or -180 to 180)
type	string	No	Filter type: "elevation", "sky", or omit for both
time	float	No	Mars time in hours (0-24). Default: current hour
date	string	No	Earth date in ISO8601 format
mars_year	int	No	Mars year number (MY)
mars_sol	int	No	Sol number within the Mars year
limit	int	No	Maximum number of stars to return. Default: 500

Response Format

When requesting both elevation and star data:

{
  "latitude": 18.65,
  "longitude": 226.2,
  "elevation": 21749.3,
  "time": 12.5,
  "mars_date": {
    "earth_date": "2023-05-15T08:24:13Z",
    "mars_sol": 753,
    "mars_year": 36,
    "solar_longitude": 127.8
  },
  "stars": [...],
  "stars_count": 325,
  "timestamp": "2023-05-15T08:24:13Z"
}

Example Requests

Getting both elevation and star data:

GET /api/data?lat=18.65&lon=226.2

Only getting elevation data:

GET /api/data?lat=18.65&lon=226.2&type=elevation

Only getting star data for a specific future date:

GET /api/data?lat=18.65&lon=226.2&type=sky&date=2030-01-01

Mars Astronomical Features

The API takes into account the following Mars-specific astronomical features:

1. Mars Axial Tilt and Seasons

Mars has an axial tilt of approximately 25.19° (compared to Earth's 23.5°), which creates seasons similar to Earth's. The API uses the solar longitude (Ls) to determine the current season on Mars:

• Ls = 0° - Northern Spring Equinox / Southern Autumn Equinox
• Ls = 90° - Northern Summer Solstice / Southern Winter Solstice
• Ls = 180° - Northern Autumn Equinox / Southern Spring Equinox
• Ls = 270° - Northern Winter Solstice / Southern Summer Solstice

2. Dust Storms and Star Visibility

The API factors in the effect of seasonal dust storms, which tend to be more prevalent during the southern spring/summer seasons (Ls 180°-360°), with peak activity around Ls 270°. These dust storms can reduce star visibility.

3. Mars Year and Sol System

The API uses the following Mars calendar conventions:

• Mars Year 1 (MY 1) began on April 11, 1955 (Earth date)
• A Mars sol (day) is approximately 24.6 Earth hours
• A Mars year is approximately 668.6 sols or 687 Earth days

Error Responses

When an error occurs, the API returns a JSON object with an error message:

{
  "error": "Invalid latitude value"
}

Rate Limiting

The API currently does not implement rate limiting, but excessive usage may be throttled in the future. Please use the API responsibly.

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) to allow browser-based applications to access the API from different domains.

Data Sources

The Mars Data API uses the following data sources:

• Mars Elevation Data: Mars Orbiter Laser Altimeter (MOLA) data from NASA's Mars Global Surveyor mission, provided by the PDS Geosciences Node at Washington University in St. Louis. The data files are downloaded directly from their servers using the included download_mola_data.sh script.

• Star Catalog: Hipparcos star catalog for accurate star positions and magnitudes.

The MOLA data files are quite large (approximately 130MB each) and are not included in this repository. Instead, they must be downloaded using the provided script, which will place them in the correct location (data/mola/) for the API to use.

Note on GitHub LFS: Due to GitHub's LFS storage limitations, we use the download script approach instead of Git LFS to manage the large data files. This ensures anyone can run the API without hitting storage quotas.

License

This project is licensed under the BSD License - see the LICENSE file for details.

Acknowledgements

• Smith, D.E., M.T. Zuber, G.A. Neumann, E.A. Guinness, and S. Slavney, Mars Global Surveyor Laser Altimeter Mission Experiment Gridded Data Record, MGS-M-MOLA-5-MEGDR-L3-V1.0, NASA Planetary Data System, 2003.
• ESA, 1997, The Hipparcos and Tycho Catalogues, ESA SP-1200.