Check VPS availability at the device's current location
Stay organized with collections
Save and categorize content based on your preferences.
The Geospatial API uses a combination of VPS and GPS data to generate high-accuracy Geospatial poses. The API can be used in any place where the device is able to determine its location:
In areas with low GPS accuracy, such as indoor spaces and dense urban environments, the API will rely on VPS coverage to generate high-accuracy poses.
In outdoor environments with few or no overhead obstructions, the Geospatial API may be able to use available GPS location data to generate Geospatial poses with high accuracy.
You can determine VPS availability at a given horizontal position before the AR session starts and use it to create more specific experiences — for example, to present an "Enter AR" button only when VPS is available.
Enable the ARCore API
Your app must enable the ARCore API to check VPS availability.
Once the ARCore API is enabled, you can check VPS availability without:
The Geospatial API can be used in any place where the device is able to determine its location. If your AR experience hinges on VPS coverage, you can use ArSession_checkVpsAvailabilityAsync() to obtain a ArVpsAvailabilityFuture, an asynchronous task that checks the VPS availability at a given horizontal position.
Once you have the ArVpsAvailabilityFuture, you can obtain its result by polling or through a callback.
Poll the result
Use ArFuture_getState() to obtain the state of the ArFuture. There are three different states:
// Obtain a ArVpsAvailabilityFuture and store it somewhere.ArVpsAvailabilityFuture*future=NULL;CHECK(ArSession_checkVpsAvailabilityAsync(ar_session,latitude,longitude,NULL,NULL,&future)==AR_SUCCESS);// Poll ArVpsAvailabilityFuture later, for example, in a render loop.ArFutureStatefuture_state=AR_FUTURE_STATE_PENDING;ArFuture_getState(ar_session,(ArFuture*)future,&future_state);if(future_state==AR_FUTURE_STATE_DONE){ArVpsAvailabilityvps_availability=AR_VPS_AVAILABILITY_UNKNOWN;ArVpsAvailabilityFuture_getResult(ar_session,future,&vps_availability);switch(vps_availability){caseAR_VPS_AVAILABILITY_AVAILABLE:// VPS is available at this location.break;caseAR_VPS_AVAILABILITY_UNAVAILABLE:// VPS is unavailable at this location.break;caseAR_VPS_AVAILABILITY_ERROR_NETWORK_CONNECTION:// The external service could not be reached due to a network connection// error.break;// Handle other error states, e.g.// AR_VPS_AVAILABILITY_ERROR_RESOURCE_EXHAUSTED,// AR_VPS_AVAILABILITY_ERROR_INTERNAL, ...}ArFuture_release((ArFuture*)future);}
Obtain the result through a callback
You can also obtain the result of a ArFuture through a callback. Use ArSession_checkVpsAvailabilityAsync() and supply a callback. This callback will be called on the Main thread soon after the ArFuture has state AR_FUTURE_STATE_DONE.
voidvps_availability_callback(void*context,ArVpsAvailabilityavailability){// Callback is called on the Main thread.// Handle the ArVpsAvailability result as shown above.// For example, show UI that enables your AR view.// It is a best practice to free `context` memory at the end of the callback.free(context);}voidcheck_availability_with_callback(ArSession*ar_session,doublelatitude,doublelongitude){ArVpsAvailabilityFuture*future=NULL;void*context=NULL;CHECK(ArSession_checkVpsAvailabilityAsync(ar_session,latitude,longitude,context,vps_availability_callback,&future)==AR_SUCCESS);}
Cancel the ArFuture
Use ArFuture_cancel() to attempt to cancel the ArFuture. Due to thread parallelism, it may be possible that your cancel attempt does not actually succeed.
ArFuture_cancel() returns 1 if this attempt was successful, and 0 otherwise.
Use the Geospatial API without VPS coverage
The Geospatial API can also be used in areas that do not have VPS coverage. In outdoor environments with few or no overhead obstructions, GPS may be sufficient to generate a pose with high accuracy.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-07-14 UTC."],[[["\u003cp\u003eThe Geospatial API leverages VPS and GPS data to create precise location anchors, enhancing AR experiences in various environments.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can proactively confirm VPS availability at a specific location using the \u003ccode\u003eArSession_checkVpsAvailabilityAsync()\u003c/code\u003e function before initiating an AR session.\u003c/p\u003e\n"],["\u003cp\u003eThe API offers flexible methods for retrieving VPS availability results, including polling using \u003ccode\u003eArFuture_getState()\u003c/code\u003e or utilizing a callback function for asynchronous updates.\u003c/p\u003e\n"],["\u003cp\u003eEven in areas without VPS coverage, the Geospatial API can still provide location data by relying on GPS, particularly in outdoor settings with clear sky visibility.\u003c/p\u003e\n"],["\u003cp\u003eAfter confirming VPS availability or utilizing GPS, developers can obtain the device's Geospatial pose to accurately position virtual content in the real world.\u003c/p\u003e\n"]]],["The Geospatial API leverages VPS and GPS data for accurate positioning. To check VPS availability, enable the ARCore API and use `ArSession_checkVpsAvailabilityAsync()` to create an `ArVpsAvailabilityFuture`. Results can be obtained by polling the `ArFuture` state with `ArFuture_getState()` or via a callback, indicating whether VPS is available, unavailable, or encountering network errors. The `ArFuture` can be canceled using `ArFuture_cancel()`. Even without VPS, the API utilizes GPS for positioning.\n"],null,["# Check VPS availability at the device's current location\n\n\u003cbr /\u003e\n\nThe Geospatial API uses a combination of [VPS](/ar/develop/geospatial#global_localization_with_vps) and GPS data to generate high-accuracy Geospatial poses. The API can be used in any place where the device is able to determine its location:\n\n- In areas with low GPS accuracy, such as indoor spaces and dense urban environments, the API will rely on VPS coverage to generate high-accuracy poses.\n- In outdoor environments with few or no overhead obstructions, the Geospatial API may be able to use available GPS location data to generate Geospatial poses with high accuracy.\n\nYou can determine VPS availability at a given horizontal position before the AR session starts and use it to create more specific experiences --- for example, to present an \"Enter AR\" button only when VPS is available.\n\nEnable the ARCore API\n---------------------\n\nYour app must enable the [ARCore API](/ar/develop/c/geospatial/enable#enable_the_arcore_api) to check VPS availability.\n\nOnce the ARCore API is enabled, you can check VPS availability without:\n\n- A current running [`ArSession`](/ar/reference/c/group/ar-session) (before calling [`ArSession_resume()`](/ar/reference/c/group/ar-session#arsession_resume)).\n- Setting a [`ArGeospatialMode`](/ar/reference/c/group/ar-config#argeospatialmode).\n\nCheck VPS availability in your app\n----------------------------------\n\nThe Geospatial API can be used in any place where the device is able to determine its location. If your AR experience hinges on VPS coverage, you can use [`ArSession_checkVpsAvailabilityAsync()`](/ar/reference/c/group/ar-session#arsession_checkvpsavailabilityasync) to obtain a [`ArVpsAvailabilityFuture`](/ar/reference/c/group/ar-vps-availability-future#arvpsavailabilityfuture), an asynchronous task that checks the VPS availability at a given horizontal position.\n\nOnce you have the [`ArVpsAvailabilityFuture`](/ar/reference/c/group/ar-vps-availability-future#arvpsavailabilityfuture), you can obtain its result by polling or through a callback.\n\n\n### Poll the result\n\nUse [`ArFuture_getState()`](/ar/reference/c/group/ar-future#arfuture_getstate) to obtain the state of the `ArFuture`. There are three different states:\n\n- [`AR_FUTURE_STATE_PENDING`](/ar/reference/c/group/ar-vps-availability-future#arfuturestate): The operation is not yet complete, so no result is known.\n- [`AR_FUTURE_STATE_CANCELLED`](/ar/reference/c/group/ar-vps-availability-future#arfuturestate): The operation has been cancelled by [`ArFuture_cancel()`](/ar/reference/c/group/ar-future#arfuture_cancel). Any registered callback will never be called.\n- [`AR_FUTURE_STATE_DONE`](/ar/reference/c/group/ar-vps-availability-future#arfuturestate): The operation is complete. Use [`ArVpsAvailabilityFuture_getResult()`](/ar/reference/c/group/ar-vps-availability-future#arvpsavailabilityfuture_getresult) to obtain the result.\n\nYou may continue checking [`ArFuture_getState()`](/ar/reference/c/group/ar-future#arfuture_getstate) until the task is complete. \n\n```c\n// Obtain a ArVpsAvailabilityFuture and store it somewhere.\nArVpsAvailabilityFuture* future = NULL;\nCHECK(ArSession_checkVpsAvailabilityAsync(ar_session, latitude, longitude,\n NULL, NULL, &future) == AR_SUCCESS);\n\n// Poll ArVpsAvailabilityFuture later, for example, in a render loop.\nArFutureState future_state = AR_FUTURE_STATE_PENDING;\nArFuture_getState(ar_session, (ArFuture*)future, &future_state);\nif (future_state == AR_FUTURE_STATE_DONE) {\n ArVpsAvailability vps_availability = AR_VPS_AVAILABILITY_UNKNOWN;\n ArVpsAvailabilityFuture_getResult(ar_session, future, &vps_availability);\n switch (vps_availability) {\n case AR_VPS_AVAILABILITY_AVAILABLE:\n // VPS is available at this location.\n break;\n case AR_VPS_AVAILABILITY_UNAVAILABLE:\n // VPS is unavailable at this location.\n break;\n case AR_VPS_AVAILABILITY_ERROR_NETWORK_CONNECTION:\n // The external service could not be reached due to a network connection\n // error.\n break;\n\n // Handle other error states, e.g.\n // AR_VPS_AVAILABILITY_ERROR_RESOURCE_EXHAUSTED,\n // AR_VPS_AVAILABILITY_ERROR_INTERNAL, ...\n }\n ArFuture_release((ArFuture*)future);\n}\n```\n\n### Obtain the result through a callback\n\nYou can also obtain the result of a `ArFuture` through a callback. Use [`ArSession_checkVpsAvailabilityAsync()`](/ar/reference/c/group/ar-session#arsession_checkvpsavailabilityasync) and supply a `callback`. This `callback` will be called on the Main thread soon after the `ArFuture` has state [`AR_FUTURE_STATE_DONE`](/ar/reference/c/group/ar-vps-availability-future#arfuturestate). \n\n```c\nvoid vps_availability_callback(void* context, ArVpsAvailability availability) {\n // Callback is called on the Main thread.\n\n // Handle the ArVpsAvailability result as shown above.\n // For example, show UI that enables your AR view.\n\n // It is a best practice to free `context` memory at the end of the callback.\n free(context);\n}\n\nvoid check_availability_with_callback(ArSession* ar_session, double latitude,\n double longitude) {\n ArVpsAvailabilityFuture* future = NULL;\n void* context = NULL;\n CHECK(ArSession_checkVpsAvailabilityAsync(\n ar_session, latitude, longitude, context, vps_availability_callback,\n &future) == AR_SUCCESS);\n}\n```\n| **Note:** When calling [`ArSession_checkVpsAvailabilityAsync()`](/ar/reference/c/group/ar-session#arsession_checkvpsavailabilityasync), you may provide an optional `context` parameter. This `context` is passed to the callback, which can be useful to associate additional data to a request. It is best practice to free the memory of `context` at the end of the callback and when [`ArFuture_cancel()`](/ar/reference/c/group/ar-future#arfuture_cancel) successfully cancels the future.\n\nCancel the `ArFuture`\n---------------------\n\nUse [`ArFuture_cancel()`](/ar/reference/c/group/ar-future#arfuture_cancel) to attempt to cancel the `ArFuture`. Due to thread parallelism, it may be possible that your cancel attempt does not actually succeed.\n\n`ArFuture_cancel()` returns `1` if this attempt was successful, and `0` otherwise.\n\nUse the Geospatial API without VPS coverage\n-------------------------------------------\n\nThe Geospatial API can also be used in areas that do not have VPS coverage. In outdoor environments with few or no overhead obstructions, GPS may be sufficient to generate a pose with high accuracy.\n\nWhat's next\n-----------\n\n- [Obtain the device camera's Geospatial pose](/ar/develop/c/geospatial/obtain-device-pose) to determine the exact location of the user's device in the real world."]]