ENG | RUS
API
Martian Atmosphere Observation and Modeling

MAOAM API

Our site has a very flexible API that allows you to use our data online in your projects.

How to construct query

All API queries should be passed as a GET request in such form:

https://mars.mipt.ru/ajax/get-data.php?
api=1&
var=h2oim_mix&
time_from=100&
time_to=100&
time_range=ave&
hour_from=0&
hour_to=23&
hour_range=ave&
lon_from=-180&
lon_to=180&
lon_range=ave&
lat_from=-90&
lat_to=90&
lat_range=range&
altype=h&
lev_from=0&
lev_to=60&
lev_range=range&
version=1.104

Possible values

The possible values for the variables are listed in the table:

VariableNameValueDescription
apiAPI1Always should be set to 1.
varVariableuZonal velocities, m/s
vMeridional velocities, m/s
uvAbsolute horizontal velocities, m/s
wVertical velocities, m/s
TTemperature, K
TsSurface temperature, K
pPressure, Pa
hHeight, km
psSurface pressure, Pa
rhoDensity, kg/m3
h2ogH2O vapor, kg/m2
h2og_prH2O vapor, Pr.mkm
h2og_stH2O vapor on 6 mbar, kg/m2
h2og_mixH2O vapor mix. ratio, mg/kg
h2og_ppmvH2O vapor mix. ratio, ppmv
h2oimH2O ice, kg/m2
h2oim_prH2O ice, Pr.mkm
h2oim_opH2O ice, opacity in 825 cm-1
h2oim_mixH2O ice mix. ratio, mg/kg
h2oinH2O ice number density, cm-3
h2oirH2O ice particle radius, mkm
gdq_mixDust mix. ratio (given), mg/kg
gdq_opDust opacity (given), opacity in 1075 cm-1
dustnDust number density (given), cm-3
h2oisSurface H2O ice, kg/m2
dmCO2 ice cloud mass concentration, g/m3
hcapSurface CO2 ice, kg/m2
dipreDelta pressure, Pa
dihCell heights, m
surfCell areas, km2
time_fromfrom Ls0 - 360Should be less than or equal to time_to.
time_toto Ls Should be greater than or equal to time_from.
time_rangeLs range typerangeRange
aveAverage
sumSumming
maxMaximum
minMinimum
hour_fromfrom local Hour0 - 23Should be less than or equal to hour_to.
hour_toto local Hour Should be greater than or equal to hour_from.
hour_rangeHour range type, should be equal to time_rangerangeRange
aveAverage
sumSumming
maxMaximum
minMinimum
lon_fromfrom Longitude-180 - 180Should be less than or equal to lon_to.
lon_toto Longitude Should be greater than or equal to lon_from.
lon_rangeLongitude range typerangeRange
aveAverage
sumSumming
maxMaximum
minMinimum
lat_fromfrom Latitude-90 - 90Should be less than or equal to lat_to.
lat_toto Latitude Should be greater than or equal to lat_from.
lat_rangeLatitude range typerangeRange
aveAverage
sumSumming
maxMaximum
minMinimum
altypeAltitude typehHeight above surface
hoHeight above "sea level"
pPressure
levHybrid model levels
lev_fromfrom Level0 - 160 for
altype = [ h, ho ],
0.0000036 - 607 for
altype = [ p, lev ]
Should be less than or equal to lev_to.
lev_toto Level Should be greater than or equal to lev_from.
lev_rangeLevel range typerangeRange
aveAverage
sumSumming
maxMaximum
minMinimum
versionGCM version 1.104Water cycle for annual dust, CO2 cycle, dust bimodal distribution and GW only for variables u, v, uv, w, T, Ts, p, h, ps, rho, h2og, h2og_pr, h2og_st, h2og_mix, h2og_ppmv, h2oim, h2oim_pr, h2oim_mix, h2oim_op, h2oin, h2oir, h2ois, co2is, dipre, dih, surf, gdq_mass, gdq_mix, gdq_op, dustn, dustr, dm, hcap.
1.110Martian year 28 dust storm (Ls 230 - 312) only for variables u, v, uv, w, T, Ts, p, h, ps, rho, h2og, h2og_pr, h2og_st, h2og_mix, h2og_ppmv, h2oim, h2oim_pr, h2oim_mix, h2oim_op, h2oin, h2oir, h2ois, co2is, dipre, dih, surf, gdq_mass, gdq_mix, gdq_op, dustn, dustr, dm, hcap.
1.114Martian year 34 dust storm (Ls 185 - 267) only for variables u, v, uv, w, T, Ts, p, h, ps, rho, h2og, h2og_pr, h2og_st, h2og_mix, h2og_ppmv, h2oim, h2oim_pr, h2oim_mix, h2oim_op, h2oin, h2oir, h2ois, co2is, dipre, dih, surf, gdq_mass, gdq_mix, gdq_op, dustn, dustr, dm, hcap.

