suredonation_phone_geo_api_hourly_cap Filter Hook

Overview

The suredonation_phone_geo_api_hourly_cap filter controls the site-wide hourly limit for outbound ipapi.co geolocation requests used by SureDonation to detect the visitor’s country for the Phone field.

The limit helps control API usage and prevents excessive requests from exhausting the available geolocation service quota.

When to Use This Filter

Use this filter when you need to customize the maximum number of IP geolocation requests SureDonation can make per hour.

For example, you can use it to:

• Reduce the number of external geolocation requests.
• Increase the limit for a high-traffic website.
• Adjust the limit when using a paid ipapi.co plan.
• Control third-party API usage based on your site’s requirements.

Filter Signature

apply_filters( 'suredonation_phone_geo_api_hourly_cap', 40 );

apply_filters( 'suredonation_phone_geo_api_hourly_cap', 40 );

Parameters

Default Value

The default limit is: 40

The default value is intentionally kept well below the ipapi.co free-tier limit of 1,000 requests per day.

Return Value

Return an integer representing the maximum number of geolocation requests allowed per hour.

return 100;

The returned value is coerced to an integer.

Basic Usage

Use add_filter() to modify the hourly limit.

add_filter( 'suredonation_phone_geo_api_hourly_cap', 'your_custom_function', 10, 1 );

function your_custom_function( $cap ) {

    return $cap;

}

add_filter( 'suredonation_phone_geo_api_hourly_cap', 'your_custom_function', 10, 1 );

function your_custom_function( $cap ) {

    return $cap;

}

Example: Increase the Hourly Limit

The following example increases the hourly limit to 200 requests.

add_filter( 'suredonation_phone_geo_api_hourly_cap',

    function () {

        // Allow more lookups per hour on a high-traffic site with a paid plan.

        return 200;

    }

);

add_filter( 'suredonation_phone_geo_api_hourly_cap',

    function () {

        // Allow more lookups per hour on a high-traffic site with a paid plan.

        return 200;

    }

);

This can be useful for high-traffic websites that use a paid ipapi.co plan with a higher request allowance.

Example: Reduce the Hourly Limit

You can also reduce the limit to minimize external API requests.

add_filter( 'suredonation_phone_geo_api_hourly_cap',

    function () {
        return 20;

    }

);

add_filter( 'suredonation_phone_geo_api_hourly_cap',

    function () {
        return 20;

    }

);

With this configuration, SureDonation allows a maximum of 20 geolocation requests per hour.

How It Works

The hourly cap is applied as part of the Phone field’s country detection process:

1. A visitor loads a SureDonation Phone field.
2. SureDonation determines whether IP-based country detection is enabled.
3. SureDonation checks the current hourly geolocation request count.
4. If the count is below the configured cap, the geolocation API request can proceed.
5. Once the hourly cap is reached, additional requests are not sent.
6. Visitors after the limit is reached use us as the default country.
7. The fallback country is cached for one hour.
8. The request counter rolls over each hour.

What Happens When the Limit Is Reached?

Once the configured hourly cap is reached, SureDonation stops making additional ipapi.co requests for that period.

Instead, subsequent visitors:

• Default to the US country.
• Use the cached fallback for one hour.
• Do not trigger another geolocation API request.

This prevents additional visitors from increasing API usage after the hourly limit has been reached.

Best Practices

When changing the default limit:

• Consider your site’s traffic volume.
• Ensure the limit is compatible with your ipapi.co plan.
• Avoid setting an unnecessarily high limit.
• Monitor external API usage if increasing the cap.
• Consider privacy requirements before enabling IP-based geolocation.

Related Hooks

• suredonation_phone_geo_enabled: Globally enables or disables IP-based country detection for SureDonation Phone fields.