geolocation-api.adoc

title	Geolocation API
page-title	How to use the Geolocation API in Vaadin
description	Using the Geolocation API to access device location from the server.
meta-description	Learn how to access device geolocation in Vaadin applications using the server-side Geolocation API.
order	115

Geolocation API

Table of Contents

• Getting the Current Position
• Options
• Tracking Position Changes
• Handling Errors
• Position Data

The Geolocation API allows you to access the browser Geolocation API from server-side Java code. It provides two modes: one-shot position requests with callbacks, and continuous position tracking with reactive Signals.

Note	The browser prompts the user for permission to share their location. Geolocation requires a secure context (HTTPS), except on localhost during development.

Getting the Current Position

Use the static Geolocation.get() method to request the device’s current position. The callback runs on the UI thread.

Geolocation.get(position -> {
    double lat = position.coords().latitude();
    double lon = position.coords().longitude();
    Notification.show("Location: " + lat + ", " + lon);
});

To handle errors, pass a second callback:

Geolocation.get(
    position -> {
        double lat = position.coords().latitude();
        double lon = position.coords().longitude();
        map.setCenter(lat, lon);
    },
    error -> Notification.show("Location error: " + error)
);

Options

You can configure the position request with GeolocationOptions:

enableHighAccuracy

Requests GPS-level accuracy. Uses more power and may take longer. Default: false.

timeout

Maximum time in milliseconds to wait for a position. Default: no limit.

maximumAge

Maximum age in milliseconds of a cached position that’s acceptable to return. Default: 0 (always request a fresh position).

var options = new GeolocationOptions(true, 5000, null);

Geolocation.get(options, position -> {
    map.setCenter(position.coords().latitude(), position.coords().longitude());
});

Pass null for any option to use the browser default.

Tracking Position Changes

Use Geolocation.track() to continuously monitor position changes. It returns a Geolocation instance with reactive Signals that update whenever the device’s position changes.

Geolocation geo = Geolocation.track(this);

Read the position in a ComponentEffect to reactively update the UI:

Geolocation geo = Geolocation.track(this);

ComponentEffect.effect(this, () -> {
    GeolocationPosition pos = geo.value().get();
    if (pos != null) {
        map.setCenter(pos.coords().latitude(), pos.coords().longitude());
    }
});

Tracking stops automatically when the owner component detaches. You can also pass GeolocationOptions to control accuracy and caching:

Geolocation geo = Geolocation.track(this, new GeolocationOptions(true, null, null));

Handling Errors

Error handling differs between the two modes.

With get(), the error callback receives a String message:

Geolocation.get(
    position -> showOnMap(position),
    error -> Notification.show("Error: " + error)
);

With track(), errors are available as a Signal<GeolocationError> with a numeric code and a message. The error signal is cleared to null whenever a successful position update arrives.

Geolocation geo = Geolocation.track(this);

ComponentEffect.effect(this, () -> {
    GeolocationError err = geo.error().get();
    if (err != null) {
        if (err.code() == GeolocationError.PERMISSION_DENIED) {
            Notification.show("Please allow location access");
        }
    }
});

The error codes are:

Code	Description
GeolocationError.PERMISSION_DENIED	The user denied the location permission request.
GeolocationError.POSITION_UNAVAILABLE	The device couldn’t determine its position.
GeolocationError.TIMEOUT	The request exceeded the configured timeout.

Position Data

A GeolocationPosition contains GeolocationCoordinates and a timestamp (milliseconds since Unix epoch).

The coordinates include:

Field	Type	Description
latitude()	double	Latitude in decimal degrees.
longitude()	double	Longitude in decimal degrees.
accuracy()	double	Accuracy of latitude and longitude in meters.
altitude()	Double	Altitude in meters above the WGS84 ellipsoid, or null.
altitudeAccuracy()	Double	Accuracy of the altitude in meters, or null.
heading()	Double	Direction of travel in degrees (0-360), or null.
speed()	Double	Speed in meters per second, or null.

Fields that return Double (boxed) may be null when the device doesn’t provide that data.