by nshipes on Mar 08, 2012
We released the initial version of our Aeris JavaScript SDK, which is the first toolkit publicly available as part of our Aeris Web product line. Last month we previewed the SDK and highlighted many of the major features included with it. Also be sure to check out our documentation and pre-built widgets for the SDK from our Developer Center.
The following is a run-down of the primary features currently included with the initial version of the Aeris Weather JavaScript SDK.
Widgets
One of the best features of the Aeris JavaScript SDK is its support for quickly creating weather widgets. As we previewed last month, the SDK already comes with a library of pre-built widgets for you to instantly includes on your web site or within your web applications. These widgets are extremely flexible, allowing you to customize the styles simply by overriding the default CSS styles, or allowing you to define a new HTML template altogether. In our preview post and current documentation, we describe how our widgets have utilized Handlebars JS as its templating engine to offer a very fast and flexible platform for widget generation.
Customizing the Pre-Built Widgets
On our own HAMweather site we have included some of these pre-built widgets from the SDK, such as the current conditions widget (Aeris.widgets.CurrentsCompact) in our site’s main navigation bar and the nearby weather conditions (Aeris.widgets.NearbyWeather) displayed on our home page. The first thing you’ll notice is these don’t look the same as the default pre-built widgets. We’ve simply modified the default CSS styles for our own implementation, and for the current conditions in the navigation, we’ve provided a completely new HTML template.
To demonstrate how easy it is to customize these widgets with a different template, below is an example of how we are setting up the widget in our site’s navigation bar:
var currentsTop = new Aeris.widgets.CurrentsCompact($('#header ul.top-elements > li.wx'), {
cls: 'hw-widget',
tpl: '<div class="aeris-widget-currents-compact-icon">' +
'<a href="{{links.wxlocal}}?pands={{lower places.0.place.name}},{{#if places.0.place.state}}' +
'{{lower places.0.place.state}}{{else}}{{lower places.0.place.country}}{{/if}}">' +
'<img src="{{paths.wxicons}}{{observations.0.ob.icon}}" />' +
'</a></div>' +
'<div class="aeris-widget-currents-compact-temp">' +
'<a href="{{links.wxlocal}}?pands={{lower places.0.place.name}},{{#if places.0.place.state}}{{lower places.0.place.state}}' +
'{{else}}{{lower places.0.place.country}}{{/if}}">{{observations.0.ob.tempF}}°<span class="aeris-widget-unit">F</span></a>' +
'</div>' +
'{{#advisories}}<div class="aeris-widget-currents-compact-alert"></div>{{/advisories}}',
opts: {
resize: {
auto: false
}
}
});
In our example, we needed to differentiate this widget instance from all other instances that may appear, such as on our sample widgets page, in order to properly target it with our custom CSS styles. Therefore, we set our widget’s cls property to “hw-widget” and then each style we needed to override for this instance is prefixed by .hw-widget:
.hw-widget .aeris-widget-currents-compact-loader {background-color:transparent;background-image:url("http://js.aerisapi.com/css/assets/loader_ffffff_4f4f4f.gif");border:0;}
.hw-widget .aeris-widget-currents-compact-icon {margin-top:5px;margin-right:5px;}
.hw-widget .aeris-widget-currents-compact-icon img {width:30px;height:30px;}
.hw-widget .aeris-widget-currents-compact-icon a img {border:0;}
.hw-widget .aeris-widget-currents-compact-temp {font-size:18px;color:#fff;margin-top:10px;}
.hw-widget .aeris-widget-currents-compact a {color:#ddd;border:0;}
.hw-widget .aeris-widget-currents-compact a:hover {color:#fff;text-decoration:underline;}
We also needed to define a new template as there were certain elements we didn’t need from the default widget template. So we included a new HTML template in the widget’s tpl property, which also contains the variables pertaining to the actual API data we wanted to display. For instance, to display the current temperature in degrees Fahrenheit, the API returns:
{
"success": true,
"error": null,
"response": {
"id": "KMSP",
"loc": {
"long": -93.233333333333,
"lat": 44.883333333333
},
"place": {
"name": "minneapolis",
"state": "mn",
"country": "us"
},
"profile": {
"tz": "America/Chicago"
},
"obTimestamp": 1331217480,
"obDateTime": "2012-03-08T08:38:00-06:00",
"ob": {
"timestamp": 1331217480,
"dateTimeISO": "2012-03-08T08:38:00-06:00",
"tempC": -4,
"tempF": 25,
"dewpointC": -6,
"dewpointF": 21,
...
}
}
To display this in our HTML template, we would use the variable format expected for Handlebars JS and explained in the SDK documentation:
{{observations.0.ob.tempF}}
Since our widget is using a BatchCollection to load the data, the response data returned from the API is stored in the collection as an array for the endpoint used. Thus, we would need to access it by prefixing our variable key with the endpoint we want data for, observations, and the item number which we want to access, observations.0. The item number will typically be “0” unless you are using a BatchCollection to
load the same data for multiple locations, such as current observations for five locations. Then you would access each according to their zero-based array index:
{{observations.0....}}
{{observations.1...}}
{{observations.2...}}
You will also noticed we have used a block expression for #advisories and an #if block helper in our template, which are all features supported by Handlebars JS. Be sure to review the complete documentation for Handlebars JS to take advantage of its flexibility in your own Aeris JavaScript templates.
We will soon be adding a tutorials section to our Aeris JavaScript SDK documentation for additional examples of creating your own custom widgets using the SDK.
Collections & Models
The JavaScript SDK makes it extremely easy to use your Aeris API subscription within your own custom web applications and sites even without using the widgets. We’ve included a set of collection objects that perform all of the necessary data requests and parsing from the API in order to provide you with an easy method for accessing this weather data. Each API endpoint has its own collection within the SDK, so you don’t have to worry about API URLs, paths or query strings. Simply create your collection instance and tell it what type of data you want to fetch, including any of the supported API options for each endpoint.
To make accessing the returned API data even easier, we’ve assigned model objects for each collection as well. This type of abstraction allows for more efficient usage and better backwards compatibility, so if anything ever changes with the core Aeris API, our JavaScript SDK can automatically account for such changes internally. This greatly reduces the potential of your own application having errors due to such changes.
...
Read more...
by nshipes on Feb 08, 2012
Over the past few weeks, we’ve been actively working on the first component to Aeris Web -- the JavaScript SDK. We are continuing to test and wrap up all items required for our version 1.0 slated for release within a couple of weeks, but we wanted to provide a preview of how easy it will be to incorporate your Aeris API subscription into your custom web applications.
For instance, if you wanted to fetch the latest weather observations for Seattle, WA, you would just need to use the following snippet once you have initialized the Aeris JS SDK with your access information:
var obs = new Aeris.collections.Observations();
obs.bind('load', function(collection){
var model = collection.at(0);
alert('Currently in Seattle it is ' + model.get('ob.tempF') + ' degrees.');
});
obs.fetch('seattle,wa');
The same properties from the core data API are also used in the JavaScript SDK, so switching between the two formats is straightforward.
Built-In Widgets
We will also be including a set of basic built-in JavaScript widgets that you can include in your application that are fully customizable using CSS and custom templates. The following is an example of using our built-in Advisories widget that loads advisories for Birmingham, AL and renders it to a <div> whose id is “widget-advisories”:
var advisories = new Aeris.widgets.Advisories($('#widget-advisories'), {
params: {
p: 'birmingham,al'
}
});
All of our HTML templates are based on Handlebars JS, so it is very easy and quick to customize any of the built-in widgets or creating your own by extending our core objects.
Below are screenshots of some of the built-in widgets that will come with the Aeris JavaScript SDK.
Our included widgets also support additional features, like displaying data based on the user's geolocation or allowing them to view the data for a particular location they can search for. Additionally, widgets can be configured to auto-refresh its data based on a specific time interval, so you can ensure your data is always up to date no matter how long the page is open or application running.
We will be posting additional updates as we get closer to the official release of version 1.0 of the JavaScript SDK.
...
Read more...
by nshipes on Feb 03, 2012
This week we have pushed out updates to the Aeris Weather API and the iOS framework. We have also been busy wrapping up development for the initial release of the JavaScript toolkit coming soon.
The Aeris Weather API 1.0.6 update is a maintenance release that fixes several bugs and adds a few improvements. Most notably, updates to the storm cells endpoint and a new sortable date-time mapping for the storm reports, storm cells and fires endpoints. Additionally, a new “skip” parameter (currently in beta) was added which allows skipping over a specific number of results, which is useful when pagination is required. Review the version history for a complete list of changes.
Additions to the Storm Cells Endpoint
The storm cells now include a place object that provides the closest city, state and country to the storm cell. Also, a new ob.location property has been added which provides the distance and bearing to the closest city, such as “3 miles SSW of Mobile”. This better aligns the storm cells endpoint with our standard output for other similar endpoints.
Additionally, new query mappings were added for the name and state of the closest city to the storm cell, which can be used to request all storm cells within a state:
For example, the following query will return up to 100 storm cells in the state of Alabama:
/stormcells/search?query=state:al&limit=100
The following will return up to 100 storm cells in the state of Alabama with a rotation signature:
/stormcells/search?query=state:al&filter=rotating&limit=100
New sort mapping for Storm Reports
We have added two new sort mappings for storm reports: “dt” and “details”. The new “dt” mapping allows sorting results based on the report date and time.
For example, the following query will return up to 50 storm reports in the state of Minnesota, sorted newest to oldest, over the past 7 days:
/stormreports/search?query=state:mn&sort=dt:-1&from=-7days&limit=50
Note: The “dt” mapping was also added to the stormcells and fires endpoints.
The new “details” mapping allows sorting results based on the measured value in the report, when available.
For example, the following would return the top 10 snow reports in Minnesota for the past week sorted by the amount of snow reported in descending order:
/stormreports/search?query=state:mn&sort=detail:-1&filter=snow&from=-7days&limit=10
Skip Parameter
Although this feature is still in beta, we are also introducing the new “skip” parameter. This parameter can be used to skip a specified number of results, which when combined with the “limit” parameter can be useful in paging implementations.
For example, you may want to return 10 of the closest cities to Minneapolis sorted by descending distance but skip the first 10 results:
/places/closest?p=minneapolis,mn&skip=10&limit=10
Aeris iOS Framework Updates
Our 1.0.3 release of the Aeris iOS framework is a maintenance release that fixes several bugs and brings the model properties up to date with the property changes recently made in the core API.
The biggest change resulted from a bug in which the date and times displayed in the sample application were not using the proper time zone of the actual location the data was for, but instead always falling back the time zone of the iOS device. Therefore, we have added a new `timeZone` property that stores an NSTimeZone instance for the time zone of data’s location. This can then be passed to custom date formatters and calendars to get the correct day and time from the stored `timestamp` property (Note that all dates in iOS are stored in GMT). Refer to the developer documentation for the Aeris.framework for the full set of properties supported for each object.
Although new features have not been added in this update, support for batch processing and several new features are in the works will be coming very soon to the iOS framework. Refer to the full version history for the full list of changes in version 1.0.3.
...
Read more...
by lhuffman on Jan 27, 2012
We released version 1.0.5 of the Aeris Weather API which provides support for Canadian postal codes and several bug fixes. Review the version history for a complete list of changes.
Canadian Postal Codes
With this release, Canadian postal codes have been added to our supported place formats. When using postal codes, the space that occurs within the middle is optional, making "M3C 4H9" and "M3C4H9" equivalent.
An example of finding the place information for a postal code:
/places/M3C4H9
/places?p=M3C4H9
/places?p=M3C%204H9
An example of finding the closest observation for a postal code:
/observations/M3C4H9
Warnings
We have introduced the concept of request warnings with this update. Request warnings will be issued in special cases, such as when a parameter is being used improperly or your request includes deprecated functionality or properties. In such cases, the API will still provide a successful response with data, but the error object will include a warning message.
...
Read more...
by lhuffman on Jan 11, 2012
Today we released version 1.0.3 of the Aeris Weather API. This release provides support for auto-complete style queries with the new “starts with” functionality as well as several other minor items. Additionally, with this release we added batch requests as a beta feature! Batch requests allow you to query multiple endpoints with a single request to the servers. Review the version history for a complete list of changes.
“Starts With” Query / Auto-Complete
A common feature seen in many weather applications is the auto-complete style functionality that queries the server as a user is typing in a location name. Now with the new “starts with” query modifier, this can be accomplished easily. All that is needed is to precede the search string in the query with a caret (^) symbol.
An example of a query searching for words starting with “minn”:
/places/search?query=name:^minn&limit=10
The following uses the same above query but limits it to US locations only:
/places/search?query=name:^minn,country:us&limit=10
Batch Requests (Beta in v1.0.3 of the Aeris Weather API)
We have received many praises and requests for the Aeris Weather API, the most common request being the ability to query multiple endpoints all within a single query. Our new batch request feature takes care of this for you without having to learn a new endpoint or request format. Please note that as of 1.0.3 we consider this a beta feature and a max of 5 endpoints can be performed per batch request.
See the batch request documentation for full usage. The following are the primary features:
The batch endpoint uses a requests parameter set to a string of comma-separated standard endpoint requests. Each endpoint request must include either an :action or :id and its own parameters (optional). If the main batch request uses an :id, then this ID will be automatically passed to each endpoint query.
Additionally, any other parameters passed to the batch request are considered global and passed to each individual endpoint requests found in the requests parameter. Note, however, that the parameters included within an individual endpoint request will override those same options found in the global parameters of the batch request. For example:
/batch?limit=10&requests=/observations/closest,/stormreports?limit=5,/fires/closest
In this batch request, the global option “limit=10” is used by the observations and the fires endpoints, but the stormreports endpoint overrides this with it’s own “limit=5”
Use Case 1 - Fetch multiple data types for the same location:
The is the simplest and most common use of a batch request:
/batch/:id?requests=/:endpoint1,/:endpoint2,/:endpoint3
For example, to fetch the latest observation, daily forecast and active advisories for Minneapolis, MN:
/batch/minneapolis,mn?requests=/observations,/forecasts,/advisories
Parameters can be passed to each individual endpoint as well. For example, to obtain the latest observation, the forecast in daily intervals, the forecast in hourly intervals and all active advisories, the batch request would be:
/batch/minneapolis,mn?requests=/observations,/forecasts,/forecast?filter=6hr,/advisories?filter=all
Use Case 2 - Fetch data for multiple locations:
To fetch the latest observations for Atlanta, Minneapolis and Seattle:
/batch?requests=/observations/atlanta,ga,/observations/minneapolis,mn,/observations/seattle,wa
Use Case 3 - Fetch weather extremes:
The following batch request is combined with the power of the query and sort parameters to return the warmest and coldest locations in the US based on their latest observations:
/batch?limit=1&query=country:us,temp:-999&requests=/observations/search?sort=temp:-1,/observations/search?sort=temp
Here the “query=country:us,temp:-999” queries only observations in the US and only includes observations that have a valid temperature (observations that didn’t report a temperature for a particular hour will have -999 as the temperature value, so we would want to eliminate those that didn’t report).
Often during the winter months the warmest location in the US may be in Puerto Rico. So, adjust the query to eliminate locations in Puerto Rico to query only the 50 states:
/batch?limit=1&query=country:us,state:!pr,,temp:-999&requests=/observations/search?sort=-1,/observations/search?sort=temp
...
Read more...
by lhuffman on Jan 05, 2012
Today we released version 1.0.2 of the Aeris Weather API that provides some significant new capabilities, as well as several enhancements and bug fixes. The complete list of changes can be found in our version history, though some of the more significant enhancements include:
Sorting
Most APIs allow fetching of data, but leave sorting and filtering up to the developer to handle. With the Aeris API, we aim to simplify development by allowing the API to handle many of these features instead.
The new sort parameter allows making requests for data that is sorted by one or more elements from the data set. This feature allows fetching results presorted for easier processing and, when combined with the filter and query parameters, can obtain specific results that would normally not be readily available from a standard endpoint action.
Review the complete sorting documentation for the full details and capabilities, but a few use cases where the new sort parameter would be useful include:
UC1 - Find the top 50 cities within the US based on population with the results sorted by descending population:
http://api.aerisapi.com/places/search?query=country:us&sort=pop:-1&limit=50
UC2 - Obtain the warmest location in Minnesota based on latest observations:
http://api.aerisapi.com/observations/search?query=state:mn&sort=temp:-1
UC3 - Find flood-related advisories in Minnesota and Wisconsin sorted by state, significance and expiration time descending:
http://api.aerisapi.com/advisories/search?query=state:mn,state:wi&filter=flood&sort=state,sigp,expires:-1&limit=200
UC4 - Find the 10 closest weather observations to Minneapolis and sort the results based on descending temperature:
http://api.aerisapi.com/observations/closest?p=minneapolis,mn&radius=50miles&limit=10&sort=temp:-1
API Versions
While we strive to test and to ensure backwards compatibility with each new release of the API, we understand there may be occasional needs to query a specific version of the API. We have now added the ability to query specific versions of the API, starting with version 1.0.1.
The standard query to obtain the latest observation for Minneapolis, MN using the latest version of the API would be:
http://api.aerisapi.com/observations/minneapolis,mn
The same request but using version 1.0.1 instead would be:
http://api.aerisapi.com/v1.0.1/observations/minneapolis,mn
If you provide an invalid version number, the latest stable version will always be used. While we offer this new capability, we recommend always using the latest stable release of the API within your custom applications.
...
Read more...
by lhuffman on Dec 13, 2011
First off, we would like to say thanks for the tremendous enthusiasm and interest in our new Aeris product suite and the new site design. Over the coming weeks we will continue to expand Aeris with additional datasets, capabilities, JavaScript / PHP toolkits and more.
With that, today we released an update to the Aeris API that provided several bug fixes and added some enhanced capabilities. The complete list of changes is available in the version history, though some of the major enhancements include:
Enhanced Location Support
-
Complete US state names or Canadian province names may be used. For example:
-
/places/houston,texas
-
/observations/toronto,ontario
-
2 letter ISO country abbreviations, 3 letter ISO country abbreviations and full country names are now supported. For example:
-
/observations/mexico+city,mx
-
/observations/mexico+city,mex
-
/observations/mexico+city,mexico
-
The official country abbreviation for cities in the United Kingdom is “GB”, but since many users enter “UK” the api will now handle being passed “UK” in place of “GB”. Both of the following usages will work:
-
/places/london,gb
-
/places/london,uk
New Countries Endpoint
We added a new countries endpoint that allows requesting basic country information, such as full name, abbreviations, estimated populations and more. See the countries endpoint docs for more information.
...
Read more...
by nshipes on Nov 29, 2011
As you can tell, things have changed quite a bit with the site now that our much-needed site redesign has been completed and the switch has been flipped. Finally. Not only has the site changed, but our lines of products and services have also received a well-deserved overhaul. So let’s get a little more familiar with the changes.
Our new site boasts a clean, fresh look better focused around our extensive line of products and services. Aeris is our new core product, an API that provides the necessary weather data to power all of our other products and services.
Similar to the previous site, we still provide traditional weather content on our weather site, where you can view your local weather and sample our vast library of weather maps currently offered with our Aeris Graphics product.
If you’re looking for more customized solutions, we continue to offer our professional services to work one-on-one with your team to develop unique weather solutions. Services include custom web and mobile applications and specialized weather content and design, such as custom weather graphics, maps and custom branding strategies.
In the coming weeks, we will continue to provide additional content regarding our new products and services as we continue to receive feedback from our clients and users. We will also be communicating tips, tricks, videos and screencasts for Aeris and it’s toolkits here on our developer blog.
In the meantime, you can communicate with us on Twitter and subscribe to our blog’s RSS feed to stay up to date on the inner happenings at HAMweather.
...
Read more...