MAOAM API

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

• How to construct query
• Possible values
• Answer example 1
• Answer example 2
• Answer example 3
• Working examples
• Python
• PHP
• Fortran 77
• Fortran 90
• C / C++

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:

Variable	Name	Value	Description
api	API	1	Always should be set to 1.
var	Variable	u	Zonal velocities, m/s
		v	Meridional velocities, m/s
		uv	Absolute horizontal velocities, m/s
		w	Vertical velocities, m/s
		T	Temperature, K
		Ts	Surface temperature, K
		p	Pressure, Pa
		h	Height, km
		ps	Surface pressure, Pa
		rho	Density, kg/m3
		h2og	H2O vapor, kg/m2
		h2og_pr	H2O vapor, Pr.mkm
		h2og_st	H2O vapor on 6 mbar, kg/m2
		h2og_mix	H2O vapor mix. ratio, mg/kg
		h2og_ppmv	H2O vapor mix. ratio, ppmv
		h2oim	H2O ice, kg/m2
		h2oim_pr	H2O ice, Pr.mkm
		h2oim_op	H2O ice, opacity in 825 cm-1
		h2oim_mix	H2O ice mix. ratio, mg/kg
		h2oin	H2O ice number density, cm-3
		h2oir	H2O ice particle radius, mkm
		gdq_mix	Dust mix. ratio (given), mg/kg
		gdq_op	Dust opacity (given), opacity in 1075 cm-1
		dustn	Dust number density (given), cm-3
		h2ois	Surface H2O ice, kg/m2
		dm	CO2 ice cloud mass concentration, g/m3
		hcap	Surface CO2 ice, kg/m2
		dipre	Delta pressure, Pa
		dih	Cell heights, m
		surf	Cell areas, km2
time_from	from Ls	0 - 360	Should be less than or equal to time_to.
time_to	to Ls		Should be greater than or equal to time_from.
time_range	Ls range type	range	Range
		ave	Average
		sum	Summing
		max	Maximum
		min	Minimum
hour_from	from local Hour	0 - 23	Should be less than or equal to hour_to.
hour_to	to local Hour		Should be greater than or equal to hour_from.
hour_range	Hour range type, should be equal to time_range	range	Range
		ave	Average
		sum	Summing
		max	Maximum
		min	Minimum
lon_from	from Longitude	-180 - 180	Should be less than or equal to lon_to.
lon_to	to Longitude		Should be greater than or equal to lon_from.
lon_range	Longitude range type	range	Range
		ave	Average
		sum	Summing
		max	Maximum
		min	Minimum
lat_from	from Latitude	-90 - 90	Should be less than or equal to lat_to.
lat_to	to Latitude		Should be greater than or equal to lat_from.
lat_range	Latitude range type	range	Range
		ave	Average
		sum	Summing
		max	Maximum
		min	Minimum
altype	Altitude type	h	Height above surface
		ho	Height above "sea level"
		p	Pressure
		lev	Hybrid model levels
lev_from	from Level	0 - 160 for altype = [ h, ho ], 0.0000036 - 607 for altype = [ p, lev ]	Should be less than or equal to lev_to.
lev_to	to Level		Should be greater than or equal to lev_from.
lev_range	Level range type	range	Range
		ave	Average
		sum	Summing
		max	Maximum
		min	Minimum
version	GCM version	1.104	Water 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.110	Martian 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.114	Martian 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;
}