Signature

apply_filters( 'mam_specials_get_post_radius', int $radius );

Returns: int — the radius in miles. You must return it.

Purpose

Sets the search radius used by the nearby-offers feed to decide which published special offers are close enough to the requesting device to appear. The plugin’s mam_special_offers::get_data_for_app() walks every published offer, resolves each offer’s parent-listing coordinates, and computes a great-circle distance from $_REQUEST['lat'] / $_REQUEST['lon']. Offers within $radius miles are returned; the rest are dropped.

The default of 5 miles is tight on purpose — it’s tuned for hyperlocal apps where you only want offers in the same neighborhood as the user. Any app serving a wider area will need to bump it.

This filter has no admin-side equivalent. Unlike mam-geofilters, the special-offers radius is not stored in role settings or a per-app option — it is purely code-driven.

When it runs

Inside mam_special_offers::get_data_for_app() (includes/content-class-special-offers.php), once per request:

$radius = apply_filters( 'mam_specials_get_post_radius', 5 );
foreach ( $posts as $post ) {
    // ... resolve $lat / $lon for the offer's parent ...
    if ( $this->distance_between( $req_lat, $req_lon, $lat, $lon ) < $radius ) {
        $dir_details[] = $this->get_post_content( $post );
    }
}

The filter fires once per request, before the per-offer loop. It is not consulted on the home-screen featured-offers feed (which returns all featured offers regardless of distance) or on the listing-detail offers section (which only checks the offer’s parent linkage). It only affects the location-aware offers list.

Default behavior

mam_specials_get_post_radius → 5  (miles)

Offers attached to parent listings without resolvable coordinates (no lat / lon meta, or both are zero) compute a distance of 0 against the device’s coordinates and pass any positive radius — so increasing the radius does not make those offers visible by accident, but if $req_lat and $req_lon are also zero (no GPS supplied) every coordinate-less offer is technically inside any radius.

Examples

Wider radius for a regional app

add_filter( 'mam_specials_get_post_radius', static fn () => 50 );

A constant override is fine — there’s only one decision per request.

Per-role radius

add_filter( 'mam_specials_get_post_radius', 'my_app_specials_radius' );

function my_app_specials_radius( $radius ) {
    if ( current_user_can( 'premium_member' ) ) {
        return 100;
    }
    return $radius;
}

Tied to the geofilters radius

If the same app uses mam-geofilters, you may want the special-offers feed to respect the user’s chosen geofilter radius rather than its own:

add_filter( 'mam_specials_get_post_radius', 'my_app_match_geofilter_radius' );

function my_app_match_geofilter_radius( $radius ) {
    return (int) apply_filters( 'mam_geofilter_radius', $radius );
}

This delegates to the geofilters resolution chain ($_REQUEST['radius'] → per-role setting → default 25, capped at 3000). See the geofilters plugin’s own Hook: mam_geofilter_radius for the chain’s details.

Gotchas

• Comparison is strict less-than. The check is distance < $radius, not <=. An offer exactly at the boundary will not appear. Returning 5.0 is functionally identical to returning 5.
• $req_lat / $req_lon come from $_REQUEST unsanitized except for floatval(). A request with no GPS gets (0, 0) — somewhere off the coast of West Africa. Most listings will compute thousands of miles of distance and be filtered out, which is the correct behavior, but it does mean offers attached to listings also at (0, 0) (uninitialized meta) will pass any radius. Validate listing coordinates if this matters.
• The 5-mile default is per request, not cached. Adding an expensive callback (DB lookup, remote call) here adds latency to every nearby-offers request. If you’re computing the radius from per-user data, cache it.
• No interaction with featured offers. Returning 0 does not hide the home-screen feed — that path doesn’t consult this filter. To hide featured offers entirely, clear special-offer-featured-listing on the offers themselves.

Verification

This article was last verified against:

• Plugin: mam-special-offers v2.1
• Source: mam-special-offers/includes/content-class-special-offers.php (get_data_for_app)

Re-verify whenever the default radius (5) changes, the comparison operator in get_data_for_app() changes, or the lat/lon source for the request changes from $_REQUEST['lat'] / $_REQUEST['lon'].

Related articles

• Plugin: mam-special-offers
• Hook: mam_specials_get_post_lat — companion hook for overriding parent coordinates
• Hook: mam_special_offers_deals_allowed
• Hook: mam_special_offers_skip_tab_bar_button

Metadata