GSMA

GSMA Location Retrieval API

Retrieve the location of a device

Documentation GitHub OpenAPI

Operations 1

POST /retrieve Execute location retrieval for a user device #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/gsma-location-retrieval-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Device Location Retrieval API
  description: This API provides the ability to retrieve a device location.
  version: wip
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: 0.8.0
servers:
- url: '{apiRoot}/location-retrieval/vwip'
  variables:
    apiRoot:
      default: http://localhost:9091
      description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
tags:
- name: Location Retrieval
  description: Retrieve the location of a device
paths:
  /retrieve:
    post:
      tags:
      - Location Retrieval
      summary: Execute location retrieval for a user device
      description: Retrieve the area where a certain user device is localized.
      operationId: retrieveLocation
      parameters:
      - $ref: ../common/CAMARA_common.yaml#/components/parameters/x-correlator
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalLocationRequest'
            examples:
              INPUT_PHONE_NUMBER_MAX_AGE:
                summary: Phone number and maxAge
                description: Retrieve location for a device identified by a phone number, providing a maxAge
                value:
                  device:
                    phoneNumber: '+123456789'
                  maxAge: 120
              INPUT_PHONE_NUMBER_MAX_AGE_AND_SURFACE:
                summary: Phone number, maxAge and maxSurface
                description: Retrieve location for a device identified by a phone number, providing a maxAge and maxSurface
                value:
                  device:
                    phoneNumber: '+123456789'
                  maxAge: 120
                  maxSurface: 1000000
              INPUT_IP_ADDRESS_V4:
                summary: IPv4 address without maxAge
                description: Retrieve location for a device identified by an IPv4 address, without an indication for maxAge
                value:
                  device:
                    ipv4Address:
                      publicAddress: 123.234.1.2
                      publicPort: 1234
              INPUT_NO_DEVICE_AND_MAX_AGE:
                summary: Device not provided, only maxAge
                description: The device has to be deducted from token
                value:
                  maxAge: 120
              INPUT_PHONE_NUMBER_IP_ADDRESS_V4:
                summary: Both phone number and IPv4 address, without maxAge
                description: Retrieve location for a device identified both by a phone number and an IPv4 address, without an indication for maxAge
                value:
                  device:
                    phoneNumber: '+123456789'
                    ipv4Address:
                      publicAddress: 123.234.1.2
                      publicPort: 1234
      responses:
        '200':
          description: Location retrieval result
          headers:
            x-correlator:
              $ref: ../common/CAMARA_common.yaml#/components/headers/x-correlator
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
              examples:
                LOCATION_CIRCLE:
                  $ref: '#/components/examples/RETRIEVAL_CIRCLE'
                LOCATION_POLYGON:
                  $ref: '#/components/examples/RETRIEVAL_POLYGON'
                LOCATION_CIRCLE_WITH_DEVICE:
                  $ref: '#/components/examples/LOCATION_CIRCLE_WITH_DEVICE'
        '400':
          $ref: ../common/CAMARA_common.yaml#/components/responses/Generic400
        '401':
          $ref: ../common/CAMARA_common.yaml#/components/responses/Generic401
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/RetrieveLocationNotFound404'
        '422':
          $ref: '#/components/responses/RetrieveLocationUnprocessableEntity422'
      security:
      - openId:
        - location-retrieval:read
