Search
K

Location Retrieval API

Overview

The Location Retrieval API returns the geographic area where a device is currently located using network-based information. The returned area can be a circle or a polygon.

  • Version: 0.4.0
  • Base URL: https://api.pxg.konera.com/camara
  • Path: /location-retrieval/v0.4/retrieve
  • OpenAPI: location-retrieval.json

Typical use cases

  • Safety and assistance – Retrieve approximate device area when a user requests emergency or roadside assistance.
  • Logistics and mobility – Validate that a courier/driver is in the expected service area.
  • Contextual experiences – Offer location‑based content or offers without requiring GPS permissions.

Security

  • OAuth2 Client Credentials
    • Token URL: https://auth.konera.com/oauth2/token
    • Scope: location-retrieval.read – Retrieve device location area

Headers

  • x-correlation-id (optional, string) – Correlation ID for request tracing.

Request

POST https://api.pxg.konera.com/camara/location-retrieval/v0.4/retrieve

Body schema: LocationRetrievalRequest

{
  "phoneNumber": "+919036499174",
  "maxAgeSeconds": 300
}

Fields

  • phoneNumber (string, required) – MSISDN in E.164 format.
  • maxAgeSeconds (integer, optional) – Maximum acceptable age of location information in seconds.

Responses

200 – Location retrieved successfully

Body schema: LocationRetrievalResponse

{
  "location": {
    "type": "circle",
    "center": {
      "latitude": 37.3382,
      "longitude": -121.8863
    },
    "radiusMeters": 500
  },
  "assessedAt": "2026-02-05T10:30:00Z"
}

location is one of:

  • CircleArea:
    • type = "circle"
    • center.latitude, center.longitude (numbers)
    • radiusMeters (number) – radius in meters.
  • PolygonArea:
    • type = "polygon"
    • coordinates (array of { latitude, longitude }) – at least 3 vertices.

assessedAt (string, date-time) – Time when location was assessed.

HTTP status codes

Standard Error schema with:

  • 200 OK – Location successfully retrieved.
  • 400 Bad Request – Invalid phone number or parameters.
  • 401 Unauthorized – Invalid/missing token.
  • 403 Forbidden – Caller not permitted to retrieve location.
  • 429 Too Many Requests – Rate limit exceeded.
  • 500 Internal Server Error – Unexpected server error.