API Documentation
How To:
Using JSON to construct queries is very useful for creating long queries.
It is both easier to make changes, as well as easier to read
Although somewhat complicated, the example below is an excellent example of when you would want to use this method
This example will save 10 images at 10 different timestamps to the current directory
from PIL import ImageThis will save an image for each time stamp in the specified range **Example written in python3**#Library used to save imagesimport urllib#Library used to convert and open URL's#Constructs the JSON query - each line is a variable: value pairquery = { "scale": "-1.6,5", "depth_limit": False, "colormap": "default", "dataset": "glorys3", "showmap": True, "variable": "votemper", "surfacevariable": "none", "time": 207, "quantum": "month", "path": [[47.649768922115356, -52.60316173355579], [45.227624722564485, -48.53822032730579]], "type": "transect", "linearthresh": 200, }#Loops through 10 different timestampsfor t in range(0,10)#In practice, the range would be a valid time formatquery['time'] = t#Sets the time portion of the query#Constructs the URLurl = "http://navigator.oceansdata.ca/plot/?" + urlliv.urlencode({ "query": json.dumps(query),#Converts the query from JSON to encodedURI"dpi" : "72", "size" : "10x7", })#Opens the URL / Sends the API Requestwith closing(urllib.urlopen(url)) as f: img = Image.open(f) images.save("image" + str(t) + ".png", "PNG")#Saves the image as image{#}.png
There are multiple ways to construct an API request in a script. 2 examples are given below.
**Both examples will print 4 lists displaying the depths available for each of the variables specified**
(1) String Replacement
In this example, the 3 curly brace sets "{}" will be replaced by the 3 values given in .format()
These values can be assigned, incremented, or modified to make multiple automated API requests.
import urllib
base_url = "http://navigator.oceansdata.ca/api/v1.0/depth/"
dataset = 'giops_day'
variables = ['votemper', 'vosaline', 'vozocrtx', 'vomecrty']
for variable in variables:
url = ('{}?dataset={}&variable={}'.format(base_url, dataset, variable))
f = urllib.urlopen(url)
output = f.read()
print(output)
**Example written in python3**
(2) String Concatenation
In this example, the variables are incorporated directly in place, and are concatenated together in the order they appear
The text given in quotations "..." are hardcoded strings which will become part of the query
import urllib
dataset = giops_day
variables = [votemper, vosaline, vozocrtx, vomecrty]
for variable in variables:
url = "http://navigator.oceansdata.ca/api/v1.0/depth/?dataset=" + dataset + "&variables=" + variable
f = urllib.urlopen(link)
output = f.read()
print(output)
**Example written in python3**
API Query Documentation
| /api/v1.0/datasets/ |
Will return a list of possible datasets and their corresponding data
| /api/v1.0/datasets/?id |
Will return a list of Dataset names and their corresponding id's
| /api/v1.0/variables/?dataset=<dataset_id>&3d_only&vectors_only&vectors |
example: /api/v1.0/variables/?dataset=giops_day **Only use variables required for your specific request** dataset_id : Dataset to extract data - Can be found using /api/datasets/id 3d_only : When included, ONLY variables with depth will be shown vectors_only : When included, ONLY variables with magnitude will be shown vectors : When included, magnitude components will be included **Boolean: True / False** Will return a list of variables in the specified dataset, this output can be filtered by including keywords in the query
| /api/v1.0/observationvariables/ |
example: /api/v1.0/observationvariables/ Returns a list of the possible observation variables
| /api/v1.0/timestamps/?dataset=<string:dataset> |
example: /api/v1.0/timestamps/?dataset=giops_day <string:dataset> : Dataset id - Can be found using /api/datasets Finds all timestamps associated with a dataset
/api/v1.0/depth/?dataset=<string:dataset_id>&variable=<string:variable>
example: /api/v1.0/depth/?dataset=giops_day&variable=votemper <dataset_id> : id of the desired dataset - Can be found using /api/datasets/id <variable> : Type of data to retrieve - found using /api/variables/?dataset='...' Returns all depths available for that variable in the dataset
| /api/v1.0/scale/<string:dataset>/<string:variable>/<string:scale_min, scale_max>.png |
example: /api/v1.0/scale/giops_day/votemper/-5,30.png <string:dataset> : Dataset id - found using /api/datasets/id <string:variable> : Type of data to retrieve - found using /api/variables/?dataset='...' <string:scale_min,scale_max> : Desired Scale Returns a coloured scale bar using the provided scale
/api/v1.0/range/<string:dataset_id>/<string:variable>/<string:interp>/<string:radius>/<string:neighbours>/<string:projection>/<string:extent>/<string:depth>/<string:time>.json
example: /api/v1.0/data/giops_day/votemper/823/0/63.51801708389351,-56.13861083984375.json <string:interp> : Dataset id - Can be found using /api/v1.0/datasets/?id <string:radius> : Type of data to retrieve - found using /api/v1.0/variables/?dataset='...' <int:neighbours> : Time of data collection <string:dataset_id> : Water Depth - found using /api/v1.0/depth/?dataset='...' <string:Lat,Lon> : Location of the data you want to retrieve **All Components Must be Included** Returns JSON object containing the location, name, units, and value based on the input values
/api/v1.0/data/<string:dataset>/<string:variable>/<string:time>/<string:Depth>/<string:location>.json'
example: /api/v1.0/data/giops_day/votemper/823/0/63.51801708389351,-56.13861083984375.json <string:dataset> : Dataset id - Can be found using /api/v1.0/datasets/?id <string:variable> : Type of data to retrieve - found using /api/v1.0/variables/?dataset='...' <string:time> : Timestamp of data collection <string:Depth> : Water Depth - found using /api/v1.0/depth/?dataset='...' <string:Lat,Lon> : Location of the data you want to retrieve **All Components Must be Included** Returns JSON object containing the location, name, units, and value based on the input values
/api/v1.0/class4/<string:q>/<string:class4_id>/
example: /api/class4/models/class4_20180512_GIOPS_CONCEPTS_2.3_profile/100 <string:q> : forecasts (dates) models (?) <string:class4_id> : ID of the desired class4 - Can be found using /api/v1.0/class4/ Returns in-situ observations with global prediction system estimates
/api/v1.0/drifters/<string:q>/<string:drifter_id>
example: /api/v1.0/drifters/vars/300234063261890/ <string:q> : vars / time (Data Request) <string:drifter_id> : ID of Drifter of Interest - Options can be found using /api/ Vars - Returns a list of Variables applicable to the specified drifter Time - Returns the max and min time of the specified drifter
| /api/v1.0/stats/?query=<string:query> |
example: not working <string:query> = { dataset : Dataset id - found using /api/v1.0/datasets/id variable : Type of data to plot - Options found using /api/v1.0/variables/?dataset='...' time : Time retrieved data was observed / modeled depth : Water Depth - found using /api/v1.0/depth/?dataset='...' area : Selected Area } **Query must be written in JSON and converted to encodedURI** **Not all components of query are required Returns a list of statistical variables associated with the plot selected. This may include variable name, units, min, max, mean, median, and stddev
| /api/v1.0/subset/?query='...' |
example: Click for Example query = { Output Format : File Format Dataset id : id of the desired dataset - found using /api/v1.0/datasets/id Variables : data type ex. temperature - found using /api/v1.0/variables/?dataset='...' Min range : Minimum of bounding box - displayed below Max range : Maximum of bounding box - displayed below time : Data Time Period zip : Takes a value of 1 or 0 [1: create a zip file, 0: do not zip file] } Bounding Box:**Query must be written in JSON and converted to encodedURI** **Not all components of query are required Returns a subset of data based on the criteria provided, this can be in multiple different file formats
| /api/v1.0/plot/?query=<json:query> |
example: Click for Example **MORE DETAILS ABOUT PLOTS CAN BE FOUND HERE <json:query> = { scale : quiver : colormap : area : { u'innerrings': u'polygons' : } bathymetry: True/False - If true, area plots will show bathymetry lines dataset : Dataset id - found using /api/v1.0/datasets/id showarea : If true, the selected area lines will be displayed variable : Type of data to plot - Options can be found in the documentation input section depth : Depth of data to plot (depths available depended on dataset) plottitle : Title of Plot (Default if blank) quantum : (year, month, day, hour) showmap : Include a map of the plots location on the map station : Coordinates of the point/line/area/etc time : Time retrieved data was gathered/modeled contour : { variable : hatch : levels : colormap : legend : } projection: radius : type : Plot Type (Check Navigator for Possible options) } Plot Types - map, transect, timeseries, ts, sound, profile, hovmoller, observation, drifter, class4, stick **Query must be written in JSON and converted to encodedURI** **Not all components of query are required This query is used to create plots of all types, as well as to create some file types including csv
/api/v1.0/colors/
Returns a list of colours for use in colour maps
/api/v1.0/colormaps/
Returns a list of colourmaps
/api/v1.0/colormaps.png
Returns image of colourmap example configurations
| /api/v1.0/<string:q>/ |
example: /api/v1.0/lines/ <string:q> : Zone Type Can be (points,lines, areas, or class4) Returns predefined points / lines / areas / class4's
| /api/v1.0/<string:q>/<string:q_id>.json' |
example: /api/v1.0/drifters/meta.json <string:q> : Type of Data (areas, class4, drifters, observation) <string:q_id> : metafile name drifters: meta, observation: meta Returns a list of all the objects of the selected type
| /api/v1.0/<string:q>/<string:projection>/<int:resolution>/<string:extent>/<string:file_id>.json |
example: /api/v1.0/class4/EPSG:3857/9784/-15618972,1596939,4487023,12369057/class4_20180510_GIOPS_CONCEPTS_2.3_profile.json --At this time, only the class4 option is available <string:q> : Type of data (points, lines, areas, class4, drifters, observations) <string:projection> : Current projection of the map (EPSG:3857, EPSG:32661, EPSG:3031) <int:resolution> : Current zoom level of the map <string:extent> : The current bounds of the map view <string:file_id> : Class 4 file ID **All Components Must be Included** **Used Primarily by WebPage** At this time will return a list of class4's and their data
Input Options
Available Datasets
Plot API Information
This page provides different variables that can be included in your plot queries. Some of them are required while others are optional and are used to achieve the described task outlined next to them. **Class4's do not use this api request to create plots
| VARIABLE | TYPE | DESCRIPTION |
| dataset | String | Dataset ID |
| names | List | Sometimes [lat,lon] |
| plotTitle | String | Blank unless a custom plot title is wanted |
| quantum | String | "day", "month"... |
| showmap | Bool | true if map of selected point is wanted |
| station | String | lat,lon,null |
| time | String | Time given in ISO8601 Extended |
| endtime | String | The end time for a time ranged plot - Given in ISO8601 extended format |
| type | String | point |
| variable | String | variable id (Additional variables can be added by seperating with a comma) |
EXAMPLE:
query = {
"dataset": "giops_day",
"names":["50,-48"],
"plotTitle":"",
"quantum":"day",
"showmap":true,
"station":[[50,-48]],
"time":'2018-08-09T00:00+00:00',
"type":"profile",
"variable":"votemper"
}
| VARIABLE | TYPE | DESCRIPTION |
| dataset | String | Dataset Id |
| colormap | String | The desired colourmap, typically set to 'default' |
| depth_limit | Bool | ? |
| linearthresh | Integer | Depth where graph becomes logarithmic, default is 200 |
| path | 2D list | Points in Transect [[lat,lon],[lat,lon],...] |
| plotTitle | String | Blank unless custom plot title is wanted |
| quantum | String | ex: "day", "month", ... |
| scale | String - Comma separated |
Scale of the color range: "auto" for a scale determined by the data "min,max" for manual where min and max are the extremes of the scale |
| selectedPlot | String - comma separated | Used to decided which plots to show when velocity is selected 1 - Plot shown 0 - Plot not included "magnitude, parallel, perpendicular": these are replaced with 1's or 0's to indicate which plots are shown ex: "0,1,1" shows the parallel and perpendicular plots, but does not included magnitude Parallel and Perpendicular is in reference to the transect line |
| showmap | Bool | true - map of transect is displayed false - only the data plot(s) is displayed |
| surfacevariable | String | Displays an additional plot showing the data of the variable at the surface along the transect |
| time | String - ISO8601 Extended | The time and date of the data wanted |
| type | String | The type of plot 'transect' for transect plots |
| variable | String | Variable ID |
EXAMPLE:
query = {
"dataset": "giops_day",
"colormap":"default",
"depth_limit":false,
"linearthresh":200,
"path":[[40,-50],[50,45]],
"plotTitle":"",
"quantum":"day",
"showmap":true,
"scale":"-5,30"
"selectedPlots":"1,1,0"
"time":'2018-08-09T00:00+00:00',
"type":"transect",
"variable":"vosaline",
"surfacevariable":"votemper"
}
| VARIABLE | TYPE | DESCRIPTION |
|
area : { "innerrings", "name", "polygons" } |
[{List, String, 3D List}] |
contains list of innerrings, name, and polygons... innerrings: ? name: ? polygons: list of lat,lon points of the area selected ex: [{"innerrings":[],"name":"","polygons":[[[55,-48],[55,-39],[45,-30],[45,-50]]]}] |
| bathymetry | Bool | True if bathymetry lines are wanted, false otherwise |
| colormap | String | which colormap should be used to display the variable use 'default' for the default map |
|
contour : { "colormap", "hatch", "legend", "levels", "variable" } |
JSON: { String Bool Bool String String } |
colormap: the desired colourmap, 'default' sets the colormap to the default hatch: Will show hatching legend: Shows legend of the value of the countours shown levels: "first,second,third" each is set to the variable value in which the contour should be set, 'auto' will auto set the values variable: The variable that should be contoured (does not have to be the variable of the plot) "none" if no contours **A contour variable must be selected for these to take effect |
| dataset | String | Dataset ID |
| depth | Integer | Index of depth layer. Click here for depth layer information |
| interp | String | Desired Interpolation ex. 'gaussian' |
| neighbours | String | Selects the maximum number of points to be included in the interpolation |
| projection | String | Projection used to superimpose the earth on a flat surface Options: 'EPSG:3857' - Global (default projection) 'EPSG:32661' - Artic 'EPSG:3031' - Antarctic |
| scale | String | The color scale for the map, 'auto' will pick a scale based on the value of the variable in the area selected |
| radius | Integer | Limits the interpolation to a specific raidus around the point |
|
'quiver':{ 'colormap', 'magnitude', 'variable' } |
{String, String, String} | Quivers are shown when a quiver variable is selected, for example, you can select quivers to show the velocity of the water around the entire area colormap: Colourmap to use when 'colour' is selected for magnitude magnitude: The method used to show the magnitude of the variable ('lenght', or 'colour') variable: The variable to show quivers for, "none" to display quivers |
| showarea | Bool | bool - If true, a map of the selected area box will be shown |
| time | String | The time to show data for in ISO8601 extended format Availble times for each dataset can be found here |
| type | String | The type of plot to be created 'map' for area plots |
| variable | String | The Variable to display on the area |
EXAMPLE:
query = {
"area":[{"innerrings":[],"name":"", "polygons":[[[50,-49],[45,-57],[50,-59],[50,-49]]]}],
"bathymetry":true,
"colormap":"default",
"contour":{"colormap":"default","hatch":false,"legend":true,"levels":"auto","variable":"none"},
"dataset":"giops_day",
"depth":0,
"interp":"gaussian",
"neighbours":10,
"projection":"EPSG:3857",
"quiver":{"colormap":"default","magnitude":"length","variable":"none"},
"radius":25,
"scale":"auto",
"showarea":true,
"time":'2018-08-9T00:00+00:00',
"type":"map",
"variable":"votemper"
}
| VARIABLE | TYPE | DESCRIPTION |
| buoyvariable | List of Strings | ["sst"] ? |
| dataset | String | Dataset Id |
| depth | Integer | Index of Depth Variable |
| drifter | String | Drifter ID |
| latlon | Bool | default is false |
| quantum | String | "day", "month", ... |
| showmap | Bool | If true shows the map of the selected area |
| type | String | 'drifters' for drifters |
| variable | String | Variable ID |
EXAMPLE:
query = {
"buoyvariable":["sst"],
"dataset":"giops_day",
"depth":0,
"drifter":["300234063263870"],
"endtime":"2017-04-12T10:30:00.000Z",
"latlon":false,
"quantum":"day",
"showmap":true,
"starttime":
"2016-05-17T15:30:48.000Z",
"type":"drifter",
"variable":["votemper"]
}