Understand location validation

For selected delivery-status actions, Driver App can compare its current client location with the business or customer location and show validation issues before it sends a status request.

This is a client-side preflight. A passing or failing result does not prove trusted GPS, fresh location, simulated-location safety, physical proximity, server acceptance, or deployed behavior.

Availability

The reviewed validator applies to selected client target statuses for arrival, pickup, customer arrival, and delivery completion when the corresponding validation configuration is active.

An explicit disabled setting turns the client check off even when a distance threshold remains configured. When the explicit setting is absent, a numeric distance threshold can activate the check. Validation being off is not permission to perform an order action.

State and result matrix

Client state	Local result	What it means	What remains unproven
Target status does not require location	Validation returns no issue for this helper.	This local check does not apply.	Server/location requirements elsewhere
Validation explicitly disabled	Validation returns no issue.	Client preflight is bypassed.	Eligibility, proximity, or server acceptance
Current location lookup fails	Cannot get current location issue can appear.	The client did not obtain usable location from its hook.	Why the OS/provider failed or whether another source has location
Location timestamp exceeds configured age	Outdated-location issue can appear.	The client timestamp is older than its configured limit.	Server freshness, provider accuracy, or trusted capture time
Location has no timestamp	The stale-location branch is not evaluated.	The client has no timestamp to compare.	That the location is fresh
Business/customer target missing	Target location not found issue can appear.	The returned order lacks a target the helper accepts.	Actual physical destination or server data quality
Calculated distance exceeds threshold	Too-far issue can show calculated distance and threshold.	Client coordinates exceeded the configured client threshold.	Trusted proximity, route distance, GPS accuracy, or server decision
No local issues	The helper returns valid with the current location.	Client preflight found no issue it checks.	Freshness without timestamp, mock safety, physical arrival, or action success
Simulated/mock indicator present	The reviewed client validator does not reject it in this helper.	Mock evaluation is outside this local preflight.	Safe/trusted location or server mock-policy enforcement

The helper targets the business for selected business/pickup transitions and the customer for selected arrival/completion transitions. It calculates straight- line distance from coordinates, not road distance, route progress, entrance location, or proof of physical presence.

Effects and boundaries

Boundary	Source-defined behavior	Public limit
Configuration	Enables/disables per target status and supplies age/distance limits.	Client configuration is not server policy confirmation.
Current location	Uses provided location or calls the location hook.	Lookup can invoke OS/provider/location effects; value is not inherently trusted.
Timestamp	Adds an outdated issue only when a timestamp exists and exceeds the limit.	Missing timestamp is not treated as stale.
Target location	Reads business or customer coordinates from current order data.	Missing/zero-like values can be treated as missing; data currentness unproven.
Distance	Calculates coordinate distance and compares with a threshold.	Not route distance, GPS accuracy, or presence proof.
Refresh Location	Can request a new location and revalidate.	Refresh is effectful and not admitted for evidence or this reference.
Go to settings	Can hand control to operating-system Settings after a location error.	Handoff is effectful; Settings change and return result are separate.
Status request	Can continue only after client issues are cleared in the calling flow.	API authorization, validation, writes, and follow-ons remain separate.

Interpret validation safely

• Treat an issue as a reason to stop the current status action.
• Do not change, simulate, refresh, or manually enter location to make the issue disappear.
• Do not press Refresh Location or Go to settings for documentation or testing.
• A no-issue result is not proof of physical proximity or permission to change status.
• Ask the order/location owner to reconcile questionable target data or current server state.

Platform and lifecycle variations

• iOS and Android permission, Settings, background-location, provider, and mock indicators can differ.
• App foreground/background transitions can change location age or trigger separate refresh/follow work.
• Device clock and time-zone correctness affect the local age calculation.
• GPS/provider accuracy and coordinate precision affect calculated distance but are not incorporated as an accuracy confidence decision here.

Troubleshooting

What you see	What to check	Safe recovery
Cannot get current location	Visible permission/provider state and whether location services are available	Stop the order action. Use the permission guide; do not force Settings or refresh for evidence.
Outdated-location issue	Displayed local age and device clock	Treat it as a local warning, not trusted freshness. Do not change the clock or mock location.
Target location not found	Whether the current order detail visibly lacks usable destination context	Do not copy coordinates from another product; ask the order owner to correct/verify data.
Too-far issue	Client-calculated distance and configured threshold	Do not move, simulate, or alter coordinates to pass a test. Let the location/order owner verify physical and server state.
No issue but location is doubtful	Missing timestamp, provider accuracy, mock handling, and server policy are outside the local pass.	Stop before the status action and escalate.
Validation differs between devices	Permission, provider, clock, accuracy, configuration, and platform can diverge.	Record only issue type/platform/time, never coordinates or addresses.
Refresh or Settings seems to fix the UI	Those are separate effectful handoffs and can change client state.	Do not treat the new UI as server acceptance or proximity proof.

Related guides: Location permissions · Delivery map · Arrive at the business · Arrive at the customer · Complete delivery