Fire Eagle : Finding a User's Location

Developer Centre

Finding a User's Location

The main method is user which your application uses to query Fire Eagle for the location of a single user. Additionally, there is recent which allows your application to query for a list of users who recently updated locations and within which allows you to query for a list of your users within a location.

user

Returns the location of a specific user in a location hierarchy format.

Called with the user-specific access token.

https://fireeagle.yahooapis.com/api/0.1/user

Required Parameters:
  • oauth_consumer_key : application consumer key
  • oauth_token : the user-specific access token
  • oauth_nonce, oauth_timestamp, oauth_signature_method, oauth_version, oauth_signature

Responses to queries for a user's location are returned in a well-formatted location hierarchy. The location hierarchy represents 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.

Users authorize an application to read their location at whichever level they're most comfortable. So, the location hierarchy response returned to the user 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 timestamp. We would recommend using the "best guess" location by default.

Timezone information (as a tz string) is included if the application has been authorized at the city level or better.

Example: /user.xml

Request

https://fireeagle.yahooapis.com/api/0.1/user?oauth_consumer_key=0000000000000&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=mEhrJ6Zl8RHI&oauth_timestamp=1204588542&oauth_nonce=WXeVhx&oauth_signature=OPIgcbKC2WQVO3kL6oATdiUdf4g%3D

Response


<rsp stat="ok">
  <user token="mEhrJ6Zl8RHI" located-at="2008-08-06T16:05:48-08:00">
    <location-hierarchy timezone="America/Los_Angeles">
      <location best-guess="true">
        <id>114031</id>
        <georss:point>37.7812461853 -122.3957595825</georss:point>
        <level>0</level>
        <level-name>exact</level-name>
        <located-at>2008-03-03T10:58:55-08:00</located-at>
        <name>500 3rd St, San Francisco, CA</name>
      </location>
      <location best-guess="false">
        <id>114041</id>
        <georss:box>
          37.7494697571 -122.40650177 37.7862281799 -122.3790893555
        </georss:box>
        <level>1</level>
        <level-name>postal</level-name>
        <located-at>2008-03-03T10:58:55-08:00</located-at>
        <name>San Francisco, CA 94107</name>
        <normal-name>94107</normal-name>
        <place-id>8Xq01wWYA5u_OEMhyQ</place-id>
        <woeid>12797158</woeid>
      </location>
      <location best-guess="false">
        <id>114051</id>
        <georss:box>
          37.7037811279 -122.5154571533 37.8545417786 -122.32472229
        </georss:box>
        <level>3</level>
        <level-name>city</level-name>
        <located-at>2008-03-03T10:58:55-08:00</located-at>
        <name>San Francisco, CA</name>
        <normal-name>San Francisco</normal-name>
        <place-id>kH8dLOubBZRvX_YZ</place-id>
        <woeid>2487956</woeid>
      </location>
      <location best-guess="false">
        <id>114061</id>
        <georss:box>
          37.7037811279 -122.5154571533 37.8545417786 -122.32472229
        </georss:box>
        <level>4</level>
        <level-name>region</level-name>
        <located-at>2008-03-03T10:58:55-08:00</located-at>
        <name>San Francisco County, CA</name>
        <normal-name>San Francisco</normal-name>
        <place-id>kH8dLOubBZRvX_YZ</place-id>
        <woeid>12587707</woeid>
      </location>
      <location best-guess="false">
        <id>114071</id>
        <georss:box>
          32.5342788696 -124.4150238037 42.0093803406 -114.1308135986
        </georss:box>
        <level>5</level>
        <level-name>state</level-name>
        <located-at>2008-03-03T10:58:55-08:00</located-at>
        <name>California</name>
        <normal-name>California</normal-name>
        <place-id>SVrAMtCbAphCLAtP</place-id>
        <woeid>2347563</woeid>
      </location>
      <location best-guess="false">
        <id>114081</id>
        <georss:box>
          18.9108390808 -167.2764129639 72.8960571289 -66.6879425049
        </georss:box>
        <level>6</level>
        <level-name>country</level-name>
        <located-at>2008-03-03T10:58:55-08:00</located-at>
        <name>United States</name>
        <normal-name>United States</normal-name>
        <place-id>4KO02SibApitvSBieQ</place-id>
        <woeid>23424977</woeid>
      </location>
    </location-hierarchy>
  </user>
