Locate a Mobile User

Overview

API Interface: HTTPS
URI: /v4/locations
Methods: GET
Response Schemas: JSON (default), XML

An application programming interface for connecting external applications, systems, and devices with the Aerialink Service Gateway for the purpose of obtaining location coordinates for mobile devices on supported carrier networks. This specific API covers locations transactions only.

Please note that this is now a deprecated legacy service.

Response Schema

Aerialink supports both JSON and XML response schemas, however the default response schema is JSON. If you wish to receive your response schema in XML or explicitly set the response schema to JSON, follow these examples as you construct your complete request URL.

/locations
(defaults to JSON automatically)

/locations.json
(explicitly sets the response to a JSON schema, same as default)

/locations.xml
(sets the response to an XML schema)

Method [GET] : Locate a Device

This method approximates the physical geographic location of a user/device with an accuracy determined by requestType parameter value. The request is initiated by your application.

Request

The available request parameters for this resource and method are listed below and should be sent form-post.

Required Parameters

  • destination [varchar(15)]
    The destination mobile number that you wish to geo locate. This should be provided in international format excluding the plus sign. For example: 1xxxyyyzzzz for a U.S. mobile number.

  • requestType [smallint(1)]
    The location request type must be a value of 1, 2, 3, or 4.

    • 1 : “Assisted GPS ONLY”
    • 2 : “Cell ID ONLY”
    • 3 : “Assisted GPS 1st, then Cell ID”
    • 4 : “Cell ID 1st, then Assisted GPS”

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

  • version [string] : The requested version of the resource
  • resource [string] : The requested resource name
  • method [string] : The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
  • type [string] : The request type; Syncronous or Asyncronous
  • guid [string] : The globally unique transaction ID for the LBS ping
  • destination [string] : The destination mobile number that the location query was performed against
  • result : The result of the location query. Consists of three attributes; ‘coordinateX’ [decimal], ‘coordinateY’ [decimal], and ‘circularAreaRadius’

Response Schema

JSON Format(default schema)

{
  "aerialink": {
    "version": "v4",
    "resource": "locations",
    "method": "get",
    "type": "synchronous",
    "guid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "destination": "1xxxyyyzzzz",
    "result": {
    "coordinateX": "0 0 0.000 N",
    "coordinateY": "0 0 0.000 N",
    "circularAreaRadius": "0.0"
    }
  }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>locations</resource>
 <method>get</method>
 <type>synchronous</type>
      <guid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</guid>
 <destination>1xxxyyyzzzz</destination>
 <result>
     <coordinateX>0 0 0.000 N</mnc>
     <coordinateY>0 0 0.000 N</ocn>
     <circularAreaRadius>0.0</operator>
 </result>
</aerialink>

Request (Asynchronous)

  • Note: Callback-only

Aerialink expects to receive an HTTP status code of 200 from your application server which confirms your receipt of the HTTP POST. If we do not receive this HTTP status code our network will continue to retry the callback to your application until the pre-defined expiration period.

Method [POST] : Subscribe User

This method subscribes a mobile number to allow the physical geographic location of their device to be pinged. The request is initiated by your application.

Request

The following request parameters are available for this resource and method

Required Parameters

  • source [string(15)]
    The source code which will be used for location services, to which the end-user will subscribe when agreeing to have their device located.

  • destination [varchar(15)]
    The destination mobile number that you wish to subscribe for mobile device location, provided in international format excluding the plus sign. (e.g. 1xxxyyyzzzz for a U.S. number.)

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

  • version [string] : The requested version of the resource
  • resource [string] : The requested resource name
  • method [string] : The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
  • type [string] : The request type; Syncronous or Asyncronous
  • guid [string] : The globally unique transaction ID for the LBS ping
  • destination [string] : The destination mobile number that the location query was performed against
  • result : The result of the location query. Consists of three attributes; ‘coordinateX’ [decimal], ‘coordinateY’ [decimal], and ‘circularAreaRadius’

Response Schema

JSON Format(default schema)

{
  "aerialink": {
    "version": "v4",
    "resource": "locations",
    "method": "post",
    "type": "synchronous",
    "result": {
    "User has been opted in successfully."
    }
  }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>locations</resource>
 <method>post</method>
 <type>synchronous</type>
 <result>The user has been opted in successfully.</result>
</aerialink>

Request (Asynchronous)

  • Note: Callback-only

Aerialink expects to receive an HTTP status code of 200 from your application server which confirms your receipt of the HTTP POST. If we do not receive this HTTP status code our network will continue to retry the callback to your application until the pre-defined expiration period.

Method [DELETE] : Unsubscribe User

This method unsubscribes a mobile number from allowing the physical geographic location of their device to be pinged. The request is initiated by your application.

Request

The following request parameters are available for this resource and method

Required Parameters

  • source [string(15)]
    The source code which will is used for location services, to which the end-user is currently subscribed and from which you wish to unsubscribe them from device location.

  • destination [varchar(15)]
    The destination mobile number that you wish to unsubscribe from mobile device location, provided in international format excluding the plus sign. (e.g. 1xxxyyyzzzz for a U.S. number.)

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

  • version [string] : The requested version of the resource
  • resource [string] : The requested resource name
  • method [string] : The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
  • type [string] : The request type; Syncronous or Asyncronous
  • guid [string] : The globally unique transaction ID for the LBS ping
  • destination [string] : The destination mobile number that the location query was performed against
  • result : The result of the location query. Consists of three attributes; ‘coordinateX’ [decimal], ‘coordinateY’ [decimal], and ‘circularAreaRadius’

Response Schema

JSON Format(default schema)

{
    "aerialink": {
        "version": "v4",
        "resource": "locations",
        "method": "delete",
        "type": "synchronous",
        "result": {
        "User has been opted out successfully."
        }
    }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>locations</resource>
 <method>delete</method>
 <type>synchronous</type>
 <result>The user has been opted out successfully.</result>
</aerialink>

This page was last updated 1515185923000