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.

Descargar la especificación OpenAPI

Location retrieval

Retrieve the location of a device

Operaciones 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

Autenticación

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>

Cuerpo de la solicitud
Tipo de contenido
application/json

phone_number
string
Requerido
ejemplo+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
ejemplo604800

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.

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

Location retrieval result

Uno de
last_location_time
string(date-time)
Requerido
ejemplo2023-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
Requerido

Location object

type
string
Requerido
ejemploCIRCLE

Type of area

center
object
Requerido

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

latitude
number(double)
Requerido
Min-90
Max90

Latitude component of a location

longitude
number(double)
Requerido
Min-180
Max180

Longitude component of location

radius_meters
number
Requerido
Min1
ejemplo800

Distance from the center in meters

Ejemplo Respuesta»Circular area

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