</rsp>

Example: /user.json

Request

https://fireeagle.yahooapis.com/api/0.1/user.json?oauth_consumer_key=0000000000000&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=UZuTj74EUF70&oauth_timestamp=1204591209&oauth_nonce=OfNuyH&oauth_signature=qxR2Glmgq6xYCtoRi5DLS0yHqhQ%3D

Response

{ 
  "stat" :  "ok",
  "user" : { 
    "token" : "RzpwVb7fmznJ",
    "timezone" : "America/Los_Angeles",
    "location_hierarchy" : [{ 
      "label" : null,
      "located_at" : "2008/08/07 17:50:15 -0700",
      "level" : 3,
      "normal_name" : "San Francisco",
      "name" : "San Francisco, CA",
      "geometry" : { 
        "type" : "Polygon",
        "coordinates" : [[[-122.5154571533, 37.7037811279],
                          [-122.32472229, 37.7037811279],
                          [-122.32472229, 37.8545417786],
                          [-122.5154571533, 37.8545417786],
                          [-122.5154571533, 37.7037811279]]],
        "bbox" : [[-122.5154571533, 37.7037811279],
                  [-122.32472229, 37.8545417786]]
      },
      "level_name" : "city",
      "woeid" : 2487956,
      "best_guess" : true,
      "id" : 17711351,
      "place_id" : "kH8dLOubBZRvX_YZ"
    }, { 
      "label" : null,
      "located_at" : "2008/08/07 17:50:15 -0700",
      "level" : 4,
      "normal_name" : "San Francisco",
      "name" : "San Francisco County, California",
      "geometry" : { 
        "type" : "Polygon",
        "coordinates" : [[[-123.1080169678, 37.6930503845],
                          [-122.3567581177, 37.6930503845],
                          [-122.3567581177, 37.832359314],
                          [-123.1080169678, 37.832359314],
                          [-123.1080169678, 37.6930503845]]],
        "bbox" : [[-123.1080169678, 37.6930503845],
                  [-122.3567581177, 37.832359314]]
      },
      "level_name" : "region",
      "woeid" : 12587707,
      "best_guess" : false,
      "id" : 17711341,
      "place_id" : "hCca8XSYA5nn0X1Sfw"
    }, { 
      "label" : null,
      "located_at" : "2008/08/07 17:50:15 -0700",
      "level" : 5,
      "normal_name" : "California",
      "name" : "California",
      "geometry" : { 
        "type" : "Polygon",
        "coordinates" : [[[-124.4150238037, 32.5342788696],
                          [-114.1308135986, 32.5342788696],
                          [-114.1308135986, 42.0093803406],
                          [-124.4150238037, 42.0093803406],
                          [-124.4150238037, 32.5342788696]]],
        "bbox" : [[-124.4150238037, 32.5342788696],
                  [-114.1308135986, 42.0093803406]]
      },
      "level_name" : "state",
      "woeid" : 2347563,
      "best_guess" : false,
      "id" : 17623741,
      "place_id" : "SVrAMtCbAphCLAtP"
    }, { 
      "label" : null,
      "located_at" : "2008/08/07 17:50:15 -0700",
      "level" : 6,
      "normal_name" : "United States",
      "name" : "United States",
      "geometry" : { 
        "type" : "Polygon",
        "coordinates" : [[[-167.2764129639, 18.9108390808],
                          [-66.6879425049, 18.9108390808],
                          [-66.6879425049, 72.8960571289],
                          [-167.2764129639, 72.8960571289],
                          [-167.2764129639, 18.9108390808]]],
        "bbox" : [[-167.2764129639, 18.9108390808],
                  [-66.6879425049, 72.8960571289]]
      },
      "level_name" : "country",
      "woeid" : 23424977,
      "best_guess" : false,
      "id" : 17623731,
      "place_id" : "4KO02SibApitvSBieQ"
    }]
  }
}

