The verb <Geolocation> sends a Geolocation request either to a mobile cellular network or to an IP Geolocation application. The request could be triggered by example by an external client or during a voice call, USSD request or after reception of an SMS.

Geolocation attributes

The <Geolocation> verb supports the following attributes:

PARAMETER

ALLOWED VALUES

DEFAULT VALUE

deviceIdentifier

Phone number

See below

action

Relative or absolute URL

None

method

GET, POST

POST

statusCallback

Relative or absolute URL

None

●      deviceIdentifier. The ‘deviceIdentifier’ attribute takes a valid E.164 phone number, an IP or MAC address as a value. RestComm will send a location request to this target.

●      action. The ‘action’ attribute takes a URL as an argument. After processing the <Geolocation> verb, RestComm will make a GET or POST request to this URL with the form parameters ‘GeolocationStatus’ and ‘GeolocationSid’. Using an ‘action’ URL, your application can receive synchronous notification that the Geolocation service was successfully queued. If you provide an ‘action’ URL, RestComm will use the RCML received in your response to the ‘action’ URL request to continue the current service. Any RCML verbs occurring after a <Geolocation> which specifies an ‘action’ attribute are unreachable. If no ‘action’ is provided, <Geolocation> will finish and RestComm will move on to the next RCML verb in the document. If there is no next verb, RestComm will end the service.

●      method. The ‘method’ attribute takes the values ‘GET’ or ‘POST’. This tells RestComm whether to request the ‘action’ URL via HTTP GET or POST. This attribute is modelled after the HTML form ‘method’ attribute.

●      statusCallback. The ‘statusCallback’ attribute takes an URL as an argument. When the location request is sent, or if sending fails, RestComm will make an asynchronous POST request to this URL with the parameters ‘GeolocationStatus’ and ‘GeolocationSid’. Note, ‘statusCallback’ always uses HTTP POST to request the given URL.

Request parameters

PARAMETER DESCRIPTION

GeolocationSid

Sid for the Geolocation service request.

GeolocationStatus

Status of the Geolocation service request. Either ‘sent’ or ‘failed’.

Nesting

The <Geolocation> verb can have the following nouns nested: <Immediate> and <Notification>.

●        <Immediate> noun: refers to requests for retrieval of current or last known location information (an associated timestamp will be included in the response). Geolocation information might include very accurate location data in terms of geographic coordinates, or just location identifiers like the radio base station transceiver identity of a cellular network that is currently giving service to the target device. Accuracy will depend on the available location procedures, either within a Mobile Network Operator for mobile handsets location within a cellular Radio Access Network, or a WLAN/WiFi covered area for IP location.

●        <Notification> noun: refers to requests for retrieval of event related location information. Examples include geofencing, device availability/presence alerts, sensors/beacons alarms, etc. Relative location data (distance to a specific spot), time intervals of occurrence and other kinds of event associated operational information can be included from this mode request.

The <Immediate> noun does not bring up additional attributes to the <Geolocation> verb. Contrariwise, the <Notification> noun adds additional attributes that are discussed further in this document.

<Notification> noun attributes

The <Notification> noun adds additional attributes that are discussed next. The following additional attributes support:

PARAMETER ALLOWED VALUES DEFAULT VALUE

eventGeofencingLatitude

A valid latitude universal coordinate

null

eventGeofencingLongitude

A valid longitude universal coordinate

null

geofenceRange

An integer amount to represent a distance in metres.

null

geofenceEvent

A string representing the type of geofencing event to be notified.

null

●      eventGeofencingLatitude. The ‘eventGeofencingLatitude’ attribute refers to the geographic coordinates’ latitude of a specific location. Used to notify when a device is within a certain distance (in metres) from that specific location.

●      eventGeofencingLongitude. The ‘eventGeofencingLongitude’ attribute refers to the geographic coordinates’ longitude of a specific location. Used to notify when a device is within a certain distance (in metres) from that specific location.

●      geofenceRange. The ‘geofenceRange’ attribute refers to the distance in metres from a specific geographic location denoted by ‘eventGeofencingLatitude’ and ‘eventGeofencingLongitude’.

●      geofenceEvent. The ‘geofenceEvent’ attribute refers to the eventuality of a target device entering or leaving a specific location area (implicitly specified by ‘EventGeofenceLatitude’, ‘EventGeofenceLongitude’ and ‘GeofenceRange’). Available values are:

o       in: reports when the target device has been detected within the specified location area.

o       out: reports when the target device has been detected leaving the specified location area.

o       in-out:  reports when the target device has been detected either entering or leaving the specified location area.

RCML examples

RCML examples on how to use the <Geolocation> verb are depicted next.

Immediate Geolocation service example demanding a synchronous HTTP POST action:

<Response>
	<Geolocation>
		<Immediate deviceIdentifier="59899549878" action="http://my.controller.net" method="POST"/>
    </Geolocation>
</Response>

Immediate Geolocation service example demanding an asynchronous HTTP POST:

<Response>
    <Geolocation>
        <Immediate deviceIdentifier="59899549878" statusCallback="http://192.16.1.19:8080/ACae6e420f425248d6a26948c17a9e2acf"/>
    </Geolocation>
</Response>

Notification Geolocation service example demanding a synchronous HTTP GET action:

<Response>
    <Geolocation>
        <Notification deviceIdentifier="59899549878" eventGeofencingLatitude="-33.426280" eventGeofencingLatitude="-70.566560W" geofenceRange="500" geofenceEvent="in-out" action="http://192.16.1.19:8080/ACae6e420f425248d6a26948c17a9e2acf" method="GET"/>
    </Geolocation>
</Response>

Notification Geolocation service example demanding an asynchronous HTTP POST:

<Response>
    <Geolocation>
        <Notification deviceIdentifier="59899549878" eventGeofencingLatitude="-33.426280" eventGeofencingLatitude="-70.566560W" geofenceRange="500" geofenceEvent="in-out" statusCallback="http://192.16.1.19:8080/ACae6e420f425248d6a26948c17a9e2acf"/>
    </Geolocation>
</Response>

When the Geolocation request is sent, or if sending fails, RestComm will make an asynchronous POST method to the ‘StatusCallback’ URL with the parameters ‘GeolocationStatus’ and ‘GeolocationSid’, as explained in the Restcomm RCML Geolocation section.

See below examples of this method applicable to previous examples for either ‘sent’ or ‘failed’ requests.

HTTP POST http://192.16.1.19:8080/ACae6e420f425248d6a26948c17a9e2acf  -d
"GeolocationSid=GLd66d2fe3954b4c888ad3dafc81b8f661" -d
"GeolocationStatus=sent"
HTTP POST http://192.16.1.19:8080/ACae6e420f425248d6a26948c17a9e2acf  -d
"GeolocationSid=GLd66d2fe3954b4c888ad3dafc81b8f661" -d
"GeolocationStatus=failed"