Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

GeoLocation API

Access geolocation information from your device.

See the controller and view in the /app/GeoLocation folder of the System API Samples application for an example.

Refer to GeoLocation in Device Capabilites for more discussion of GeoLocation, and for examples.

Enabling Geolocation

To use the geolocation API, you need to enable geolocation on the device. Do this by adding that capability to the build.yml file:

capabilities:
  - gps

We do not have a timeout parameter to automatically turn off the GPS system. If you want to turn off the GPS system, call GeoLocation.turnoff.

Using JavaScript API

You can call the GeoLocation methods from JavaScript as well as Ruby. To use the JavaScript API, add the public/js/rho_javascript_api.js file – created at build time as part of the application package – to the .html, .erb, or .js file calling the JavaScript method.

The JavaScript API methods with a return value can pass it as a parameter in jQuery-compatible continuation (deferred object, a kind of callback). Possible continuations to handle are done, fail, and complete.

Rho.Class.method(params).done(function(handler) { /* handler... */ })

You must enable JavaScript by putting rho-javascript into extensions in your build.yml.

extensions: ["rho-javascript"]

You must have a RhoElements license to use the JavaScript API.

latitude

Returns current latitude in degrees.

Ruby syntax:

GeoLocation.latitude

JavaScript syntax:

Rho.GeoLocation.latitude()

longitude

Returns current longitude in degrees.

Ruby syntax:

GeoLocation.longitude

javaScript syntax:

Rho.GeoLocation.longitude()

known_position?, is_known_position

Returns true if the location system is up and running, false otherwise. is_known_position returns null if this feature is not supported on the device platform.

Ruby syntax:

GeoLocation.known_position?

JavaScript syntax:

Rho.GeoLocation.is_known_position()

set_notification

Set callback to track location changes.

You only need to call GeoLocation.set_notification once. The current behavior of the callback is that it will be called forever until it is stopped; you need to call GeoLocation.turnoff to stop it. The previous behavior was that the callback was called once and needed to be reset.

Refer to Device Capabilities - GeoLocation for examples of set_notification.

Ruby syntax:

GeoLocation.set_notification(callback_url, callback_params, ping_gpssystem_interval)

The callback_url parameter must be set in order for GeoLocation to function.

JavaScript syntax:

Rho.GeoLocation.set_notification(callback, callback_params, ping_gpssystem_interval)
callback_url url for the callback method called upon a location change notification or for the interval set by ping_gpssystem_interval.
callback_params a string added to the body of the callback url. You can use it to identity who is setting up the callback, such as "my_tag=55". In general you do not set callback_param (leave it blank as in "").
ping_gpssystem_interval (optional) If 0, the system interval is used; the callback is executed when the GPS system processes a location update (dependent on the mobile platform). If set to a number (such as 3), the callback is executed at an interval of this number of seconds (such as every three seconds).

When the GeoLocation.set_notification callback is called, it will receive a variable called @params, just like a normal Rhodes controller action. Here are the parameters included in the @params variable.

known_position 1 or 0. Return from known_position? method.
latitude Return from call to latitude method.
longitude Return from call to longitude method.
available 1 if geolocation is available, 0 otherwise. For 1, not only does the hardware exist, but also the user can turn GPS off in phone settings, or not allow GPS activity on iPhone, etc.
status "ok" or "error"
error_code error code from RhoError.
accuracy horizontal radius in meters; iOS and Android.

Click here for the RhoError error code list.

haversine_distance

Returns the distance between two points in miles.

Ruby syntax:

GeoLocation.haversine_distance(latitude1, longitude1, latitude2, longitude2)

JavaScript syntax:

Rho.GeoLocation.haversine_distance(latitude1, longitude1, latitude2, longitude2)
latitude1 Latitude of the first point in degrees.
longitude1 Longitude of the first point in degrees.
latitude2 Latitude of the second point in degrees.
longitude2 Longitude of the second point in degrees.

turnoff

Turn off GeoLocation.

When you call GeoLocation.turnoff, after the GPS is switched off, you might still receive a few callbacks (this depends on the platform; iOS and Android does not receive callbacks after turnoff).

Ruby syntax:

GeoLocation.turnoff

JavaScript syntax:

Rho.GeoLocation.turnoff()
Back to Top