recent

Returns a list of users of the application who have updated their location within the given amount of time.

Not for the faint of heart, this method is experimental and may not be stable.

Called with the general-purpose access token.

https://fireeagle.yahooapis.com/api/0.1/recent

Required Parameters:
  • oauth_consumer_key : application consumer key
  • oauth_token : general-purpose access token
  • oauth_version, oauth_signature_method, oauth_nonce, oauth_timestamp, oauth_signature
Optional Parameters:
  • time (default: now) : the time to start looking at recent updates from
  • per_page (default: 10) : number of users to return per page
  • page (default: 0) : the page number at which to start returning the list of users, pages are 0-indexed, each page contains the per_page number of users.

You might use this method if you're keeping a local cache of your users locations and want to update it periodically. Another use is to send messages based on users' locations when there's no need to message them if they haven't moved.

Example: /recent.xml

Request

https://fireeagle.yahooapis.com/api/0.1/recent.xml?oauth_consumer_key=0000000000000&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=UZuTj74EUF70&count=2&time=&oauth_timestamp=1204605774&oauth_nonce=NPvHhi&oauth_signature=LexXe6PhQX814McdNifQ%2Bp6CiHQ%3D

Response


    <?xml version="1.0" encoding="UTF-8"?>
    <rsp stat="ok" xmlns:georss="http://www.georss.org/georss">
      <users>
        <user token="8zuzkn86wh5x" located-at="2008-08-01T10:59:09-07:00"/>
      </users>
    </rsp>

Example: /recent.json

Request

https://fireeagle.yahooapis.com/api/0.1/recent.json?oauth_consumer_key=0000000000000&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=UZuTj74EUF70&count=2&time=&oauth_timestamp=1204605882&oauth_nonce=xTikeP&oauth_signature=W7d9lihPKfwRocymCk45ec2%2FMWI%3D

Response


    {
     "users": [
      {
        "located_at": "2008-08-01T10:59:09-07:00",
        "token": "8zuzkn86wh5x"
      }
     ],
     "stat": "ok"
    }

within

Takes a Place ID or a WoE ID and returns a list of users using your application who are within the bounding box of that location.

Not for the faint of heart, this method is experimental and may not be stable.

Called with the general-purpose access token.

https://fireeagle.yahooapis.com/api/0.1/within

Required Parameters:
  • oauth_consumer_key : application consumer key
  • oauth_token : general-purpose access token
  • a location parameter such as woeid, address, etc.
  • oauth_version, oauth_signature_method, oauth_nonce, oauth_timestamp, oauth_signature

Example: /within.xml

Request

https://fireeagle.yahooapis.com/api/0.1/within.xml?oauth_consumer_key=0000000000000&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=UZuTj74EUF70&place_id=&woeid=12796255&oauth_timestamp=1204596221&oauth_nonce=9IZU3E&oauth_signature=nYhHrF6uhGBgFkqPVqSNBbHg5NI%3D

Response


    <?xml version="1.0" encoding="UTF-8"?>
    <rsp stat="ok" xmlns:georss="http://www.georss.org/georss">
      <users>
        <user token="8zuzkn86wh5x" located-at="2008-08-01T10:59:09-07:00"/>
      </users>
    </rsp>

Example: /within.json

Request

https://fireeagle.yahooapis.com/api/0.1/within.json?oauth_consumer_key=0000000000000&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_token=UZuTj74EUF70&place_id=&woeid=12796255&oauth_timestamp=1204596558&oauth_nonce=id7Bid&oauth_signature=KmAf1GLbJblyn4azo4lsKQCwcZE%3D

Response


    {
     "users": [
      {
        "located_at": "2008-08-01T10:59:09-07:00",
        "token": "8zuzkn86wh5x"
      }
     ],
     "stat": "ok"
    }