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...