Then the site will return JSON answer with a file name or a number.

Answer example 1

{
"id":"871",
"hash":"4jPDBS9OxovVj78fcFnEVyqlBzMxu8",
"num":"",
"txt":"VODsZDkGglXS1qpDdnkN3GQoaFGl4X.txt",
"result":"success"
}

Answer example 2

{
"id":"",
"hash":"",
"num":"1.58469712734",
"txt":"",
"result":"success"
}

Answer example 3

{
"result":"error",
"mes":"Wrong version!"
}

If the "result" is "success" then you should check the field "num" to understand if the site returned a number or a file. The "mes" field will contain the error message if an error occurred. The "txt" field contains filename and allows you to download the result of the calculations:

https://mars.mipt.ru/data/txt/VODsZDkGglXS1qpDdnkN3GQoaFGl4X.txt

Working examples

Python

# Loading libraries
import requests, json, pandas

# Constructing the URL
url = "https://mars.mipt.ru/ajax/get-data.php?api=1&var=h2oim_mix&time_from=100&time_to=100&time_range=ave&hour_from=0&hour_to=23&hour_range=ave&lon_from=-180&lon_to=180&lon_range=ave&lat_from=-90&lat_to=90&lat_range=range&altype=h&lev_from=0&lev_to=60&lev_range=range&version=1.104"

# Sending the request to the site
response = requests.get(url)

# Reading the response in JSON
json_response = json.loads(response.content)

# Getting the file, trimming and extracting the data
csv = pandas.read_csv('https://mars.mipt.ru/data/txt/'+json_response['txt'], sep="\t", skiprows=19)

# Printing the first lines
csv.head()

PHP

// Constructing the URL
$url = "https://mars.mipt.ru/ajax/get-data.php?api=1&var=h2oim_mix&time_from=100&time_to=100&time_range=ave&hour_from=0&hour_to=23&hour_range=ave&lon_from=-180&lon_to=180&lon_range=ave&lat_from=-90&lat_to=90&lat_range=range&altype=h&lev_from=0&lev_to=60&lev_range=range&version=1.104";

// Sending the request to the site
$response = file_get_contents($url);

// Reading the response in JSON
$json_response = json_decode($response,true);

// Getting the file
$data = file_get_contents('https://mars.mipt.ru/data/txt/'.$json_response['txt']);

// Trimming the first 19 rows
$data = preg_replace('/^'.str_repeat('.*\n',19).'/', '', $data);

// Extracting the data
$csv = array();
foreach (explode(PHP_EOL, $data) as $line) {
    $csv[] = explode("\t", $line);
}

// Printing the first lines
for ($i = 0; $i < 5; $i++) {
    print_r($csv[$i]);
}

Fortran 77

To use the code provided below you will also need to install wget.

!     Defining variables
      implicit none
      character(len=500) :: url, buffer
      character(len=34) :: txt
      integer :: pos, i, iostat
      real*8 :: csv(1292,3)
      
!     Constructing the URL
      url = 'https://mars.mipt.ru/ajax/get-data.php?api=1&var=h'
     &   // '2oim_mix&time_from=100&time_to=100&time_range=ave&'
     &   // 'hour_from=0&hour_to=23&hour_range=ave&lon_from=-18'
     &   // '0&lon_to=180&lon_range=ave&lat_from=-90&lat_to=90&'
     &   // 'lat_range=range&altype=h&lev_from=0&lev_to=60&lev_'
     &   // 'range=range&version=1.104'
     
