What it does

mam-geofilters lets a mobile app filter the content it shows by city. Once enabled, the app displays a location picker — either inline in the home view or as an icon — and uses the chosen city’s latitude/longitude plus a configurable search radius to filter what the user sees.

Most use cases are pure configuration: turn the feature on per role, set a radius, and trim or extend the built-in list of 55 US cities. When configuration isn’t enough, four WordPress filters let a developer add cities, replace the entire list, or override the on/off and radius decisions in code.

The plugin is no-code first and low-code where it matters. The same person typically wears both hats — admin to enable the feature, developer to extend it — so the recipes and hook references in this codex are designed to hand off to one another.

Where it appears in the app

When mam_use_geofilters resolves to true for the current user, the mobile app renders a location picker:

• Inline — a button or strip in the home view (default behavior)
• As an icon — a compact icon in the navigation chrome (set by tsl-geofilters_show_as_icon)

The active city’s coordinates and the configured radius are sent on subsequent content requests so the backend can return geographically relevant results.

If GPS is available the app also shows a “Current Location” entry at the top of the picker. If GPS is unavailable, the plugin can fall back to a city derived from the user’s IP via the GeoIP Detection plugin (if installed).

Requirements

• WordPress 6.3+
• PHP 8.1+
• MAM Suite with mam-main activated
• MAM Suite plugin entitlement for mam-geofilters

Optional integrations:

• MAM GeoDirectory — when active, GeoDirectory takes over the city list via the mam_geofilter_list filter (see Hook: mam_geofilter_list)
• GeoIP Detection plugin — enables IP-based fallback when GPS is unavailable

Default city list

Out of the box the plugin ships with a list of 55 US cities (San Jose, Oakland, New York, Los Angeles, Chicago, Miami, Dallas, Philadelphia, Houston, Atlanta, …). Each entry has a text (display name), lat, and lon. The full list is in includes/geofilters-cities-list.php.

You can:

• Hide cities from the geofilters tab in admin — see Recipe: Manage the city list
• Edit names or coordinates on the Manage Cities admin page — see Recipe: Manage the city list
• Add cities programmatically via filter — see Hook: mam_wc_geofilters_locations
• Replace the list entirely via filter — see Hook: mam_geofilter_list

Hooks exposed

Each hook has its own dedicated article. See Related articles.

Mobile JSON contract

mam-geofilters writes into the mobile JSON payload via the mam_get_phone_data_before_send pipeline. The keys it sets are part of the frozen mobile contract — renaming them will break deployed apps. See docs/CODEBASE_MAP.md for the canonical list.

The first entry in geoFiltersLocations is special:

• If GPS coordinates are sent in the request (actual_lat, actual_lon) and gd-show-current-location-on-app is not 'no', the picker is prepended with a Current Location entry at the device’s coordinates.
• Otherwise, if the request has no_gps=yes and GeoIP Detection is installed, the picker is prepended with a city derived from the request IP, and location_name is set to that city.
• On the default-list path (no mam_geofilter_list subscriber), if the request has actual_lat the list is also prepended with a Nearby entry at the device’s coordinates inside the list-builder itself. This is in addition to the Current Location prepend that happens later in the pipeline.

Common tasks

• Enable geofilters and set the radius → Recipe: Enable geofilters
• Hide cities or edit their coordinates → Recipe: Manage the city list
• Configure a per-neighborhood city list → Recipe: Per-neighborhood city lists
• Add a custom city in code → Hook: mam_wc_geofilters_locations
• Replace the city list with one from another data source → Hook: mam_geofilter_list
• Force geofilters on or off in code → Hook: mam_force_geofilters
• Override the search radius in code → Hook: mam_geofilter_radius

Verification

This article was last verified against:

• Plugin: mam-geofilters v2.1.1
• mam-main (required)
• mam-geodirectory (optional integration)
• GeoIP Detection plugin (optional integration)

Re-verify whenever a hook is added or removed, the default city list changes, the on/off decision logic changes (mam_use_geofilters), or the mobile JSON keys named under Mobile JSON contract change.

Related articles

• Recipe: Enable geofilters
• Recipe: Manage the city list
• Recipe: Per-neighborhood city lists
• Hook: mam_wc_geofilters_locations
• Hook: mam_geofilter_list
• Hook: mam_force_geofilters
• Hook: mam_geofilter_radius

Metadata