Intro

By 7425wpczar,

INTRO

You can use our test environment or interactive web console like Postman to test our API.

While you are testing, here are some helpful pointers to assist your debugging:

  • Ensure you are always using the POST method for each call.
  • Always use your Subscription key

API REFERENCE

The API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

AUTHENTICATION

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Earth Networks Enterprise Portal. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

 

 

Daily Forecast

By 7425wpczar,

DESCRIPTION

The Earth Networks ENCast City 10 Day‐Night Forecast Feed provides a descriptive day and night period forecast covering the next 10 days. The day period of the forecast is considered to be 7am‐7pm local time, while the night period of the forecast is considered to be the hours straddling the date change from 7 pm to 7 am local time. This forecast will be available for 2.6 million cities across the entire globe and will be available in multiple languages.

REQUEST URL

https://earthnetworks.azure-api.net/data/forecasts/v1/daily?locationtype={locationtype}&location={location}[&verbose][&cultureInfo]

 

REQUEST PARAMETERS

Name Type Description
locationtype string “city” or “latitudelongitude”
location string a valid cityId or valid latitude/longitude. For the cityId use “Location Search v2” API call.

 

REQUEST HEADERS

Name Type Description
Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

Hourly Forecast

By 7425wpczar,

Description:

The hourly forecast call provides hourly forecast data by lat/long. The data itself is updated once an hour at around 20 minutes after the hour. The forecast includes a description of the conditions for that hour. The description will be translated into additional languages according to the culture passed in.

Request URL:

https://earthnetworks.azure-api.net/getHourly6DayForecast/data/forecasts/v1/hourly?location={location}&locationtype={locationtype}[&verbose][&units][&metadata][&offset][&length]

Limitations:

The latitude and longitude location type will only provide data if there is a city within 40 miles of the latitude and longitude requested.

 

Request parameters:

locationtype string „city“ or “latitudelongitude”
latitude string  
longitude string  
location string a valid EN „CityId“ from Search Location or longitude,latitude

Optional parameters:

verbose (optional) boolean true, false
units string the units determine the return type for the system. Currently the following values are supported: english = all units are returned in English units metric = all units are returned Metric units
metadata boolean determines if metadata should be returned in the response. Metadata can be used to describe the data returned by the feed
offset Number determines the starting period to return. A value of 0 will return the current UTC hour. This means if the forecast hasn’t updated yet for the current hour then it may mean that only 143 periods of forecast data are returned. Default is 0
length number determines the number of forecast periods to return. This value can be between 1 and 144. If there is less data then the value, all the data will be returned. Default is 144

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Air Quality Forecast

By 7425wpczar,

Description:

The AirQuality feed provides Air Quality Index and discussion data for a city or a lat/long.

Request URL:

https://earthnetworks.azure-api.net/getAirQuality/data/aqi/v1/daily

Request parameters:

locationtype string “latitudelongitude”
latitude string  
longitude string  

Optional parameters:

verbose (optional) boolean true, false
cultureInfo (optional) string en-us, es-es, fr-fr, pt-pt

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Google Map Layers

By 7425wpczar,

For displaying map tiles over Google Maps you must first make a Google Account and get an API Key from the Google API Console (https://developers.google.com/maps/documentation/javascript/get-api-key). After the API Key is obtained you can use the following approach for displaying the tiles:

1) Load the Google Maps Javascript API, substitute YOUR_API_KEY in the code below with your API key:

<script async defer src=”https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap” type=”text/javascript”></script>

2) Get current time slot value t from metadata call (the subscriptionKey key variable is your Earth Networks subscription key)


var t;
var subscriptionKey;

    var json = (function() {
        var json = null;
        $.ajax({
           'async': false,
           'global': false,
            'url': "https://earthnetworks.azure-api.net/maps/overlays/v2/metadata?lid=Radar.NA.LoAlt&subscription-key=" + subscriptionKey,
            'dataType': "json",
            'success': function(data) {
                json = data;
            }
        });
        return json;
    })();
    t = json.Result.LatestSlot;

3) Initiate the map with the following code where the t variable is the current time slot value got from metadata call


