API Dashboard
Vonage.com
Pricing
Support
Documentation
Blog
Code Hub

Device Location Verification API

Introduction

The Device Location Verification API allows you to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by the a set of coordinates (latitude and longitude) and some expected accuracy (radius).

Please Note: Currently, the Device Location Verification API can only be used within the Sandbox environment using a Virtual CSP. See here for more information.

The verification result depends on the network's ability and accuracy to locate the device at the requested area.

  • If the network's estimation of the device's location is fully contained within the requested area, the verification result is TRUE.
  • If the network's estimation of the device's location does not overlap with the requested area at all, the verification result is FALSE .
  • If the network's estimation of the device's location partially overlaps with the requested area, or it fully contains the requested area (because it is larger), the result is 'PARTIAL'. In this case, a match_rate may be included in the response, indicating an estimation of the likelihood of the match in percent.
  • Lastly, the network may not be able to locate the device. In this case, the verification result is UNKNOWN.

You may also optionally include a maxAge indication. If the location information known to the server is older than the specified maxAge, the verification result will be UNKNOWN and the lastLocationTime attribute may indicate the last available time for the device location.

lastLocationTime will be always included in the response unless there is no historical location information available for the device. In this case, UNKNOWN will be returned without lastLocationTime.

Relevant terms and definitions

  • Device: A device refers to any physical entity that can connect to a network and participate in network communication.

  • Area: It specifies the geographical surface where a device may be physically located.

  • Verification: Process triggered in the API server to confirm or contradict the expectation assumed by the API client about the device location.

Download OpenAPI Specification

Location verification

Verification the location of a device

Available Operations

Verify the location of a device

Verify whether the location of a device is within a requested area. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent.

posthttps://api-eu.vonage.com/camara/location/v020/verify

Authentication

OAuth 2.0 (three_legged)

For detailed information on authentication with the Device Location Verification API, please refer to our authentication guide.

Scopes:
  • openid dpv:NotApplicable#location-verification:verify - Verify the location of a device.

Request Body
Content Type
application/json

device
object
Required

The phone number of the end-user device capable of connecting to a mobile network. Examples of such devices include smartphones or IoT sensors/actuators.

phoneNumber
string
example123456789

A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.

area
object
Required
areaType
string
Required

Type of this area. CIRCLE - The area is defined as a circle.

Must be one of:CIRCLE
center
object

Coordinates (latitude, longitude) defining a location in a map

latitude
number(double)
Required
Min-90
Max90
example50.735851

Latitude component of a location

longitude
number(double)
Required
Min-180
Max180
example7.10066

Longitude component of location

radius
integer
Min2000
Max200000

Expected accuracy for the verification in meters, from location (radius)

maxAge
integer
Min60
example120

The maximum age (in seconds) of the available location, which is accepted for the verification.

Example Request

{
   "device": {
      "phoneNumber": "123456789"
   },
   "area": {
      "areaType": "CIRCLE",
      "center": {
         "latitude": 50.735851,
         "longitude": 7.10066
      },
      "radius": 2000
   },
   "maxAge": 120
}

Responses
Content Type
application/json

Location verification result

lastLocationTime
string(date-time)
example2023-09-07T10:40:52Z

Timestamp of the last location information. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)

verificationResult
string
Required

Result of a verification request:

  • TRUE: when the network locates the device within the requested area,
  • FALSE: when the requested area does not match the area where the network locates the device,
  • UNKNOWN: when the network cannot locate the device,
  • PARTIAL: when the requested area partially match the area where the network locates the device. A match_rate could be included in the response.
Must be one of:TRUEFALSEUNKNOWNPARTIAL
matchRate
integer
Min1
Max99

Estimation of the match rate between the area in the request (R), and area where the network locates the device (N), calculated as the percent value of the intersection of both areas divided by the network area, that is (R ∩ N) / N * 100. Included only if VerificationResult is PARTIAL.

Example Response

{
   "lastLocationTime": "2023-09-07T10:40:52Z",
   "verificationResult": "TRUE",
   "matchRate": 1
}