What you’ll accomplish

By the end of this article, your app will show a distance label (for example, “2.4 mi”) on each listing card, measured from the user’s current location to that listing. Optionally, you can also have the list sorted nearest-first, so the closest listings land at the top.

No code here — this is pure configuration. You’ll flip two Listings settings and one listing-card layout option, and the app’s location features do the rest.

Before you start

For distance to work, the app needs two things: it has to know where the user is, and each listing needs coordinates on file. Check both before you go further:

• Your listings have latitude/longitude. Distance is measured from each listing’s stored lat/lon. GeoDirectory listings and Special Offers (which inherit coordinates from their parent listing) already have these — a listing with no coordinates simply can’t show a distance.
• The app can get the user’s location. The device sends its GPS coordinates (lat/lon) with every content request. If the user hasn’t granted location permission and there’s no other location source, there’s simply nothing to measure from, so no distance is shown.
• Geofilters / a chosen location helps. Distance values get populated as part of the location-aware listing query — in practice, that means distance shows up once the app has a location to work with, whether that’s the device’s GPS position or a city the user picked via mam-geofilters. See Recipe: Enable geofilters in the geofilters docs.

Note: distances are calculated as a great-circle (haversine) distance in miles — a straight-line “as the crow flies” figure, not a driving distance.

Step 1 — Turn on “Display Distance on listing”

1. Go to Mobile App Manager → App Settings.
2. Open the Listings settings group.
3. Find Display Distance on listing and set it to Yes.

Think of this as the app-wide switch — it makes the distance figure available in the listing UI at all. The per-card Show Distance layout option in Step 2 decides whether any individual card actually shows the label.

Step 2 — Enable “Show Distance” on the listing-card layout

The distance label lives inside a listing-card layout, so whichever layout your listings use needs that element switched on too.

1. Go to your listing layout editor (the Layout Manager for listing cards).
2. Open the layout used by the listings you want to change.
3. Enable the Show Distance checkbox.
4. Save the layout.

Behind the scenes, this sets showDistance: "yes" on every card built from that layout — that’s the flag the mobile app checks before it draws the distance label. Running more than one listing layout? Repeat this step for each one that should show distance.

Step 3 (optional) — Sort listings nearest-first

By default, listings sort alphabetically by title. Want proximity instead?

1. In App Settings → Listings, find Display order using Distance from User.
2. Set it to Yes.

Turn it on, and the listing query orders results by the computed distance value, so the nearest listings rise to the top. Turn it off, and listings fall back to title order.

This setting controls ordering only — you can sort nearest-first without showing the distance label, or show the label without re-sorting. The two settings work independently.

Step 4 — Rebuild and preview

1. Save your settings.
2. Refresh the app preview (or pull-to-refresh on a device build) so the new listing payload — the bundle of listing data your app downloads — is fetched.
3. Open a listing screen. You should see a distance figure on each card, and — if you enabled Step 3 — the closest listings at the top.

Change the user’s location — move the device, or pick a different city in the geofilters picker — and the distances recalculate on the next content request.

How it works (brief)

Here’s what happens under the hood: when the app requests listings, the device includes its current coordinates in the request. Your site’s backend measures the distance from those coordinates to each listing’s stored coordinates, then attaches it to the listing payload:

• For GeoDirectory listings, distance is computed in the listing query itself (a haversine expression evaluated against the listings table) and returned as a distance field per listing.
• For Special Offers, the offer inherits its parent listing’s lat/lon, and the distance is computed per offer before it’s added to the payload.

Each listing in the mobile payload then carries:

These keys are part of the frozen mobile contract — they’re how deployed apps already read distance, so the behavior is stable.

Troubleshooting

No distance shows on any card.

• Confirm Display Distance on listing is Yes and the listing’s layout has Show Distance enabled.
• Confirm the device has granted location permission, or that a city is selected in the geofilters picker. With no location, distance is never populated.

Distance shows on some listings but not others.

• The listings without a distance are almost certainly missing lat/lon. Add coordinates to those listings.

Sorting isn’t nearest-first.

• Display order using Distance from User must be Yes. If it’s off, listings sort by title even when distances are visible.
• If the request has no location, there are no distances to sort by, so the list falls back to title order.

The distance looks “off” compared to my map app.

• The figure is straight-line miles, not driving distance, so it will read shorter than a turn-by-turn route.

Related

• Recipe: Enable geofilters — give users a location even without GPS, and set the search radius.
• Plugin: mam-geodirectory — listing data shape, including the distance field.
• Plugin: mam-special-offers — distance on offers, and the mam_specials_get_post_lat / mam_specials_get_post_lon hooks for overriding an offer’s coordinates.

Verification

This article was last verified against:

• App settings: directory_display_distance_from_user and featured_show_distance (category listings), defined in mam-main/includes/app-settings/admin-settings-page.php
• Layout option: showDistance, defined in mam-main/includes/app-settings/mam-layout-manager.php and applied in mam-main/includes/app-settings/local-settings.php
• GeoDirectory distance query and distance-vs-title sort in mam-geodirectory/content-classes/local-app-geodirectory-v2-class.php
• Special Offers distance calculation in mam-special-offers/includes/content-class-special-offers.php
• Haversine helper mam_distance_between() in mam-main/includes/helper-classes/mam-classless-functions.php

Re-verify whenever the listing settings labels change, the showDistance layout option is renamed, the distance query/sort logic changes, or the distance mobile-payload key changes.