Fire Eagle : Calling the API

Before diving into the specific API calls, it's good to know a little bit about how to call Fire Eagle properly. Here we explain the two basic types of API calls, how URL requests are structured, HTTP GET vs. POST, response formats, and query parameters.

API method types

Fire Eagle has two classes of API methods: user-specific and general-purpose. The user-specific methods are called on behalf of an authenticated user while the general-purpose methods are called on behalf of the application.

User-specific

API Methods for updating and querying a user's own location. Calls to this API should use a user-specific access token. The primary User-specific calls are user, update, and lookup.

General-purpose

API Methods for getting information about all users of the application, e.g. recently updated locations, and users who are within a location. Calls to this API should use the general-purpose access token. The primary General-purpose calls are recent, within, and lookup.

Only web-based applications are allowed to call general-purpose methods. When you create a web-based application, you will be assigned a general-purpose token and general-purpose token secret. Learn more about application types.

URL & Response Formats

Fire Eagle requests are RESTful. The URL also controls the response format. The proper HTTP method changes depending on the API call.

URL Format

Information (including OAuth authentication) is sent with the URL as query string parameters in the form of:

https://[URL]/api/[version]&/[method].[response_format]?[query-string-parameters]

Response Format

Fire Eagle has two response formats: XML or JSON. Response formats are specified by appending the requested format to the URL. If no response format is specified, then by default, the response format is XML.

For example, to request a user location in XML format:

https://fireeagle.yahooapis.com/api/0.1/user.xml?oauth_consumer_ke...

For JSON, change the url to end with .json. If you need the resulting data wrapped in a function, include a callback parameter with its name.

https://fireeagle.yahooapis.com/api/0.1/user.json?oauth_consumer_ke...

HTTP Method

The HTTP method (GET and POST) varies on the request type. In RESTful fashion, queries (such as /user, /recent, and /lookup) are GETs. Updates (currently only /update) are POSTs. The method must match the operation (or you will get a 405 Unsupported Method error).

Request Parameters

Parameters fall into three categories: Required, Default, and Invalid. There are more specifics about the location parameters to pass into the API methods available.

Required

Required parameters must be specified in the request. They have no default values. Passing in a null (for example foo has a null value: ?city=anytown&foo=&state=anystate) or invalid argument will return an error. Some parameters are only required in conditional cases. For example, when specifying a location, some valid set of values is required, but only one such set.

Default Values

If a parameter is not required, it may have a default value. The default will only be used if the parameter is not supplied in the method call. If you supply a null or invalid value for a parameter, the default will not be assumed in its place.

Invalid Values

Required or not, each parameter may have invalid parameters. For example, longitude, and latitude values must be between -180.0 and 180.0 and -90.0 and 90.0, respectively. If you supply an invalid value for a parameter, an error will be returned even if the parameter is optional, is conditionally optional (as in location queries & updates) or has a default value.

Response Structure

Fire Eagle returns two response formats: XML or JSON. Set xml or json as your [response_format] in the API request. Read more about the location hierarchy for details.

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" xmlns:georss="http://www.georss.org/georss">
  [api response]
</rsp>

{"user":{api response},
 "stat":"ok"}