function initMap() {
   var map = new google.maps.Map(document.getElementById('map'), {
        zoom: 6,
        center: { lat: 37.514938, lng: -99.337306 }
   });
   var imageMapType = new google.maps.ImageMapType({
        getTileUrl: function (coord, zoom) {
            return "https://earthnetworks.azure-api.net/maps/overlays/tile?x=" + coord.x + "&y=" + coord.y + "&z=" + zoom + "&t=" + t + "&lid=pulserad&epsg=3857&subscription-key=" + subscriptionKey
        },
        tileSize: new google.maps.Size(256, 256)
   });
   map.overlayMapTypes.push(imageMapType);
}

Location Search

By 7425wpczar,

Description:

The location search provides the details for a single specific station similar to station list.

Request URL:

https://earthnetworks.azure-api.net/getLocations/data/locations/v2/location?searchString={searchString} [&cultureInfo]

Request parameters:

searchString string This variable can be any one of the following: (1) a zip code, or (2) a city name, or (3) a combination of zip code and city name separated by a comma, or (4) a city ID

Optional parameters:

cultureInfo (optional) string en-us, es-es
locationtype string “latitudelongitude”
location string a valid latitude/longitude
maxresults number  

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Radar and Maps

By 7425wpczar,

Description:

Radar and Maps provides URLs for Satellite, Radar, and Temperature maps as well as other various images of the United States, Puerto Rico and the Virgin Islands.

Maps can be provided in standard (373×272) size or enlarged (640×480) size. Earth Networks provides the capability for end users to navigate between maps (traveling N, S, E, W), and to zoom in and out between local, regional, and national maps. Navigation XML can be optionally added to provide a way to create an interface for your users to pan and zoom throughout the maps.

An animation option allows for a number of time-sequential images to be returned. Cycling through these images provides for a small animation loop. Note that images should be used in the same order as they are returned in the XML. Radar and Maps provide specific information for the given zip code or city code RequestType “RadarAndMaps” or 5.

Request URL:

https://earthnetworks.azure-api.net/getRadarsandMaps?RequestType=5&ZipCode=<zip code>&PostalCode=<postalcode>&CityCode=<citycode>[&MapType=<Map Type>][&Zoom=<Zoom>][&Animate=<Animate>][&Navigation=<Navigation>][&Enlarge=<Enlarge>]&subscription-key=<Your subscription key>

Request parameters:

RequestType string 5 or RadarAndMaps

Optionaly required parameters:

ZipCode A valid 5-digit zip code or 9- digit zip code

The zip code for the area that you wish to have data returned for.

We now support 9-digit zipcodes.

For example, 20171, 20171-

1234 both of these formats will be accepted if passed in

PostalCode 5-digit number

A series of letters and/or digits appended to a postal address for the purpose of sorting mail.

CityCode integer

The city code that identifies this location. This is the value that will be used in other calls to identify a specific list of stations for the provided city code

Optional parameters:

MapType

1 = Doppler Radar

2 = Infrared Satellite

3 = Satellite/Radar

4 = Visible Satellite

5 = Current Temperatures

6 = High Temps Today

7 = High Temps Tomorrow

8 = Wind Chill/Heat Index

9 = Wind Speed/Direction

10 = Topography

The type of map to retrieve.

Not all map types are available in all zip codes, such as Puerto Rico.

Zoom (Only for US)

1 = Local (closest view)

2 = Metro

3 = Regional

4 = National

8 = Hawaii

10 = Alaska

12 = Puerto Rico/Virgin Islands

The zoom level for the map

to retrieve. If you desire a map of Hawaii, Alaska, Puerto Rico or the Virgin Islands, be sure to specify the corresponding Zoom level. Not all map types are available in all zoom levels.

Animate

0 or blank = Show only the

current map URL

1 = Show a list of URLs for animation loops

Provides the animation image list, rather than a single image XML in the response.
Navigation An XML Node containing an ID attribute as well as two sub-nodes. Contains information about the current category ID and has sub-nodes to indicate the next and previous categories.
Enlarge

0 or blank = Show standard

size map URL(s)

1 = Show large image URL(s)

when 0 is entered standard is returned 363×272 images in the XML response. When 1 is entered enlarged is returned 640×480 images

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Real Time Weather Observations V4

By 7425wpczar,

Description:

The Earth Networks Observation Data Feed will provide you with a set of current condition data based on the location or station id requested. For Location the logic is in place to always return the best observation for the location requested based on age, distance and accuracy. For station id the logic is to always return observations for that station id.

