Location Services

Location Services capabilities allow service providers to retrieve the geographical position of a mobile device using network-level information. Unlike GPS-based location, which requires application-level access and can be spoofed, operator-provided location is derived from network infrastructure and is typically harder to spoof, reflecting the device’s location as observed by the operator within its coverage area.

These capabilities are part of the CAMARA standard and require explicit user authorization before any location data is shared.

Location Retrieval

What it does: Provides the geographical area where a device is currently located, either as a circle (coordinates and radius) or as a polygon (closed shape defined by coordinate points).

When a service provider requests location retrieval, the operator determines the device’s position based on network signals and returns an area that represents the device’s location. The shape and precision of this area depend on network conditions, cell tower density, and the accuracy capabilities available at that moment.

The service provider can optionally specify constraints:

• Maximum age (maxAge): How fresh the location must be (e.g., “no older than 600 seconds”)
• Maximum surface (maxSurface): The largest acceptable area size (e.g., “no larger than 1,000,000 square meters”)

If the operator cannot meet these constraints, the API returns an error indicating which requirement could not be satisfied.

Who benefits:

• Financial services: Fraud prevention by verifying that a user is located in a region authorized for transactions
• Content delivery platforms: Ensuring GPS coordinates reported by an app are accurate and have not been faked to bypass regional restrictions
• Advertising networks: Contextual targeting by confirming a device is within a specific area of interest before serving location-based ads
• Mobility services: Vehicle and bike rental platforms retrieving the actual location of a device to verify it is in the expected location at the start or end of a rental
• Delivery and logistics: Confirming driver location for route optimization and real-time tracking

Why it matters:

GPS coordinates can be falsified by the user through device settings, mock location apps, or GPS spoofing tools. Because location retrieval is provided by the operator based on network infrastructure, it is generally harder for the device owner to manipulate. This makes it a more reliable signal for security, compliance, and business logic decisions.

Additionally, many devices and applications do not have constant GPS access or permission. Location retrieval offers a network-level alternative that does not depend on the device exposing its GPS sensor to the application layer.

Response formats

Location is returned in one of two geometrical formats:

Circle:

• Center defined by latitude and longitude (WGS84 decimal degrees)
• Radius in meters indicating the area’s size
• Surface area calculated as π × radius²

Polygon:

• Closed shape defined by an ordered array of coordinate points
• Each point represented as latitude and longitude
• The last point implicitly connects back to the first point
• Surface area calculated based on the polygon’s boundary

The format returned depends on the network’s ability to determine location shape. Service providers must be prepared to handle either format.

Freshness and accuracy controls

Maximum Age (maxAge):

• Absence of maxAge means the service provider accepts location data of any age. The response will include lastLocationTime to indicate when the device was last located.
• maxAge=0 means a fresh, real-time calculation is required. If the operator cannot provide a fresh location, the API returns error 422 LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_AGE.
• If the operator has no location data at all, the API returns error 422 LOCATION_RETRIEVAL.UNABLE_TO_LOCATE.

Maximum Surface (maxSurface):

• Absence of maxSurface means the service provider accepts any area size.
• If the operator cannot provide an area smaller than the requested maxSurface, the API returns error 422 LOCATION_RETRIEVAL.UNABLE_TO_FULFILL_MAX_SURFACE.
• Some implementations define a minimum acceptable maxSurface (e.g., 10,000 square meters) to prevent requests for impractically precise locations.

If both maxAge and maxSurface constraints fail, the operator returns one of the two error codes based on which constraint was evaluated first.

Multi-SIM scenarios

In cases where a phone number is associated with multiple physical devices (e.g., a smartphone with a paired smartwatch), the API behavior depends on the operator’s implementation:

• Single device response: If one device is considered the primary SIM holder, the operator may return the location of that device only.
• Combined location: The operator may return a location area that encompasses all devices associated with the phone number.
• Error response: The operator may reject the request with an error indicating that multi-SIM scenarios are not supported for this API.

Service providers should check with the operator to understand the expected behavior. To make location retrieval more deterministic in multi-SIM scenarios, service providers can:

• Use the authorization code flow (three-legged token) to automatically identify the intended device
• Identify the device by unique attributes such as IP address and port
• Use a secondary phone number if one is associated with the specific device

Privacy and consent

Before using Location Retrieval, service providers must ensure:

• The user has been informed of the purpose for which their location will be accessed
• The user has explicitly consented to location access for that purpose
• The consent scope matches the API operation being invoked
• The processing complies with applicable data protection regulations (e.g., GDPR, CCPA)

Open Gateway enforces consent at the platform level. If a user has not consented or has revoked consent, location retrieval requests will fail with an authorization error, regardless of whether the service provider holds a valid access token.

Location Verification

What it does: Verifies whether a mobile device is currently located within a specified geographical area. Instead of returning the device’s coordinates, this capability provides a boolean-style verification result: is the device inside the requested area or not?

When a service provider requests location verification, they define a circular area (center coordinates and radius) and optionally specify how fresh the location data must be (maxAge). The operator evaluates the device’s network-derived location and returns one of four possible results:

• TRUE: The device is confirmed to be within the requested area
• FALSE: The device is confirmed to be outside the requested area
• UNKNOWN: The network cannot locate the device (e.g., device is offline, out of coverage, or location data is unavailable)
• PARTIAL: The device’s location area partially overlaps with the requested area. In this case, a matchRate percentage (1-99%) is included to indicate the degree of overlap.

