{ "openapi": "3.0.1", "info": { "title": "Device location API", "description": "The device location API allows you to access the coarse location of a device that is active on your network.\n\n**Note:** You must have an active subscription in order to view the base URL.", "version": "1.0.0" }, "tags": [ { "name": "Location" } ], "paths": { "/locationCheck": { "post": { "tags": [ "Location" ], "summary": "Get Location", "description": "Returns location details about a specified SIM.", "operationId": "getLocation", "parameters": [ { "name": "Authorization", "in": "header", "description": "Your [access token](/documentation-hub/fundamentals/authentication/authentication-coding-apis#request-id-and-access-tokens).", "required": true, "schema": { "type": "string" }, "example": "eyJraWQiOiJmYjk3ZGQxZi0xMDUzLTRiZGEtYjQ2OC1lZjU3ODdmZTA1MTMiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0bW9uLWpyNElVT25jeU9lTWRZdIiwiYXVkIjoidG1vbi1qcjRJVU9uY3lPZU1kWXdDSzFyUUd1V0RWWlpvUEFwVCIsImlzcyI6Imh0dHBzOlwvXC9hcGlzLnQtbW9iaWxlLmNvbVwvb2F1dGgyXC92MSIsImV4cCI6MTY3OTM1OTAwNCwiaWF0IjoxNjc5MzU1NDA0LemdgdhdspEeeSMNDW0.2emmeePL0239memmemIifQ.csRgOWOgRjwlY_K35hSd22SNqTS_wnSPLpXNcnh2uDxi3_wMaGmpEdv4g_EYnrfBkgbZrLam6o9dTfTmxXmx9kaSs2gAfQjq_lmTsTwMQppnCbqZ8YmRAtu9dj3mLlNKYg8aBEJnk6NxdDf5Z980k2xfUFeyNlhkrhwt3HToEPTIbspnzNgh3GEEdbwvWY8CD7gplIVHsDyWgz8cnzfL98oAuGsQLP3qnTN8oiOYJYUWdNLUxXyxgzDKpVli6WMK631phGbi2dXziY7Qz0YRQPf2fD9Da2jjNKEmfx3v9OqN2WO3YC261cJuWyd41drh2L5HiHLUxois3fHXyfNOA" }, { "name": "X-Authorization", "in": "header", "description": "Your [PoP Token](/documentation-hub/fundamentals/authentication/authentication-coding-apis#create-a-pop-token).", "required": true, "schema": { "type": "string" }, "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlZHRzIjoiUp6MTl4OFo4TEJMYTBPS3pZWVRNSnpKMldKNE5YNGppoiuyrtdfswdACHFBNJHG,..JBB,JJFDWQFtVnI4OCIsInYiOiIxIiwiZXhwIjoxNjc5MzU1NTM1LCJlaHRzIjoiQ29udGVudC1UeXBlO0F1dGhvcml6YXRpb247dXJpO2h0dHAtbWV0aG9kO2JvZHkiLCJpYXQiOjE2NzkzNTU0M228ccccbgjvjrehdhYzAtZDVkMC1hNGZiLThlMTkuSUJq3IDCMG6dOPPiFQao288sjndh_5IBWHk3mD_iZZatz7B_S_qC6kfsuoBoQC0TckwTTb7kB51HJ-Z2GXpGjweDwT_oVf0w0IyvQg4b61TBU29GeTOu21UdG0hemUHfJEiiCIZNeeb9GoSifxKuuwKdeSiXAU1OqKnjcB3mbYQVsgivC7wduLUt5B70w9x5cx002xFNa_C2EMWZGhOUJafsN8UhNDdjBWQOrjEK5g9br4bBBowQQMnPIRI5JC4PiPwTCFHbki4MSZlKSjoCqZhjlnOdNcLU765iLdE_jbSazqP34glN1RTw" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLocation" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "iccid": { "$ref": "#/components/schemas/Iccid" }, "msisdn": { "type": "string", "description": "The device's [MSSIDN](https://en.wikipedia.org/wiki/MSISDN).", "example": "17197158760" }, "distanceUnit": { "type": "string", "description": "The distance's unit of measurement.", "example": "meter" }, "longitude": { "type": "string", "description": "The longitude of the cell tower's location.", "example": "39.122819" }, "latitude": { "type": "string", "description": "The latitude of the cell tower's location.", "example": "-104.866133" }, "shape": { "type": "string", "description": "The shape of the estimated area in which the SIM is located.", "example": "CircularArea" }, "radius": { "type": "string", "description": "The area's radius.", "example": "468" }, "cellid": { "type": "string", "description": "The location's cell tower ID.", "example": "6490371" }, "timestamp": { "type": "string", "description": "The date and time the location was received from the application.\n\n**Timezone:** GMT", "format": "YYYYMMDDHHMMSS", "example": "20220324202805" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "System Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "DeviceLocation": { "type": "object", "properties": { "iccid": { "$ref": "#/components/schemas/Iccid" }, "horizontalPrecision": { "type": "string", "description": "The location's level of precision.

`AREA`: Accurate within 14001 meters

", "enum": [ "AREA" ], "example": "AREA" }, "respTimeOut": { "type": "string", "description": "The response time out, in seconds. \n\n**Maximum:** 50", "example": "30", "maximum": 50 }, "maxCacheAge": { "type": "string", "description": "The maximum cache age, in seconds. \n\nBy comparing the cache with `maxCacheAge` you can tell whether the information was retrieved from the server or from the cache:

cache > `maxCacheAge`: Information is sent from the server
cache < `maxCacheAge`: Information is sent from the cache

\n\n**Maximum:** 900", "example": "300", "maximum": 900 } }, "required": [ "iccid", "horizontalPrecision", "respTimeOut", "maxCacheAge" ] }, "Error": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "reasonCode", "systemMessage", "userMessage" ], "properties": { "reasonCode": { "type": "string", "example": "ERR-1031" }, "systemMessage": { "type": "string", "example": "Internal Server Error" }, "userMessage": { "type": "string", "example": "Trying to parse input that is malformed or otherwise invalid" }, "subReason": { "type": "object" } } } } } }, "Iccid": { "type": "string", "description": "The SIM card's ICCID. The ICCID is 19-20 characters long and is both stored digitally and engraved in the SIM card's body.", "example": "891004234814455936" } } } }

Location API

To get started, you need:

An active DevEdge account

A DevEdge IoT Developer KIt or SIM Starter Kit

An active subscription for the Device Location API

Your API keys

Getting Started

Additional Resources

Did you find what you were looking for?