components:
  responses:
    RetrieveLocationNotFound404:
      description: Not found
      headers:
        x-correlator:
          $ref: ../common/CAMARA_common.yaml#/components/headers/x-correlator
      content:
        application/json:
          schema:
            allOf:
            - $ref: ../common/CAMARA_common.yaml#/components/schemas/ErrorInfo
            - type: object
              properties:
                status:
                  enum:
                  - 404
                code:
                  enum:
                  - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              summary: Identifier not found
              description: Some identifier cannot be matched to a device
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Device identifier not found.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: ../common/CAMARA_common.yaml#/components/headers/x-correlator
      content:
        application/json:
          schema:
            allOf:
            - $ref: ../common/CAMARA_common.yaml#/components/schemas/ErrorInfo
            - type: object
              properties:
                status:
                  enum:
                  - 403
                code:
                  enum:
                  - PERMISSION_DENIED
          examples:
            GENERIC_403_PERMISSION_DENIED:
              summary: Permission denied
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
    RetrieveLocationUnprocessableEntity422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: ../common/CAMARA_common.yaml#/components/headers/x-correlator
      content:
        application/json:
          schema:
            allOf:
            - $ref: ../common/CAMARA_common.yaml#/components/schemas/ErrorInfo
            - type: object
              properties:
                status:
                  enum:
                  - 422
                code:
                  enum:
                  - SERVICE_NOT_APPLICABLE
                  - MISSING_IDENTIFIER
                  - UNSUPPORTED_IDENTIFIER
                  - UNNECESSARY_IDENTIFIER
                  - LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
                  - LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_SURFACE
                  - LOCATION_RETRIEVAL.UNABLE_TO_LOCATE
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              summary: Service not applicable
              description: Service not applicable for the provided identifier
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not available for the provided identifier.
            GENERIC_422_MISSING_IDENTIFIER:
              summary: Missing identifier
              description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: The device cannot be identified.
            GENERIC_422_UNSUPPORTED_IDENTIFIER:
              summary: Unsupported identifier
              description: None of the provided identifiers is supported by the implementation
              value:
                status: 422
                code: UNSUPPORTED_IDENTIFIER
                message: The identifier provided is not supported.
            GENERIC_422_UNNECESSARY_IDENTIFIER:
              summary: Unnecessary identifier
              description: An explicit identifier is provided when a device or phone number has already been identified from the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: The device is already identified by the access token.
            LOCATION_RETRIEVAL_422_UNABLE_TO_FULFILL_MAX_AGE:
              summary: Unable to fulfill maxAge
              description: The system is not able to provide the fresh location required by the client
              value:
                status: 422
                code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE
                message: Unable to provide expected freshness for location
            LOCATION_RETRIEVAL_422_UNABLE_TO_FULFILL_MAX_SURFACE:
              summary: Unable to fulfill maxSurface
              description: The system is not able to provide accurate acceptable surface required by the client
              value:
                status: 422
                code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_SURFACE
                message: Unable to provide accurate acceptable surface for location
            LOCATION_RETRIEVAL_422_UNABLE_TO_LOCATE:
              summary: Unable to locate device
              description: The network cannot locate the device
              value:
                status: 422
                code: LOCATION_RETRIEVAL.UNABLE_TO_LOCATE
                message: The network is unable to locate the device
  schemas:
    Location:
      type: object
      description: Device location
      required:
      - lastLocationTime
      - area
      properties:
        lastLocationTime:
          $ref: '#/components/schemas/LastLocationTime'
        area:
          $ref: '#/components/schemas/Area'
        device:
          $ref: '#/components/schemas/DeviceResponse'
    DeviceResponse:
      $ref: ../common/CAMARA_common.yaml#/components/schemas/DeviceResponse
    RetrievalLocationRequest:
      description: Request to retrieve the location of a device. Device is not required when using a 3-legged access token, following the rules in the description.
      type: object
      properties:
        device:
          $ref: ../common/CAMARA_common.yaml#/components/schemas/Device
        maxAge:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Maximum age of the location information which is accepted for the location retrieval (in seconds). Absence of maxAge means "any age" and maxAge=0 means a fresh calculation.
        maxSurface:
          type: integer
          format: int32
          minimum: 1
          maximum: 2147483647
          description: Maximum surface in square meters which is accepted by the client for the location retrieval. Absence of maxSurface means "any surface size".
          example: 1000000
    Area:
      $ref: ../common/CAMARA_common.yaml#/components/schemas/Area
    LastLocationTime:
      description: Last date and time when the device was localized. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
      type: string
      format: date-time
      maxLength: 64
      example: '2023-09-07T10:40:52Z'
  examples:
    RETRIEVAL_CIRCLE:
      summary: circle-based device location retrieval
      description: The device is localized within a circle with a center at the specified coordinates and a radius of 800 meters.
      value:
        lastLocationTime: '2023-10-17T13:18:23.682Z'
        area:
          areaType: CIRCLE
          center:
            latitude: 45.754114
            longitude: 4.860374
          radius: 800
    LOCATION_CIRCLE_WITH_DEVICE:
      summary: circle-based device location retrieval, returning the device identifier used by the implementation
      description: The device is localized within a circle with a center at the specified coordinates and a radius of 800 meters. Response when the request used a 2-legged access token with multiple device identifiers, or possibly only a single device identifier.
      value:
        lastLocationTime: '2023-10-17T13:18:23.682Z'
        area:
          areaType: CIRCLE
          center:
            latitude: 45.754114
            longitude: 4.860374
          radius: 800
        device:
          phoneNumber: '+123456789'
    RETRIEVAL_POLYGON:
      summary: polygon-based device location retrieval
      description: The device is localized within a polygon delimited by the provided coordinates.
      value:
        lastLocationTime: '2023-10-17T13:18:23.682Z'
        area:
          areaType: POLYGON
          boundary:
          - latitude: 45.754114
            longitude: 4.860374
          - latitude: 45.753845
            longitude: 4.863185
          - latitude: 45.75249
            longitude: 4.861876
          - latitude: 45.751224
            longitude: 4.861125
          - latitude: 45.751442
            longitude: 4.859827
  securitySchemes:
    openId:
      description: OpenID Connect authentication
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
externalDocs:
  description: Project documentation at Camara
  url: https://github.com/camaraproject/DeviceLocation