!     Sending the request to the site
      call system('wget -O json.tmp "' // url // '"')
      
!     Reading the response in JSON
      open(unit=1,file='json.tmp')
      read(1,"(A)") buffer
      pos = index(buffer, "txt")
      read(buffer(pos+6:pos+39), *) txt
      
!     Getting the file
      call system('wget -O data.csv "https://mars.mipt.ru/data/txt/'
     &            // txt // '"')
      
!     Trimming the first 20 rows
      open(unit=2,file='data.csv')
      do i = 1, 20
        read(2,"(A)") buffer
      enddo
    
!     Extracting the data
      do i = 1, 1292

        read(2,"(A)") buffer

        read(buffer,*,iostat=iostat) csv(i,1), csv(i,2), csv(i,3)
        
        ! if there is no data, let's associate -1.0000000000000000d100 with NaN
        if( iostat .ne. 0 ) then
          read(buffer,*,iostat=iostat) csv(i,1), csv(i,2)
          csv(i,3) = -1.0000000000000000d100
        endif
        
      enddo
      
!     Printing the first lines
      do i = 1, 5
        print*, csv(i,1), csv(i,2), csv(i,3)
      enddo

      end

Fortran 90

To use the code provided below you will also need to install wget.

!     Defining variables
      implicit none
      character(len=500) :: url, buffer
      character(len=34) :: txt
      integer :: pos, i, iostat
      real*8 :: csv(1292,3)
      
!     Constructing the URL
      url = 'https://mars.mipt.ru/ajax/get-data.php?api=1&var=h' &
         // '2oim_mix&time_from=100&time_to=100&time_range=ave&' &
         // 'hour_from=0&hour_to=23&hour_range=ave&lon_from=-18' &
         // '0&lon_to=180&lon_range=ave&lat_from=-90&lat_to=90&' &
         // 'lat_range=range&altype=h&lev_from=0&lev_to=60&lev_' &
         // 'range=range&version=1.104'
     
!     Sending the request to the site
      call system('wget -O json.tmp "' // url // '"')
      
!     Reading the response in JSON
      open(unit=1,file='json.tmp')
      read(1,"(A)") buffer
      pos = index(buffer, "txt")
      read(buffer(pos+6:pos+39), *) txt
      
!     Getting the file
      call system('wget -O data.csv "https://mars.mipt.ru/data/txt/' &
                  // txt // '"')
      
!     Trimming the first 20 rows
      open(unit=2,file='data.csv')
      do i = 1, 20
        read(2,"(A)") buffer
      enddo
    
!     Extracting the data
      do i = 1, 1292

        read(2,"(A)") buffer

        read(buffer,*,iostat=iostat) csv(i,1), csv(i,2), csv(i,3)
        
        ! if there is no data, let's associate -1.0000000000000000d100 with NaN
        if( iostat .ne. 0 ) then
          read(buffer,*,iostat=iostat) csv(i,1), csv(i,2)
          csv(i,3) = -1.0000000000000000d100
        endif
        
      enddo
      
!     Printing the first lines
      do i = 1, 5
        print*, csv(i,1), csv(i,2), csv(i,3)
      enddo

      end

C / C++

To use the code provided below you will also need to install wget.

// Loading libraries
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <math.h>

int main() {

    char url[500], buffer[500], txt[34];
    FILE *fjson, *fcsv;
    double data[1292][3];
    
//  Constructing the URL
    strcpy( url, "wget -O json.tmp \"" );
    strcat( url, "https://mars.mipt.ru/ajax/get-data.php?api=1&var=h2oim_mix&time_from=100&time_to=100&time_range=ave&hour_from=0&hour_to=23&hour_range=ave&lon_from=-180&lon_to=180&lon_range=ave&lat_from=-90&lat_to=90&lat_range=range&altype=h&lev_from=0&lev_to=60&lev_range=range&version=1.104" );
    strcat( url, "\"" );
    
//  Sending the request to the site
    system(url);
    
//  Reading the response in JSON
    fjson = fopen("json.tmp", "r");
    fscanf(fjson, "%s", buffer);
    fclose(fjson);

    strncpy(txt, strstr(buffer, "txt") + 6, 34);
    strcpy( url, "wget -O data.csv \"https://mars.mipt.ru/data/txt/" );
    strcat( url, txt );
    strcat( url, "\"" );

//  Getting the file
    system(url);
    
//  Trimming the first 20 rows
    fcsv = fopen("data.csv", "r");
    for( int i = 0; i < 20; i++ ) {
        fgets(buffer, 500, fcsv);
    }

//  Extracting the data
    int i = 0;
    while( fgets(buffer, 500, fcsv) ) {
        data[i][2] = NAN;
        sscanf(buffer, "%lf %lf %lf", &data[i][0], &data[i][1], &data[i][2]);
        i++;
    }
    
    fclose(fcsv);
    
//  Printing the first lines
    for( int i = 0; i < 5; i++ ) {
        printf("%lf %lf %lf\n", data[i][0], data[i][1], data[i][2]);
    }
            
    return 0;
}