Request URL for latitudelongitude:

https://earthnetworks.azure- api.net/data/observations/v4/current?[&cultureinfo][&locationtype][&location][&units][&r uledetails][&verbose][&metadata][&includeqcflags]

Request URL for stationid:

https://earthnetworks.azure- api.net/data/observations/v4/current?[&cultureinfo][&locationtype][&stationid][&providerid][&units][&ruledetails][&verbose][&metadata][&includeqcflags]

Request parameters:

locationtype string „Latitudelongitude“ or „stationid“
location
(if location type is „latitudelongitude“)
string Latitude/Longitude in format: <Latitude>,<Longitude>
providerid (if  locationtype is „stationid“) String Must be valid ID from Search Weather Station API for station

Optional parameters:

verbose boolean

Abbreviations (false)

or long variable names (true)

true, false
units string Metric or English units “metric” or “English”
metadata boolean

determines whether

or not to return metadata

“false” or “true”
cultureinfo string Language “en-en”, “es-es”
ruledetails boolean

determines whether

or not to display explanation of rollover logic

“false” or “true”
includeqcflags boolean provides qc value for filtered measurements “false” or “true”

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Real Time Weather Observations V3

By 7425wpczar,

Description:

The Earth Networks Observation Data Feed will provide you with a set of current condition data based on the location or station id requested. For Location the logic is in place to always return the best observation for the location requested based on age, distance and accuracy. For station id the logic is to always return observations for that station id.

Request URL:

https://earthnetworks.azure-api.net/data/observations/v3/current?[&locationtype][&location][&verbose]

v3 Parameters for Latitude/Longitude:

Request parameters:

Parameter
Name
Description Input options Default
location Latitude and Longitude Coordinates Must be valid Latitude/Longitude in format: “<Latitude>,<Longitude>” N/A

Optional parameters:

Parameter
Name
Description Input options Default
units Metric or English units “metric” or “english” “metric”
cultureinfo Language “en-en” (English), “es-es” (Spanish) “en-en”
verbose Abbreviations (false) or long variable names (true) “false” or “true” “false”

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

v3 Parameters for StationId:

Request parameters:

Parameter
Name
Description Input options Default
providerid Provider the station is part of Must be validID from Search Weather StationAPI for station N/A
stationid Identifier forstation Must be validID from Search Weather StationAPI for station N/A

Optional parameters:

Parameter
Name
Description Input options Default
units Metric or English units “metric” or “english” “metric”
cultureinfo Language “en-en” (English), “es-es” (Spanish) “en-en”
verbose Abbreviations (false) or long variable names (true) “false” or “true” “false”

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

Observation Variables:

The table below outlines the Observation variables contained within the Observation data feed. It also defines the units, format, min/max values, and precision for each variable.

Please note that extensive quality control measures of the data will be implemented to ensure that data values are reasonable. While rare, it is possible that data may occasionally be missing in the Observation Data Feed. If the data is missing, it will be saved as “Null”. A null space is defined as being this: Null = ‘ ‘.

Real Time Weather Observations V1

By 7425wpczar,

Description:

The Earth Networks Observation Data Feed will provide you with a set of current condition data based on the location or station id requested. For Location the logic is in place to always return the best observation for the location requested based on age, distance and accuracy. For station id the logic is to always return observations for that station id.

Request URL for latitudelongitude:

https://earthnetworks.azure-api.net/data/observations/v1/current?location=<location>&locationtype=latitudelongitude&units=<units>&cultureinfo=<cultureinfo>&verbose=<verbose>&subscription-key=<Your subscription key>

Request URL for stationid:

https://earthnetworks.azure-api.net/data/observations/v1/current?providerid=<providerid>&stationid=<stationid>&units=<units>&cultureinfo=<cultureinfo>&verbose=<verbose>&subscription-key=<Your subscription key>

Request parameters:

locationtype string „Latitudelongitude“ or „stationid“
location
(if location type is „latitudelongitude“)
string Latitude/Longitude in format: <Latitude>,<Longitude>
providerid (if  locationtype is „stationid“) String Must be valid ID from Search Weather Station API for station

Optional parameters:

verbose boolean

Abbreviations (false)

or long variable names (true)

true, false
units string Metric or English units “metric” or “English”
cultureinfo string Language “en-en”, “es-es”

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Search Weather Station

