{ "openapi": "3.0.3", "info": { "title": "Device Location Retrieval", "description": "This API provides the ability to retrieve the area where a certain user device is located.\n\nThe area provided in the response could be described:\n\n- by a circle determined by coordinates (latitude and longitude) and a radius.\n- 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.\n\nThe retrieved shape depends on the network conditions at the device's location and any of the supported shapes could be received.\n\nThe 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\").\n\nThe result accuracy depends on the network's ability and accuracy to locate the device.\n\nAdditionally to location information, the answer will also provide indication about the location time.\n", "version": "0.3.0", "contact": { "name": "Vonage Developer Relations", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "x-metaTitle": "Vonage Device Location Retrieval API Reference | Vonage API Documentation" }, "externalDocs": { "description": "Project documentation at Camara", "url": "https://github.com/camaraproject/DeviceLocation" }, "servers": [ { "url": "https://api-eu.vonage.com/v0.1/location/" } ], "tags": [ { "name": "Location retrieval", "description": "Retrieve the location of a device" } ], "paths": { "/retrieval": { "post": { "tags": [ "Location retrieval" ], "summary": "Retrieve the location of a user’s mobile device based on their phone number", "description": "Retrieve the location of a user's mobile device", "operationId": "retrieveLocation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalLocationRequest" } } } }, "responses": { "200": { "description": "Location retrieval result", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Circle" }, { "$ref": "#/components/schemas/Polygon" } ] } } } }, "400": { "$ref": "#/components/responses/Generic400" }, "401": { "$ref": "#/components/responses/Generic401" }, "403": { "$ref": "#/components/responses/Generic403" }, "404": { "$ref": "#/components/responses/LocationNotFound404" }, "415": { "$ref": "#/components/responses/Generic415" }, "500": { "$ref": "#/components/responses/Generic500" }, "503": { "$ref": "#/components/responses/Generic503" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "RetrievalLocationRequest": { "description": "Request to retrieve the location of a phone number of an end-user device capable of connecting to a mobile network.", "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "description": "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 '+'.", "type": "string", "pattern": "^\\+[1-9][0-9]{4,14}$", "example": "+123456789" }, "location_age_seconds": { "description": "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.", "type": "integer", "example": 604800 } } }, "LastLocationTime": { "type": "object", "properties": { "last_location_time": { "description": "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)", "type": "string", "format": "date-time", "example": "2023-10-17T13:18:23.682Z" } } }, "LocationCircle": { "type": "object", "description": "Location object", "required": [ "type", "center", "radius_meters" ], "properties": { "type": { "type": "string", "description": "Type of area", "example": "CIRCLE" }, "center": { "$ref": "#/components/schemas/Point" }, "radius_meters": { "type": "number", "description": "Distance from the center in meters", "minimum": 1, "example": 800 } } }, "LocationPolygon": { "type": "object", "description": "Location object", "required": [ "type", "boundary" ], "properties": { "type": { "type": "string", "description": "Type of area", "example": "POLYGON" }, "boundary": { "$ref": "#/components/schemas/PointList" } } }, "Circle": { "description": "Circular area", "required": [ "last_location_time", "location" ], "allOf": [ { "$ref": "#/components/schemas/LastLocationTime" }, { "type": "object", "properties": { "location": { "$ref": "#/components/schemas/LocationCircle" } } } ] }, "Polygon": { "description": "Polygonal area", "required": [ "last_location_time", "location" ], "allOf": [ { "$ref": "#/components/schemas/LastLocationTime" }, { "type": "object", "properties": { "location": { "$ref": "#/components/schemas/LocationPolygon" } } } ] }, "PointList": { "description": "List of points defining a polygon", "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 3, "maxItems": 15 }, "Point": { "type": "object", "description": "Coordinates (latitude, longitude) defining a location in a map", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "$ref": "#/components/schemas/Latitude" }, "longitude": { "$ref": "#/components/schemas/Longitude" } }, "example": { "latitude": 50.735851, "longitude": 7.10066 } }, "Latitude": { "description": "Latitude component of a location", "type": "number", "format": "double", "minimum": -90, "maximum": 90 }, "Longitude": { "description": "Longitude component of location", "type": "number", "format": "double", "minimum": -180, "maximum": 180 }, "ErrorResponse": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "title", "detail" ] } }, "responses": { "Generic400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Generic401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Generic403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Generic415": { "description": "Invalid Content-Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "LocationNotFound404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Generic500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Generic503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }