---
title: "Location Retrieval API"
url: "https://developer.pxg.konera.com/apis/location-retrieval-0/versions/e3780db4-1bcc-4b92-be5f-6ab27b544cd5"
---

# Location Retrieval API

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Location Retrieval API","description":"CAMARA Location Retrieval API. Retrieves the geographic area where a device is currently located using network-based information.","version":"0.4.0"},"servers":[{"url":"https://api.pxg.konera.com/camara","description":"Production CAMARA API Gateway"}],"tags":[{"name":"Location Retrieval","description":"Device location retrieval APIs"}],"security":[{"OAuth2ClientCredentials":["location-retrieval.read"]}],"paths":{"/location-retrieval/v0.4/retrieve":{"post":{"tags":["Location Retrieval"],"summary":"Retrieve device location","description":"Retrieves the geographic area where a device is currently located. The returned area can be a circle or a polygon, depending on operator support.","operationId":"retrieveLocation","parameters":[{"name":"x-correlation-id","in":"header","required":false,"description":"Correlation ID for request tracing","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationRetrievalRequest"},"example":{"phoneNumber":"+14155550123","maxAgeSeconds":86400}}}},"responses":{"200":{"description":"Location retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationRetrievalResponse"},"example":{"location":{"type":"circle","center":{"latitude":37.3382,"longitude":-121.8863},"radiusMeters":500},"assessedAt":"2026-02-05T10:30:00Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://auth.konera.com/oauth2/token","scopes":{"location-retrieval.read":"Retrieve device location area"}}}}},"schemas":{"LocationRetrievalRequest":{"type":"object","required":["phoneNumber"],"properties":{"phoneNumber":{"type":"string","description":"MSISDN in E.164 format","example":"+919036499174"},"maxAgeSeconds":{"type":"integer","minimum":0,"nullable":true,"description":"Maximum acceptable age of the location information in seconds","example":300}}},"LocationRetrievalResponse":{"type":"object","required":["location","assessedAt"],"properties":{"location":{"oneOf":[{"$ref":"#/components/schemas/CircleArea"},{"$ref":"#/components/schemas/PolygonArea"}],"discriminator":{"propertyName":"type"}},"assessedAt":{"type":"string","format":"date-time","description":"Time when the location was assessed","example":"2026-02-05T10:30:00Z"}}},"CircleArea":{"type":"object","required":["type","center","radiusMeters"],"properties":{"type":{"type":"string","enum":["circle"]},"center":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double","example":12.9716},"longitude":{"type":"number","format":"double","example":77.5946}}},"radiusMeters":{"type":"number","format":"double","example":500}}},"PolygonArea":{"type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","minItems":3,"description":"List of polygon vertices","items":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"}}}}}},"Error":{"type":"object","required":["status","code","message"],"properties":{"status":{"type":"integer","example":400},"code":{"type":"string","example":"INVALID_ARGUMENT"},"message":{"type":"string","example":"Invalid request"}}}}}}
```