openapi: 3.0.3 info: title: Global System for Mobile Communications GSMA Camara Project Device Location Retrieval API description: >- Device Location Retrieval API provides the ability to retrieve the location of a device. The retrieved area depends on the network conditions at the subscribers location. version: 0.3.0 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html x-camara-commonalities: 0.4.0 externalDocs: description: Project documentation at Camara url: https://github.com/camaraproject/DeviceLocation servers: - url: '{apiRoot}/location-retrieval/v0.3' variables: apiRoot: default: http://localhost:9091 description: API root tags: - name: Location Retrieval description: Retrieve the location of a device paths: /retrieve: post: tags: - Location Retrieval summary: Global System for Mobile Communications Execute location retrieval for a user equipment description: Retrieve the area where a certain user device is localized. operationId: retrieveLocation parameters: - $ref: '#/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_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 responses: '200': description: Location retrieval result headers: x-correlator: $ref: '#/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' '400': $ref: '#/components/responses/Generic400' '401': $ref: '#/components/responses/Generic401' '403': $ref: '#/components/responses/Generic403' '404': $ref: '#/components/responses/RetrieveLocationNotFound404' '422': $ref: '#/components/responses/RetrieveLocationUnprocessableEntity422' '500': $ref: '#/components/responses/Generic500' '503': $ref: '#/components/responses/Generic503' security: - openId: - location-retrieval:read components: securitySchemes: openId: description: OpenID Connect authentication type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration parameters: x-correlator: name: x-correlator in: header description: Correlation id for the different services schema: type: string headers: x-correlator: description: Correlation id for the different services schema: type: string schemas: 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: '#/components/schemas/Device' maxAge: type: integer 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. Device: description: > End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: $ref: '#/components/schemas/PhoneNumber' networkAccessIdentifier: $ref: '#/components/schemas/NetworkAccessIdentifier' ipv4Address: $ref: '#/components/schemas/DeviceIpv4Addr' ipv6Address: $ref: '#/components/schemas/DeviceIpv6Address' minProperties: 1 PhoneNumber: description: >- A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). 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' NetworkAccessIdentifier: description: >- A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string example: 123456789@domain.com DeviceIpv4Addr: type: object description: > The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. properties: publicAddress: $ref: '#/components/schemas/SingleIpv4Addr' privateAddress: $ref: '#/components/schemas/SingleIpv4Addr' publicPort: $ref: '#/components/schemas/Port' anyOf: - required: - publicAddress - privateAddress - required: - publicAddress - publicPort example: publicAddress: 84.125.93.10 publicPort: 59765 SingleIpv4Addr: description: A single IPv4 address with no subnet mask type: string format: ipv4 example: 84.125.93.10 Port: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 DeviceIpv6Address: description: > The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). type: string format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 Location: type: object description: Device location required: - lastLocationTime - area properties: lastLocationTime: description: >- Last date and time when the device was localized. It must follow RFC 3339 and must have time zone. Recommended 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 area: $ref: '#/components/schemas/Area' Area: description: Base schema for all areas type: object properties: areaType: $ref: '#/components/schemas/AreaType' required: - areaType discriminator: propertyName: areaType mapping: CIRCLE: '#/components/schemas/Circle' POLYGON: '#/components/schemas/Polygon' AreaType: type: string description: | Type of this area. CIRCLE - The area is defined as a circle. POLYGON - The area is defined as a polygon. enum: - CIRCLE - POLYGON Circle: description: Circular area allOf: - $ref: '#/components/schemas/Area' - type: object required: - center - radius properties: center: $ref: '#/components/schemas/Point' radius: type: number description: Distance from the center in meters minimum: 1 Polygon: description: Polygonal area allOf: - $ref: '#/components/schemas/Area' - type: object required: - boundary properties: boundary: $ref: '#/components/schemas/PointList' 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 ErrorInfo: description: Common schema for errors type: object required: - status - code - message properties: status: type: integer description: HTTP status code returned along with this error response code: type: string description: Code given to this error message: type: string description: Detailed error description responses: Generic400: description: Bad Request headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: >- Client specified an invalid argument, request body or query param. GENERIC_400_OUT_OF_RANGE: summary: Generic Out of Range description: >- Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested value: status: 400 code: OUT_OF_RANGE message: Client specified an invalid range. GENERIC_400_MAX_AGE_NOT_SATISFIABLE: value: status: 400 code: LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT message: maxAge threshold cannot be satisfied Generic401: description: Unauthorized headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_401_UNAUTHENTICATED: summary: Generic Unauthenticated description: Request cannot be authenticated value: status: 401 code: UNAUTHENTICATED message: >- Request not authenticated due to missing, invalid, or expired credentials. GENERIC_401_AUTHENTICATION_REQUIRED: summary: Generic Authentication Required description: New authentication is needed, authentication is no longer valid value: status: 401 code: AUTHENTICATION_REQUIRED message: New authentication is required. Generic403: description: Forbidden headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_403_PERMISSION_DENIED: summary: Generic 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. GENERIC_403_INVALID_TOKEN_CONTEXT: summary: Invalid access token context description: >- Reflects some inconsistency between information in some field of the API and the related OAuth2 Token value: status: 403 code: INVALID_TOKEN_CONTEXT message: '{{field}} is not consistent with access token.' RetrieveLocationNotFound404: description: Not found headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: LOCATION_RETRIEVAL_404_UNABLE_TO_LOCATE_DEVICE: summary: The location server is not able to locate the device description: The location server is not able to locate the device value: status: 404 code: LOCATION_RETRIEVAL.DEVICE_NOT_FOUND message: The location server is not able to locate the mobile GENERIC_404_DEVICE_NOT_FOUND: summary: Some identifier cannot be matched to a device description: >- One or more of the provided device identifiers do not match any device value: status: 404 code: DEVICE_NOT_FOUND message: No device found for a provided identifier RetrieveLocationUnprocessableEntity422: description: Unprocessable Entity headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: LOCATION_RETRIEVAL_422_UNABLE_TO_FULFILL_MAX_AGE: summary: Unable to provide expected frehsness description: >- Unable to provide expected frehsness for location retrieval request value: status: 422 code: LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE message: Unable to provide expected freshness for location GENERIC_422_UNPROCESSABLE_ENTITY: summary: Unprocessable entity description: >- The request was well-formed but was unable to be processed due to semantic errors or not applicable values. This is the generic error code for 422 responses. value: status: 422 code: UNPROCESSABLE_ENTITY message: 'Value not acceptable: ...' GENERIC_422_DEVICE_NOT_APPLICABLE: summary: Service not applicable to the device description: >- The provided device is not compatible with the requested operation, according to the service provider rules. value: status: 422 code: DEVICE_NOT_APPLICABLE message: The device is not applicable for the requested operation GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: summary: Device identifiers mismatch description: >- Several device identifiers are provided but do not match the same device value: status: 422 code: DEVICE_IDENTIFIERS_MISMATCH message: The provided device identifiers do not match the same device GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: summary: >- None of the provided device identifiers is supported by the implementation description: Message may list the supported device identifiers value: status: 422 code: UNSUPPORTED_DEVICE_IDENTIFIERS message: 'Supported device supported are: ...' GENERIC_422_UNIDENTIFIABLE_DEVICE: summary: No identifier provided description: No device identifier provided for the device to be located value: status: 422 code: UNIDENTIFIABLE_DEVICE message: A device must be provided Generic500: description: Internal server error headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_500_INTERNAL: summary: Generic Internal description: Problem in Server side. Regular Server Exception value: status: 500 code: INTERNAL message: Internal server error Generic503: description: Service Unavailable headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_503_UNAVAILABLE: summary: Generic Unavailable description: >- Service is not available. Temporary situation usually related to maintenance process in the server side value: status: 503 code: UNAVAILABLE message: Service Unavailable. 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 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