The service provider can optionally specify:

• Maximum age (maxAge): How fresh the location must be (e.g., “no older than 120 seconds”). If omitted, the operator accepts location data of any age and includes lastLocationTime in the response.

If the operator cannot meet the maxAge constraint, the API returns an error indicating which requirement could not be satisfied.

Who benefits:

• Financial services: Real-time fraud detection by verifying a user is within an authorized region before approving a transaction, without needing to store precise coordinates
• Geofencing applications: Confirm whether a user has entered or exited a specific zone (e.g., retail store proximity, event venue, restricted area)
• Content delivery platforms: Verify regional compliance by checking if a device is within a content distribution zone, without processing exact GPS data
• Smart mobility: Confirm that a user is at a vehicle pickup or drop-off location without requiring the client app to share GPS coordinates
• Access control: Grant or deny access to services based on whether the user is physically present in an authorized location (e.g., on-campus services, regional promotions)
• Privacy-focused applications: Perform location checks without exposing the user’s exact position to the service provider

Why it matters:

Location verification provides a privacy-preserving alternative to location retrieval. Instead of receiving precise coordinates that must be processed and potentially stored, service providers get a simple yes/no answer to “is the device in this area?”

This approach:

• Reduces privacy exposure: The service provider never receives the device’s actual location, only a verification result
• Simplifies compliance: Less sensitive data to process means fewer data protection obligations
• Prevents location spoofing: Like location retrieval, verification is based on network infrastructure rather than device-reported GPS, making it harder to fake
• Optimizes decision-making: For use cases that only need to know “inside or outside this area,” verification is more efficient than retrieving and processing full coordinates

Because location verification relies on operator network data, it works even when the device has GPS disabled or is indoors where GPS signals are weak.

Verification results

The API returns one of four verification results:

TRUE:

• The network confirms the device is located within the requested area
• The device’s network-derived location falls entirely inside the circle defined by the center coordinates and radius

FALSE:

• The network confirms the device is located outside the requested area
• The device’s network-derived location does not overlap with the requested area at all

UNKNOWN:

• The network cannot determine the device’s location
• Possible causes: device is offline, out of coverage, airplane mode enabled, or location data is not available from the network
• Service providers should treat this as “unable to verify” rather than “verified to be outside”

PARTIAL:

• The device’s network-derived location area partially overlaps with the requested area
• This occurs when the network’s location precision is broader than the requested verification area, causing ambiguity
• A matchRate (1-99%) is included to indicate the percentage of overlap between the network’s location area and the requested area
• Service providers must decide whether to accept partial matches based on their risk tolerance and use case requirements

Request area format

Location verification currently supports circle areas only:

• Center: Defined by latitude and longitude (WGS84 decimal degrees)
• Radius: Distance in meters from the center point, indicating the expected accuracy
• Minimum radius: 1 meter
• Maximum radius: 200,000 meters (200 km)

Unlike location retrieval, which can return either a circle or polygon, location verification accepts only circular areas as input. This simplifies the verification logic and aligns with most geofencing and proximity use cases.

Freshness controls

Maximum Age (maxAge):

• Absence of maxAge: The service provider accepts location data of any age. The response includes lastLocationTime to indicate when the device was last located.
• maxAge=0: A fresh, real-time verification is required. If the operator cannot provide fresh location data, the API returns error 422 LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE.
• If the operator has no location data: The API returns verificationResult: UNKNOWN in the successful response (not an error), indicating the device could not be located.

If the operator cannot satisfy the maxAge constraint (i.e., the most recent location data is older than requested), the API returns an error rather than returning a potentially misleading verification result.

Multi-SIM scenarios

In cases where a phone number is associated with multiple physical devices (e.g., a smartphone with a paired smartwatch), the API behavior depends on the operator’s implementation:

• Single device verification: If one device is considered the primary SIM holder, the operator may verify the location of that device only.
• Combined location verification: The operator may verify based on a location area that encompasses all devices associated with the phone number.
• Error response: The operator may reject the request with an error indicating that multi-SIM scenarios are not supported for this API.

Service providers should check with the operator to understand the expected behavior. To make location verification more deterministic in multi-SIM scenarios, service providers can:

• Use the authorization code flow (three-legged token) to automatically identify the intended device
• Identify the device by unique attributes such as IP address and port
• Use a secondary phone number if one is associated with the specific device

Privacy and consent

Before using Location Verification, service providers must ensure:

• The user has been informed of the purpose for which their location will be verified
• The user has explicitly consented to location verification for that purpose
• The consent scope matches the API operation being invoked
• The processing complies with applicable data protection regulations (e.g., GDPR, CCPA)

Open Gateway enforces consent at the platform level. If a user has not consented or has revoked consent, location verification requests will fail with an authorization error, regardless of whether the service provider holds a valid access token.

Privacy advantage of verification over retrieval:

While both capabilities require user consent, location verification exposes less information to the service provider than location retrieval. The service provider learns only whether the device is inside or outside a specific area, not the device’s actual coordinates. This reduces the privacy risk and may simplify compliance obligations in certain jurisdictions.

Use cases