Location API Suite
Location is a valuable tool in maximizing the monitization of traffic while minimizing risk. There are a two different types of location lookups that are available to Pesology Clients today. These are: AGPS Cell-ID.
AGPS or Assisted GPS
Device-assisted mode, the user provides positioning measurements, which the network uses to calculate the users location. It uses activated GPS chipsets in the user device Networks- assisted satellite tracking. Device must be set to “LBS on” mode.
ACCURACY: In general, A-GPS provides the highest accuracy of any network-enabled technique, often within 50m under good conditions.
Cell-ID
Network centric technology. The phone takes readings from nearby cellular towers to determine location. Works with any cellular phone.
ACCURACY: Average accuracy distance is 800m. May achieve a precision of down to 50m in urban areas
For a more summary comparison of GPS Methods please see the below chart:
For a more comprehensive article on the subject of GPS types, please follow this link: Gps
Pesology has four APIs which are used to manage the location request process.
optIn: A user must first “opt in” in your systems IVR flow by calling the optIn Method as described below, to be able to use the service.
optOut: is called to opt out a consumer.
checkOptInStatus: is called to check the current Opt in status.
location: returns a users location.
NOTE: Currently only US mobile subscribers look ups are supported
INTEGRATION AND USE
Flow Sequence:
APIs
Note: the flow in your IVR must check the status of a consumer’s opt status before requesting a location look up. If the opt status is anything other then “0” you must either opt them in or honor their request not request a look up.
optIn
This API is used to add a subscriber who has consented to the location terms conditions to the “opted in” list. Only opted-in subscribers can be located. Upon opting in a subscriber the end-user is sent a text message notifying them of their enrollment into location services. Clients are expected to maintain proof of collection of consent in case of a audit.
Request Parameters
| Name | Matory | Format | Description |
|---|---|---|---|
| usr | Matory | String | This value is your username. |
| pwd | Matory | String | This value is your API password |
| accountId | Matory | String | Any of your Active Account Id. |
| requestId | Matory | String | Used as a client-specified correlation ID used for traceability auditing purposes. |
| msisdn | Matory | String | Customer phone number that has opted into location services. |
Response Codes
0 - Success 1000 or 1001 - Invalid User API or Password API 1002 - User inactive 1005 - Sorry, this Account has been disabled by the moment M-001 - Missing MSISDN M-002 - Invalid MSISDN R-001 - Missing requestId 2002 - Subscriber Already Opted In 9999 - External Provider Error
Request
GET /Api/optIn/usr/youruser@mail.com/pwd/bab87e2f6362155dd839a8702e709537/accountId/1/msisdn/8015551210/requestId/abc123 HTTPS/1.1 Host: api.pesology.com Connection: keep-alive
Response
HTTP/1.1 200 OK
Date: Thu, 13 Mar 2014 19:21:14 GMT
Server: Apache/2.2.22 (Ubuntu)
Content-Length: 57
Keep-Alive: timeout=7, max=100
Connection: Keep-Alive
Content-Type: text/html
{"statusDescription":"Success","status":0}
optOut
This API is used to remove a subscriber who ask to be opted out of the location terms conditions. Upon opting out, the end-user is sent a text message notifying them of removal of location services.
Request Parameters
| Name | Matory | Format | Description |
|---|---|---|---|
| usr | Matory | String | This value is your username. |
| pwd | Matory | String | This value is your API password |
| accountId | Matory | String | Any of your Active Account Id. |
| requestId | Matory | String | Used as a client-specified correlation ID used for traceability auditing purposes. |
| msisdn | Matory | String | Customer phone number that has opted out of location services. |
Response Codes
0 - Success 1000 or 1001 - Invalid User API or Password API 1002 - User inactive 1005 - Sorry, this Account has been disabled by the moment M-001 - Missing MSISDN M-002 - Invalid MSISDN R-001 - Missing requestId 9999 - External Provider Error
Request
GET /Api/optOut/usr/youruser@mail.com/pwd/bab87e2f6362155dd839a8702e709537/accountId/1/msisdn/8015551210/requestId/abc123 HTTPS/1.1 Host: api.pesology.com Connection: keep-alive
Response
HTTP/1.1 200 OK
Date: Thu, 13 Mar 2014 19:22:14 GMT
Server: Apache/2.2.22 (Ubuntu)
Content-Length: 57
Keep-Alive: timeout=7, max=100
Connection: Keep-Alive
Content-Type: text/html
{"statusDescription":"Success","status":0}
checkOptInStatus
This API is used to check if the specified subscriber is currently opted into location terms conditions.
Request Parameters
| Name | Matory | Format | Description |
|---|---|---|---|
| usr | Matory | String | This value is your username. |
| pwd | Matory | String | This value is your API password |
| accountId | Matory | String | Any of your Active Account Id. |
| requestId | Matory | String | Used as a client-specified correlation ID used for traceability auditing purposes. |
| msisdn | Matory | String | Customer phone number to query for location services opt-in status. |
Response Codes
0 - Opted In 1 - Not Opted In 1000 or 1001 - Invalid User API or Password API 1002 - User inactive 1005 - Sorry, this Account has been disabled by the moment M-001 - Missing MSISDN M-002 - Invalid MSISDN R-001 - Missing requestId 9999 - External Provider Error
Request
GET /Api/checkOptInStatus/usr/youruser@mail.com/pwd/bab87e2f6362155dd839a8702e709537/accountId/1/msisdn/8015551210/requestId/abc123 HTTPS/1.1 Host: api.pesology.com Connection: keep-alive
Response
HTTP/1.1 200 OK
Date: Thu, 13 Mar 2014 19:22:14 GMT
Server: Apache/2.2.22 (Ubuntu)
Content-Length: 57
Keep-Alive: timeout=7, max=100
Connection: Keep-Alive
Content-Type: text/html
{"statusDescription":"Opted In","status":0}
location
This API is used to retrieve the current location of a mobile subscriber. The subscriber being queried must be opted in prior to retrieving their location.
Request Parameters
| Name | Matory | Format | Description |
|---|---|---|---|
| usr | Matory | String | This value is your username. |
| pwd | Matory | String | This value is your API password |
| accountId | Matory | String | Any of your Active Account Id. |
| requestId | Matory | String | Used as a client-specified correlation ID used for traceability auditing purposes. |
| msisdn | Matory | String | Customer phone number to query for location. |
| requestType | Oprional | Int | If not sent will do Cell-ID lookup, if “1” is sent, Pesology will perform A-GPS lookup |
Response Codes
0 - Success 1000 or 1001 - Invalid User API or Password API 1002 - User inactive 1005 - Sorry, this Account has been disabled by the moment M-001 - Missing MSISDN M-002 - Invalid MSISDN R-001 - Missing requestId 2001 - Subscriber Location Unavailable 2003 - Subscriber Is Not Opted In 9999 - External Provider Error
Request
https://api.pesology.com/Api/location/usr/youruser@mail.com/pwd/bab87e2f6362155dd839a8702e709537/accountId/1/msisdn/8015551210/requestId/abc123https://api.pesology.com/Api/optIn/usr/youruser@mail.com/pwd/bab87e2f6362155dd839a8702e709537/accountId/1/msisdn/8015551210/requestId/abc123/requestType/1
GET /Api/location/usr/youruser@mail.com/pwd/bab87e2f6362155dd839a8702e709537/accountId/1/msisdn/8015551210/requestId/abc123 HTTPS/1.1 Host: api.pesology.com Connection: keep-alive
Response
HTTP/1.1 200 OK
Date: Thu, 13 Mar 2014 19:22:14 GMT
Server: Apache/2.2.22 (Ubuntu)
Content-Length: 57
Keep-Alive: timeout=7, max=100
Connection: Keep-Alive
Content-Type: text/html
{"statusDescription":"Success","status":0,"latitude":34.754501388889,"longitude":-117.39456944444,"radius":0}
