Before diving into the API methods, you should understand how location data is represented inside Fire Eagle. Location data goes in and out of Fire Eagle, in terms of parameters and responses. Location data coming out of Fire Eagle are responses to queries and formated in a location hierarchy. Location data coming into Fire Eagle are parameters to the API method and can be represented as street addresses in the form of text strings, Place IDs (as used on Flickr or Upcoming), lon/lat coordinates, bounding boxes, etc. Fire Eagle takes these incoming location parameters, priorities them according to accuracy level and translates the data into a consistent location hierarchy.
User Location Permissions
From the user's perspective, when she is authorizing your application, she is setting two things. Firstly, she is authorizing how much of her location information in Fire Eagle is accessible to your application. Secondly, she is deciding whether your application can set his location in Fire Eagle.
Users authorize which of the following levels of their location information your application is able to access. Your application should be prepared to deal with inputs at any of these levels.
- user has not allowed read access.
- as precisely as possible
- at the Postal Code level
- at the Neighborhood level (currently unused)
- at the Town level
- at the Regional level (currently unused)
- at the State level
- at the Country level
After authorizing your application, the user can change either of these authorization settings at any time without notice to your application.
Location Hierarchy
Responses to queries for a user's location are returned in a well-formatted location hierarchy. The location hierarchy contains representations of the user's known location as levels from exact location to decreasing accuracy. The levels are: exact location, postal code, neighborhood/local area, large cities, county, state and country.
XML Response Format
<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" xmlns:georss="http://www.georss.org/georss">
<user token="[user token]">
<location-hierarchy timezone="TZ value">
<location best-guess="[true|false]">
<georss:box>[georss]</georss:box>
<level>[level]</level>
<level-name>[level name]</level-name>
<located-at>[timestamp]</located-at>
<name>[location name]</name>
<place-id>[place ID]</place-id>
<woeid>[WOE ID]</woeid>
</location>
[more location elements]
</location-hierarchy>
</user>
</rsp>
Users authorize an application to read their location at whichever level they're most comfortable. So, the location hierarchy response returned to an application query could consist of (1) only country, or (2) country & state or (3) country, state & county and so forth. One level in the hierarchy will be marked as Fire Eagle's "best guess" for the user's location. This best guess is derived as the most accurate level of the hierarchy with the most recent time-stamp. We would recommend using the "best guess" location by default.
In order to avoid conflicts where a more accurate location is overwritten by a less accurate one, Fire Eagle keeps any levels of the location hierarchy that have not been directly contradicted or updated by a subsequent update.
For example, if a user's exact location is set to 500 3rd Street San Francisco and then their city is set to San Francisco ten minutes later, the location hierarchy will keep exact location set to 500 3rd Street. If the city is set to Detroit five minutes later, then the location hierarchy will void the previous exact location. Each level in the hierarchy is time-stamped.
It's important to remember when developing applications that a user may supply information at any level of granularity, from their exact location up to just their current country. All applications have to therefore be ready to receive information at any scale, even if they choose not to do anything with it. We always provide information on every level in the heirarchy larger than the one the user has specified (if a user is comfortable sharing their exact location, then we'll also provide their neighborhood, city, state and country).
Location Parameters
Location data passed into Fire Eagle for updating a user's location can be from a variety of input methods. Fire Eagle will take into account all the location inputs in order to determine the best location of the user. In general, Fire Eagle will give more weight to the more precise location inputs, such as latitude and longitude geo-coordinates. However, Fire Eagle will assemble all the inputs in order to parse the user's location. The formats of location data that Fire Eagle access are described below.
(lon, lat) - both required, valid values are floats of -180 to 180 for lon and -90 to 90 for latwoeid - 32-bit identifier that uniquely represents spatial entities.- address - street address (may contain a full address, but will be combined with postal, city, state, and country if those values are available)
upcoming_venue_id - identifier that uniquely represents a venue from Upcoming.org(mnc, mcc, lac, cellid) - cell tower information, all values are in integers and required for a valid tower locationpostal - a ZIP or postal code (combined with address, city, state, and country if those values are available)city - city (combined with address, postal, state, and country if those values are available)state - state (combined with address, postal, city, and country if those values are available)country - country (combined with address, postal, city, and state if those values are available)