Module · Geo
ExpertPress Geo
ExpertPress Geo adds optional geolocation to an ExpertPress marketplace: specialists put their in-person services on a map, and clients can look for services close to them. Public pages show only an approximate area by default; the exact point and the street address stay private. Leave the module off if every session on your marketplace takes place online.
Key capabilities:
- A Locations tab in the specialist cabinet where the specialist sets a map point, city, district and a private address for each of their services.
- Three privacy levels per point: an approximate public area (the default), an exact public marker, or a fully private point that is never shown or searched.
- An ExpertPress Map block and
[expertpress_map]shortcode that show published locations on a map. - An ExpertPress Nearby Filter block and
[expertpress_nearby_filter]shortcode: "Use my location" or a pin on the map, an optional radius, then a filtered catalog. - Distances rounded to 100 m and offset markers, so the private point cannot be worked out from search results.
- A choice of map provider: MapLibre (bundled with the module, works with any tile server you choose), Google Maps or Mapbox with your own key.
- Public geo fields in the catalog REST responses (public coordinates, city and district, and distance in a nearby search), for themes and apps.
The module is off after installation.
Requirements
- ExpertPress (core plugin) installed and active. The module declares
Requires Plugins: expertpress; WordPress will not activate it without the core. - WordPress 6.0 or later; PHP 7.4 or later.
- Database tables of its own (map points and a small state table), created when the module is activated.
- A map source. The module does not include map imagery. Choose one:
- MapLibre (default): the map library is bundled, but you need a tile server and its URL (your own, or a commercial tile service with its own account and terms). Without a tile URL the map is a plain grey background on which markers and pins still work.
- Google Maps: a Google Cloud account with the Maps JavaScript API enabled and a browser API key.
- Mapbox: a Mapbox account and a public access token.
- No geocoding. The module never turns an address into coordinates. Points are set by clicking the map or by typing latitude and longitude.
- A one-time preparation step before nearby search works (see below).
Getting it running
- Activate ExpertPress Geo after the core.
- Open ExpertPress → Geolocation (Геолокація), or Geo (Гео) in the Modules section of the ExpertPress admin, tick Enable geolocation, pick a map provider, enter the tile URL or key, and click Save geolocation settings. See Settings.
- Prepare the public map data. Before nearby search can answer, the module has to build the public (offset) version of every saved point. There is no button for this on the settings screen: whoever maintains the site runs the module's maintenance call from WP-CLI, for example
wp eval 'var_dump( ExpertPress\Geo\Service\ProjectionState::rebuild_batch( 200 ) );', and repeats it until the result saysreadyis true. On a new site with no points one run is enough. Repeat it after changing Public marker offset (meters) or the site's WordPress security keys, because both change where the public markers are drawn. Until it is done, a nearby search returns an "unavailable" result; the ordinary catalog keeps working. - Ask specialists with in-person services to set their locations under Locations in their cabinet.
- Add the ExpertPress Nearby Filter block (and, if you want, the ExpertPress Map block) to the catalog page or another page. See Blocks and shortcodes.
What changes for each side
Specialists
When the module is enabled, the specialist cabinet gets a Locations (Локації) tab. It lists every service of the specialist under the heading Service locations (Локації послуг), each with its own form:
- Latitude and Longitude (required). Clicking the small map under the form fills them in.
- City label (Місто) and Area / district (Район), up to 191 characters each. These are shown publicly.
- Full address (private) (Повна адреса (приватна)). Stored on the site; never included in public pages or REST responses.
- Privacy (Приватність): Public area (Публічний район), Public exact (Публічна точна) or Exact private (Точна приватна). A new point starts with the site's Default privacy.
- Save location (Зберегти локацію).
What each privacy level means for the public:
| Level | Map marker | Found by nearby search | Distance shown |
|---|---|---|---|
| Public area | Moved by a fixed random offset from the real point (at least 50 m, up to the site's Public marker offset) | Yes, measured to the offset marker | Yes, rounded up to 0.1 km |
| Public exact | At the exact point | Yes | Yes, rounded up to 0.1 km |
| Exact private | Not shown | No | No |
The offset for a given service is always the same (it does not move on every page load), and it does not depend on the real coordinates, so averaging many views does not reveal the point.
Only services can be placed from the cabinet. The module also supports points for specialist profiles (used by the specialists directory filter and by the map with entity="specialist"), but it has no screen for setting them; they appear only if a theme or another plugin saves them.
Clients and visitors
- On pages with the Nearby Filter, a visitor clicks Use my location (Моя локація). The browser asks for permission to share the location. If the visitor agrees, the catalog opens filtered to services within the radius; if not, a small map appears with the hint "Click the map to set a point", and the visitor picks a point by hand and clicks Search nearby (Шукати поруч).
- If Allow visitors to choose the search radius is on, a Radius (km) (Радіус (км)) field appears; otherwise the site's default radius is used.
- Service cards and the REST catalog carry the public city/district and, in a nearby search, the distance.
- The Map block shows markers for published services (or specialists) whose privacy is public area or public exact, up to 200 markers.
The site owner and team
- One settings screen, available to administrators and ExpertPress Managers (permission
expertpress_operate), see Roles and access. - An administrator can save a location for any service through the same cabinet form; a specialist can only change locations of their own services.
- Only published content appears on the map and in nearby results; the core's publication rules still apply.
Blocks and shortcodes
Both blocks are in the ExpertPress block category and are registered only while geolocation is enabled. While it is off, the shortcodes print nothing.
ExpertPress Map — [expertpress_map]
Map of published marketplace locations (public coordinates only).
| Attribute | Default | Values |
|---|---|---|
entity |
service |
service or specialist |
zoom |
12 |
1–20 |
height |
360 |
Height in pixels, 160–800 |
The map centres on the first marker. The map library loads only when the map scrolls into view.
Example: [expertpress_map entity="service" zoom="11" height="420"]
ExpertPress Nearby Filter — [expertpress_nearby_filter]
Radius filter using the visitor location or a map pin.
| Attribute | Default | Values |
|---|---|---|
target |
services |
services opens the service catalog; specialists opens the specialists directory |
The form always sends visitors to /listings/ (for services) or /specialists/ (for specialists) with near_lat, near_lng and radius_km in the address. It does not follow a catalog address changed under ExpertPress → Settings → Pages and terms → Addresses; on such a site check that the filter lands on your catalog page. The same parameters work in the core catalog REST endpoints, and include_distance=1 adds the distance to each item.
For the core blocks, see Blocks, shortcodes and widgets.
Privacy and data
Stored on your site (in the module's own table):
- For each point: the exact latitude and longitude, the public (offset or exact) coordinates, the privacy level, city and district labels, the private full address, and the time of the last change.
Shown publicly: only the privacy level, city and district labels, the public coordinates (not for Exact private) and rounded distances. The exact coordinates of a Public area point and the full address are never sent to visitors.
The visitor's own location is read by the browser only after the visitor clicks Use my location and agrees. It is sent to your site as part of the catalog address (near_lat, near_lng, to seven decimal places), so it can appear in your web server logs and in any analytics that record page addresses. The module does not store it.
External services:
- MapLibre: the map library is served from your site. Map tiles are requested by the visitor's browser from the tile URL you entered, so that tile host receives the visitor's IP address, browser details and the map area being viewed. Its terms apply.
- Google Maps or Mapbox (only when selected and Allow remote Google / Mapbox SDKs is on): the visitor's browser loads the provider's script and tiles directly from Google or Mapbox, with your key. The provider receives the visitor's IP address, browser details and the map area being viewed, under its own terms and privacy policy.
- Nothing is sent to any of them by the server; specialists' saved coordinates are not sent anywhere except as markers drawn in the visitor's browser.
Mention the map provider you use, and the "Use my location" feature, in your site's privacy policy.
Personal data tools: the module does not add entries to the WordPress personal data export or erase tools. Locations belong to services; what happens to them when a service or account is removed is not handled by a separate rule in this module.
Turning it off and removing it
- Unticking Enable geolocation hides the cabinet tab, both blocks, the shortcodes' output and the geo fields in REST responses. Saved locations are kept.
- Deleting the plugin from Plugins removes its tables (all saved locations) and its settings. If a table cannot be removed, the settings are kept so that deletion can be retried.