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

Geolocation API

Access geolocation information from your device.

Refer to our Geolocation guide 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"]

Methods

accuracy()

Returns the estimated accuracy of the fix. Units: Horizontal radius in Meters.

Float

Ruby: Geolocation.accuracy

JavaScript: Rho.Geolocation.accuracy();

Ruby 
def get_accuracy
  accuracy = Geolocation.accuracy
  Alert.show_popup accuracy
end
JavaScript 
function getAccuracy(){
  var accuracy = Rho.Geolocation.accuracy;
  alert(accuracy);
}

altitude()

Returns the altitude if available, if not available 0 is returned. Units: Meters above sea level.

Double

Ruby: Geolocation.altitude

JavaScript: Rho.Geolocation.altitude();

Ruby 
def get_altitude
  altitude = Geolocation.altitude
  Alert.show_popup.altitude
end
JavaScript 
function getAltitude(){
  var altitude = Rho.Geolocation.altitude;
  alert(altitude);
}

haversine_distance( FLOAT latitude1, FLOAT longitude1, FLOAT latitude2, FLOAT longitude2 )

Returns the distance between two points in miles.
  • 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.

Ruby: Geolocation.haversine_distance(latitude1, longitude1, latitude2, longitude2)

JavaScript: Rho.Geolocation.haversine_distance(latitude1, longitude1, latitude2, longitude2);

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: Geolocation.known_position?

JavaScript: Rho.Geolocation.is_known_position();

Boolean

latitude()

Returns current latitude in degrees.

Ruby: Geolocation.latitude

JavaScript: Rho.Geolocation.latitude();

Float

longitude()

Returns current longitude in degrees.

Ruby: Geolocation.longitude

JavaScript: Rho.Geolocation.longitude();

Float

satellites()

Returns the number of satellites used to determine the fix. If this information isn't available, null is returned.

Integer
Ruby 
def get_satellites
  satellites = Geolocation.satellites
  Alert.show_popup.satellites
end
JavaScript 
function getSatellites(){
  var satellites = Rho.Geolocation.satellites;
  alert(satellites);
}

Ruby: Geolocation.satellites

JavaScript: Rho.Geolocation.satellites();

set_notification( CALLBACK callback_url, STRING callback_params, INT ping_gpssystem_interval )

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.
The callback_url parameter must be set in order for Geolocation to function.

Ruby: Geolocation.set_notification(callback_url, callback_params, ping_gpssystem_interval)

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

set_notification_ex( CALLBACK url, STRING callbackParams, HASH options )

Extended notification which encompasses the recently added features.
There is no valid data related to distance, which the Geolocation API exposes in WM and hence there is no support for extended notification in WM.
minDistance and minTimeout values are optional; if nothing is provided, whenever a location update is processed by the underlying system, it is sent to the application. It is supported only on Android devices.
  • url - Callback method to be invoked on any notification.
  • callbackParams - To be used when callback is invoked. It is generally used to know the source of the callback. This is optional.
  • options - This is a hash and can consist of the following two keys:
    • minDistance - Minimum moving distance(in meters) to invoke the callback again.
    • minTimeout - Minimum timeout for next callback invocation.

Ruby: Geolocation.set_notification_ex(callback url, string callbackParams, options hash)

JavaScript: Rho.Geolocation.set_notification_ex(callback url, string callbackParams, options hash);

When the callback happens, it will provide the following parameters:

  • known_position - 1 or 0. Return from known_position? method.
  • latitude - Value returned by Geolocation.latitude() method.
  • longitude - Value returned by Geolocation.longitude() method.
  • altitude - Value returned by Geolocation.altitude() method.
  • speed - Value returned by Geolocation.speed() method.
  • accuracy - Value returned by Geolocation.accuracy() method.
  • satellites - Value returned by Geolocation.satellites() 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.

speed()

Returns the speed if it is available. If the speed is not available, 0.0 is returned. On iOS it will return a negative speed when it can not calculate it - for example when device detects location not by GPS but by 3G or Wi-Fi triangulation (also in the case where accuracy is too large - about 50 and more meters).

Units: Meters/sec over ground

Float

Ruby: Geolocation.speed

JavaScript: Rho.Geolocation.speed();

def get_speed
  speed = Geolocation.speed
  Alert.show_popup speed
end
function getSpeed(){
  var speed = Rho.Geolocation.speed;
  alert(speed);
}

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 
Geolocation.turnoff
JavaScript 
Rho.Geolocation.turnoff();