Device Location Retrieval

This API provides the ability to retrieve the area where a certain user device is located.

The area provided in the response could be described:

  • by a circle determined by coordinates (latitude and longitude) and a radius.
  • by a simple polygon delimited by segments connecting consecutively an array of coordinates (points). The last point connects to the first point to delimit a closed shape bounded with straight sides.

The retrieved shape depends on the network conditions at the device's location and any of the supported shapes could be received.

The requester could optionally ask for a freshness of the location information by providing a location_age_seconds ("I want a location not older than 600 seconds").

The result accuracy depends on the network's ability and accuracy to locate the device.

Additionally to location information, the answer will also provide indication about the location time.

Télécharger la spécification OpenAPI

Location retrieval

Retrieve the location of a device

Opérations disponibles

Retrieve the location of a user’s mobile device based on their phone number

Retrieve the location of a user's mobile device

posthttps://api-eu.vonage.com/v0.1/location/retrieval

Authentification

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>

Corps de la demande
Type de contenu
application/json

phone_number
string
Exigée
exemple+123456789

A public identifier addressing a telephone subscription. In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.

location_age_seconds
integer
exemple604800

Maximum age of the location information which is accepted for the location retrieval (in seconds). Absence of location_max_seconds means "any age" and location_max_seconds=0 means a fresh calculation.

Exemple Demande

{
   "phone_number": "+123456789",
   "location_age_seconds": 604800
}

Réponses
Type de contenu
application/json

Location retrieval result

L'un des
last_location_time
string(date-time)
Exigée
exemple2023-10-17T13:18:23.682Z

Last date and time when the device was located. It follows the RFC 3339 including the time zone. The 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)

location
object
Exigée

Location object

type
string
Exigée
exempleCIRCLE

Type of area

center
object
Exigée

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

latitude
number(double)
Exigée
Min-90
Max90

Latitude component of a location

longitude
number(double)
Exigée
Min-180
Max180

Longitude component of location

radius_meters
number
Exigée
Min1
exemple800

Distance from the center in meters

Exemple Réponse»Circular area

{
   "last_location_time": "2023-10-17T13:18:23.682Z",
   "location": {
      "type": "CIRCLE",
      "center": {
         "latitude": 50.735851,
         "longitude": 7.10066
      },
      "radius_meters": 800
   }
}