Fathym Forecast API
- Updated on 01 Jul 2020
- 2 minutes to read
-
Print
-
DarkLight
Fathym Forecast API
Welcome
The Fathym Forecast API is a high-performance RESTful API that can be used to obtain forecasted values for a variety of variables at any set of points in space and time. This document outlines the process of making basic queries.
This document includes the following topics:
- Sample API Interactions
- Request a List of Available Variables
- Request Multiple Variables
- Request a List of Available Maptile Imagery
- Request a Maptile
Sample API Interactions
In each of these examples, the {subscription key} is the one provided by the Azure API Management system.
Request a List of Available Variables
Below is an example using curl to fetch the list of forecast variables. The list of variables is long and growing. Note: The results below are truncated for brevity:
| $ curl -X GET "https://api-prd.fathym.com/api/v0/apivariables" -H "Ocp-Apim-Subscription-Key: {subscription key}" [ { "name": "CategoricalFreezingRain", "doc": "1 if there is freezing rain, 0 otherwise.", "level": "Surface", "units": "boolean" }, { "name": "CategoricalIcePellets", "doc": "1 if there are ice pellets, 0 otherwise.", "level": "Surface", "units": "boolean" }, { "name": "CategoricalRain", "doc": "1 if there is rain, 0 otherwise.", "level": "Surface", "units": "boolean" }, [… SNIP …], { "name": "DewPoint", "doc": "DewPoint at 2 meters", "level": "2Meters", "units": "k" }, [… SNIP …], { "name": "LongWaveRadiation", "level": "Surface", "doc": "downward long wave rad. flux", "units": "W/m2" }, [… SNIP …], { "name": "PrecipitationRate", "doc": "Precipitation Rate (kg/m^2/s)", "level": "Surface", "units": "kg/m^2/s" }, [… SNIP …], { "name": "RoadState", "doc": "Get projected road state (string) based on weather variables", "level": "Surface", "units": "unknown" }, { "name": "RoadTemperature", "doc": "Road Temperature in Kelvin", "level": "Surface", "units": "kelvin" }, [… SNIP …], { "name": "Temperature", "doc": "Temperature (kelvin) at surface", "level": "Surface", "units": "k" }, [… SNIP …], { "name": "WindDirection", "doc": "Wind Direction in degrees (0 is true north)", "level": "10Meters", "units": "degrees" }, { "name": "WindSpeed", "doc": "Wind Speed (m/s)", "level": "10Meters", "units": "m/s" }, [… SNIP …] ] |
Request Multiple Variables
Below is an example of forecasting temperature, precipitation, and road state in Boulder, CO, USA one hour from current time and Denver, CO, USA two hours from current time:
| $ curl "https://fathym-forecast-int.azure-api.net/api/v0/point-query" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: {subscription key}" \ --data-ascii '{"variables":[{"name":"Temperature","level":"Surface"},{"name":"PrecipitationRate","level":"Surface"},{"name":"RoadState","level":"Surface"}],"points": [{"lat":40.021296,"lng":-105.264607,"relativeseconds":3600},{"lat":39.753299,"lng":-104.992361,"relativeseconds":7200}]}' [ { "name": "Temperature", "level": "Surface", "values": [ 301.0521415710449, 298.94481951395676 ] }, { "name": "PrecipitationRate", "level": "Surface", "values": [ 0, 0 ] }, { "name": "RoadState", "level": "Surface", "values": [ "Dry", "Dry" ] } ] |
Notably, this example queries just three variables at just two points in space and time. In general, a query can be for any forecasted variables at any set of points. Querying thousands of points (e.g., along an interstate trucking route, or the locations of a set of retail establishments) is not only possible, but fast — responses in about one second are possible. For the purpose of forecasting along routes, a route is a list of points in space and time.
Request a List of Available Maptile Imagery
The Forecast API delivers maptile imagery based on forecasted data. These images are suitable for display on, for example, Azure Maps. To discover what imagery is currently available, request a maptile manifest.
| $ curl "https://fathym-forecast-int.azure-api.net/api/v0/maptile-manifest " \ -H "Ocp-Apim-Subscription-Key: {subscription key}" { "CloudCover_EntireAtmosphere": [ 1574186400, 1574187300, 1574188200, 1574189100, 1574190000, 1574190900, 1574191800, 1574192700 ], "PrecipitationRate_Surface": [ 1574186400, 1574187300, 1574188200, 1574189100, 1574190000, 1574190900, 1574191800, 1574192700 ], "Temperature_Surface": [ 1574186400, 1574187300, 1574188200, 1574189100, 1574190000, 1574190900, 1574191800, 1574192700 ], "Visibility_Surface": [ 1574186400, 1574187300, 1574188200, 1574189100, 1574190000, 1574190900, 1574191800, 1574192700 ], "Wind_10Meters": [ 1574186400, 1574187300, 1574188200, 1574189100, 1574190000, 1574190900, 1574191800, 1574192700 ] } |
Currently, five variables (layers) are available (as seen in the response above), and for each of those five variables, eight forecast times (approximately every 15 minutes for the next two hours) have available imagery.
Data from the manifest can be used to request maptiles, as seen below.
Request a Maptile
In general, the URL scheme for requesting maptiles is:
/api/v0/maptile-fetch/{variable}/{t}/{z}/{x}/{y}.png
Where:
- {variable} is a variable from the maptile manifest (e.g., "Temperature_Surface")
- {t} is a time from the maptile manifest corresponding to the desired variable (e.g., 1574186400)
- {z}/{x}/{y} are the zoom-level, and x, and y of the desired tile.
This is designed to be convenient to use with mapping software, here is an example of integrating it with Azure Maps in JS in the browser:
| function makeMaptileOptions(layerStr, t) { return { tileUrl: "/api/v0/maptile-fetch/"+layerStr+"/"+t+"/{z}/{x}/{y}.png", opacity: 0.7, tileSize: 256 } } |
Here is an example of accessing a maptile image directly.
Note the parameters "Temperature_Surface" and 1574186400 come from the maptilemanifest as above.
| $ curl "https://fathym-forecast-int.azure-api.net/api/v0/maptilefetch/Temperature_Surface/1574186400/0/0/0.png" \ -H "Ocp-Apim-Subscription-Key: {subscription key}" \ --output tile-0-0-0.png |
Then, ./tile-0-0-0.png is:
At zoom-level `1`, there are four tiles:
 |  |
 |  |
And so on, up to the resolution of available forecast data (approximately zoom level 6 over the continental US and zoom level 3 everywhere else).
.png){kind=logo}