This is actual version on 2019-06-26. If something doesn't work, please contact Artem Vesnin (artem_vesnin@iszf.irk.ru)
General info
API for SIMuRG use JSON-format both for queries/requests and its replies. API for SIMuRG is under development. Please, check method names by request:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "get_list_of_methods", # This method
# provides you list of our methods
"args": {} # It doesn't need any arguments
}
)
methods = rq.json()
print(methods)What kind of result you should get:
['', 'check', 'delete', 'create_map','create_series', 'get_site', 'get_data_count', 'get_list_of_methods', 'get_limbo', 'get_all_gec', 'get_method_schema', 'get_series_data','get_map_times', 'get_map_data_by_time', 'get_db_info', 'get_day_info','get_system_load', 'add_event']Your result can be slightly different, but the whole picture should be the same.
Of course, you don't know the inner structure of new for you methods. Parameters for a method can be requested:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "get_method_schema",
# This method provides you information
# about all of our methods
"args": {"name": "get_method_schema"}
# Here you write chosen method name.
# For example, "get_method_schema
}
)
method_schema_schema = rq.json()
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "get_method_schema",
# This method provides you information
# about all of our methods
"args": {"name": "check"}
# Here you write chosen method name.
# For example, "check"
}
)
check_schema = rq.json()
print(method_schema_schema)
print(check_schema)What kind of result you should get:
{'schema': {'type': 'object', 'properties': {'name': {'type': 'string'}}, 'required': ['name']}}
{'schema': {'type': 'object', 'properties': {'email': {'type': 'string'}}, 'required': ['email']}}How you should read and understand this info on method_schema example:
method_schema =
{
"schema":
{"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}
}Keys of method_schema["schema"]["properties"] are the parametes that could be passed when request is made. method_schema["schema"]["required"] list of parameters those must specified.
Usage cases
After one can understand how SIMuRG api works, some practically useful examples are shown.
Sites and coordinates are requested as follows:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "get_site", "args": {}}
# This method provides you information
# about GNSS receivers, that are in SIMuRG database.
# It doesn't need any arguments
)
sites = rq.json()
for site, coords in sites.items():
print(site, coords) As the results, one should get long list of receivers names with its coordinates.
Also, you can do user requests for Ionospheric maps or Ionospheric series as on web-site. Ionospheric maps request can be retrieved:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "create_map", # This method
# creates maps request
"args": {"email": "your@mail.com", # Here you write your e-mail
# All information about
# your request would be attached to this one.
# Required parameter
"begin": "2015-06-22 00:00", # Here you write
# the beginning of interesting time interval.
# Required parameter
"end":"2015-06-22 01:00", # Here you write
# the ending of interesting time interval.
# Required parameter
"coordinates":{"minlat":-90, "maxlat": 90,
"minlon": -180, "maxlon": 180},
# Here you write
# the left lower and the right top corners of the map
# Required parameter
"flags":{
"create_plots": True,
# Here you write whether you want or not
# to create plots
# Not required parameter
"create_movie": True
# Here you write whether you want or not
# to create movie
# Not required parameter
},
"options":{
# Here you customize your query
"product_type":"ROTI"
# Here you select what product you want to get
# Not required parameter
"cmap": "jet",
# Here you select what colormap you want to get
# Not required parameter
"format": "HDF5",
# Here you select data's format you want to get
# Not required parameter
"movie_quality": "high",
# Here you select quality of movie you want to get
# Not required parameter
"grid": "subionospheric points",
# Here you select what type of grid you want to get
# Not required parameter
"subsolar": True,
# Here you select whether you want or not to create
# solar terminator movement
# Not required parameter
"mageq": True
# Here you select whether you want or not to create
# magnetic equator lines
# Not required parameter
}
}
}
)
queries = rq.json()
for query in queries:
print(query) That's how this query would look like on web. The main settings part:
The additional part:
If one would made a mistake (wrong value of parameters, misspelling , e.t.c.) or there were failed query before,one would get errors message after all. For example:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "create_map", # This method
# creates maps request
"args": {"email": "your@mail.com",
"begin": "2015-06-22 00:00",
"end":"2015-06-22 01:00",
"cordinates":{"minlat":-90, "maxlat": 90,
"minlon": -180, "maxlon": -180}
# "cordinates" is the mistake
# It's required parameter,
# you don't define it with this spelling
# You should write "coordinates"
# instead of "cordinates" here.
}
}
)
queries = rq.json()
print(queries) That's what you would get:
{'errors': ["'coordinates' is a required property"]}After you have made a query, you can retrieve it by the code:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "check", # This method
# checks queries
"args": {"email": "your@mail.com"}
# Here you write your e-mail
# All information is attached to this one.
# Required parameter
}
)
queries = rq.json()
for query in queries:
print(query) As the result you can get something like that:
{'id': '5d12d262b6326a7fed9394fd', 'created': '2019-06-26 02:03:14+00:00', 'begin': '2015-06-22 00:00', 'end': '2015-06-22 01:00', 'type': 'series', 'product_type': '2-10 minute TEC variations', 'status': 'done', 'message': '', 'progress': {'total': 1, 'processing': [1, 0]}, 'paths': {'data': '/media/storage/simurg/simurg/dtec_2_10_2015_173_edae.h5', 'image': '/media/storage/simurg/simurg/dtec_2_10_2015_173_edae.png', 'zippng': '/media/storage/simurg/simurg/dtec_2_10_2015_173_edae.zip'}, 'site': 'irkj'}
{'id': '5d12d562b6326a7fed9394fe', 'created': '2019-06-26 02:16:02+00:00', 'begin': '2015-06-22 00:00', 'end': '2015-06-22 01:00', 'type': 'map', 'product_type': 'ROTI', 'status': 'done', 'message': '', 'progress': {'total': 5025, 'processing': [3677, 1348]}, 'paths': {'data': '/media/storage/simurg/simurg/roti_2015_173_-90_90_N_-180_180_E_8852.h5'}, 'coordinates': {'minlat': -90, 'maxlat': 90, 'minlon': -180, 'maxlon': 180}, 'site': 5025}
{'id': '5d13390ea99795241786ecba', 'created': '2019-06-26 09:21:18+00:00', 'begin': '2015-06-22 00:00', 'end': '2015-06-22 01:00', 'type': 'map', 'product_type': 'ROTI', 'status': 'plot', 'message': '', 'progress': {'total': 5025, 'processing': [3677, 1348]}, 'paths': {}, 'coordinates': {'minlat': -90, 'maxlat': 90, 'minlon': -180, 'maxlon': 180}, 'site': 5025}Here you can see results of the query on web-site:
For more info about how to work on web-site read here in understanding map query results part:
SIMuRG how to web
Ionospheric series request can be retrieved:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "create_series",
"args": {"email": "your@mail.com",
# Here you write your e-mail
# All information would be attached to this one.
# Required parameter
"begin": "2015-06-22 00:00",
# Here you write
# the beginning of interesting time interval.
# Required parameter
"end":"2015-06-22 01:00",
# Here you write
# the ending of interesting time interval.
# Required parameter
"site": "irkj" # Here you write
# the name of interesting site/receiver.
# Required parameter
}
}
)
queries = rq.json()
for query in queries:
print(query) That's how this query would look like on web:
Here you can see results of the query on web-site:
For more info about how to work on web-site read here in understanding series query results part:
SIMuRG how to web
That's how you can get Global electron content series:
import json
import requests
rq = requests.post("https://simurg.iszf.irk.ru/api",
json={"method": "get_all_gec",
# This method takes GEC data
# from different computation stations
"args": {}
# It doesn't need any arguments
}
)
gecs = rq.json()
print('Retrieved {}'.format(list(gecs.keys())))