By 7425wpczar,

Description:

The stations call provides access to the station list and allows for the entry of optional parameters to make a bounding box to get a list of stations within that area.

Request URL:

https://earthnetworks.azure-api.net/getStationList/data/locations/v3/stationlist?latitude=39.1833&longitude=-77.2667&verbose=true&subscription-key=<Your subscription key>

Request parameters:

latitude string  
longitude string  
location string „CityId“ from Search Location

Optional parameters:

verbose boolean true, false

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Sky Conditions Icon V1

By 7425wpczar,

Description:

This call returns a complete set of icons listed in order of icon code (for either lunar or forecast, by request). When providing Icons for depicting sky cover for current conditions the response shall check the local sunrise/sunset time in order to determine whether to return a day or night conditions icon value.

Request URL:

https://earthnetworks.azure-api.net/getSkyConditionIcons/resources/v1/icons?iconSet={iconSet}

Request parameters:

iconSet string choice of whether to view lunar icons or forecast icons lunar: returns lunar icons forecast: returns forecast icons

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Sky Conditions Icon V3

By 7425wpczar,

Description:

This call returns a complete set of icons listed in order of icon code (for either lunar or forecast, by request). When providing Earth Networks icons for depicting sky cover for current conditions the response shall check the local sunrise/sunset time in order to determine whether to return a day or night conditions icon value.

Request URL:

https://earthnetworks.azure-api.net/getSkyConditionIcons/resources/v3/icons?iconSet={iconSet}&iconSize={iconsize}

Request parameters:

iconSet string choice of whether to view lunar icons or forecast icons lunar: returns lunar icons forecast: returns forecast icons
iconsize string choice of icon size
forecast returns 52×40, lunar returns 160×160

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Station List

By 7425wpczar,

Desciption:

The stations call provides access to the entire station list. You should only use stations with a provider ID of 3, 4, 10 or 17. Adds optional display flag to allow manual setting to determine whether or not to use the station data.

3 = Earth Networks
4 = METAR
10 = CMAN
17 = SYNOP

Request URL:

https://earthnetworks.azure-api.net/data/locations/v2/stationlist

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

Sunrise and Sunset Times

By 7425wpczar,

Description:

Sunrise and Sunset provides accurate sunrise and sunset times based on latitude and longitude. Default behavior when optional parameters NumDays, ShowSunrise and ShowSunset are omitted is to display both sunrise and sunset data for seven days beginning with the current day.

Request URL:

https://earthnetworks.azure-api.net/getAlmanacData/data/almanac/v1?locationtype=latitudelongitude&location=39,-77&verbose=true&days=2

Request parameters:

locationtype string „city“ or “latitudelongitude”
location string „CityId“ from Search Location or Longitude,Latitude

Optional parameters:

days number number of days you want data for. The default is 1 meaning only the current day. The number of days includes the current day and any subsequent days in local time (max:10)
verbose (optional) boolean true, false
cultureInfo (optional) string en-us, es-es

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

Limitations:

Days must be < = 10

Ultraviolet Index

By 7425wpczar,

Description:

The UV feed provides UV Index data for a lat/long

Request URL:

https://earthnetworks.azure-api.net/getUltraviolet/data/uv/v1

Request parameters:

locationtype string „city“ or “latitudelongitude”
location string a valid EN „CityId“ from Search Location, or Longitude,Latitude

Optional parameters:

verbose (optional) boolean true, false

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.

 

US Alerts

By 7425wpczar,

Description:

The Alerts request provides up-to-the-minute NWS US weather alerts. Only currently active alerts are returned based on the LatLong entered.

Dangerous Thunderstorm Alert is a part of US Alert API and it is a proprietary and more granular alert than the National Weather Service.

Request URL:

https://earthnetworks.azure-api.net/getPublishedAlerts/data/alerts/v1/alerts?locationtype={locationtype}&location={location}[&cultureInfo][&verbose]

Request parameters:

locationtype string „city“ or “latitudelongitude”
location string a valid EN „CityId“ from Search Location, or Longitude,Latitude

Optional parameters:

cultureInfo string choice of language: en-us, es-es
verbose (optional) boolean true, false

Request headers:

Ocp-Apim-Subscription-Key string Subscription key which provides access to this API. Found in your Profile.