Charitable Geolocation - WordPress Plugin

How to Set Up Charitable Geolocation for a Campaign Map

Charitable Geolocation is not just there to decorate a page with a map. It solves a specific problem: linking Charitable campaigns to real places, displaying them on a map, and helping visitors quickly understand where a fundraiser, project, team, or local initiative is active. In this guide, we will walk through how to prepare your site, choose a map provider, add addresses to campaigns, display the map with a block or shortcode, verify that everything works, and quickly pinpoint the cause if the map does not load.

This guide is written for a WordPress site owner, a nonprofit site administrator, an agency webmaster, or a technical editor who already works with Charitable and wants to make campaign pages more useful. It does not cover buying a license or bypassing activation. The goal here is to help you safely configure a plugin you already have access to and understand when geolocation genuinely improves the donation experience.

There are a few important details to keep in mind with Charitable Geolocation. Newer documentation describes a choice between OpenStreetMap via Leaflet and Google Maps, while older documentation and shortcode references still show a Google Maps workflow. That is why this guide takes a cautious approach: first verify which settings exist in your installed version, then choose the simplest working option, and only after that add the map to the public-facing site.

What Geolocation Actually Does in Charitable

A standard campaign page answers the question, "Which fundraiser should I support?" A map adds a second layer of meaning: where the project, team, event, or local need is located. For nonprofit sites, that is not a minor detail. If an organization is raising funds for several schools, disaster-affected regions, sports teams, volunteer events, or local chapters, visitors can make a decision more easily when they can see each campaign in geographic context.

Charitable Geolocation adds location data to campaigns. Once that is in place, the campaign map can display those campaigns as points or cards on a map. In the basic workflow, the administrator enters a location inside the campaign, the plugin gets coordinates from the selected provider, and the public page displays a map based on that data. If you are also using Charitable Ambassadors, the Location field may appear in the public campaign submission form so a participant or ambassador can enter the location themselves.

It is important not to confuse this plugin with a general-purpose address directory. It is built around Charitable campaigns. That means the main entity remains the fundraising campaign: title, goal, description, donations, progress, donors, and related Charitable elements. Geolocation simply adds a spatial layer. If you need a large directory of branches, restaurants, real estate listings, or arbitrary WordPress posts, a standalone mapping plugin may be a better fit. But if you want to build a map specifically from Charitable campaigns, this extension fits that niche very well.

When a Map Adds Real Value to the Page

A map is especially useful when campaigns have a meaningful geographic component. For example, a national organization can show fundraisers by region, a church can display mission projects, a sports club can show teams and events, an animal rescue can map shelters and mobile outreach locations, and a school can show class fundraisers or neighborhood initiatives. In those cases, visitors are not just reading a list - they are quickly connecting a fundraiser with a place they recognize.

If all campaigns support a single online goal with no geographic meaning, the map may be unnecessary. It takes up space, loads external map resources, and can distract from the donation itself. In that case, a standard campaign grid, a single campaign page, or a donation form is usually a better choice. Geolocation makes sense when location helps someone decide, not when the map simply looks impressive on its own.

What the Visitor Should See After Setup

A well-configured page should answer three questions without any extra explanation:

• Which campaigns are tied to a location and can be shown on the map.
• How a visitor can zoom the map, open a marker, and go to the campaign they need.
• Why some campaigns may be missing from the map if they do not yet have coordinates or an address.

The last point matters more than it may seem. It is common for an administrator to create a map, see an empty screen, and assume the plugin is broken. In practice, the reason is often much simpler: the campaigns do not have saved coordinates, the address was not geocoded, the selected provider is not connected, or the map is filtered so no matching campaigns are available.

Who This Plugin Is For and When It May Be Unnecessary

Charitable Geolocation is worth considering if you already use Charitable as your donation platform and want to display campaigns on a map. The plugin makes the most sense on sites with multiple active campaigns, local teams, ambassadors, events, regional funds, or projects that are easier to explain through place. In those conditions, the map becomes more than a decorative block - it becomes meaningful navigation.

A typical user of this extension is a nonprofit site administrator managing campaigns in WordPress who wants to shorten the path from visitor interest to choosing a specific fundraiser. Another common user is an agency building a site for a foundation and needing to hand off a simple system to the client: add a campaign, enter a location, save it, check the map. A third common use case is a project using Charitable Ambassadors, where campaigns are created not only by administrators but also by outside participants.

How to Tell Whether Charitable Geolocation Makes Sense for Your Site

Situation	Decision	What to Check
Campaigns are tied to cities, neighborhoods, branches, events, or volunteer teams.	Geolocation is usually a good fit.	Whether most campaigns already have addresses or coordinates.
The site has one main campaign with no local variations.	A map usually is not needed.	Whether the map would distract from the donation form.
Campaigns are submitted by ambassadors or community participants.	The Location field may reduce manual admin work.	Whether the field should be required and how addresses will be moderated.
You need a general WordPress location directory with radius search.	It is better to compare general-purpose mapping plugins.	Whether the map should show specifically Charitable campaigns or any type of post.

The plugin may not be the right fit if you do not use Charitable as your campaign system, if your campaigns have no meaningful geographic dimension, if your site runs in an environment where external map services are not allowed, or if the map needs to function as a full directory with filters across dozens of custom fields. In those cases, it is better not to force Charitable Geolocation into a role it was never designed to handle.

Quick reality check before deciding: take 5 to 10 real campaigns and ask yourself whether seeing them on a map would help a visitor choose. If the answer is "yes, because location affects the decision," geolocation makes sense. If the answer is "it would just look nicer," you are usually better off improving the campaign copy, donation form, and navigation first.

What to Check Before Installation

Before installing the extension, prepare not only WordPress itself but also the campaign data. Geolocation usually breaks down not because of one major issue, but because of a chain of smaller omissions: an outdated Charitable version, no campaigns yet, empty addresses, the wrong provider, caching, blocked external requests, Google key errors, or an overly strict site security policy.

Basic WordPress and Charitable Requirements

First, make sure the main Charitable plugin is installed, active, and able to create campaigns. Charitable Geolocation is an extension for that system, not a standalone mapping solution. If your site does not yet have any campaigns, create a test campaign first with a clear title, description, and published status. A map with no published campaigns that have locations will look empty even if everything is technically configured correctly.

Check whether your Charitable version includes an extensions settings area or a current section at Charitable > Settings > Advanced > Geolocation. The documentation may also show the older path Charitable > Settings > Extensions for the Google API key, as well as a newer screen with a separate Geolocation tab. That is not a contradiction for the user: the interface depends on the version and on which components are active. Follow what is actually visible in your WordPress admin.

Choosing a Map Provider: OpenStreetMap or Google Maps

Newer descriptions of Charitable Geolocation offer a choice between OpenStreetMap via Leaflet and Google Maps. OpenStreetMap is a convenient starting option: no Google Cloud account, no key, and it is easier to verify the map on a test page. Google Maps is still a sensible choice if the project already uses Google Cloud, needs a familiar basemap, relies on Google Places address suggestions, or treats the map as a central part of the page.

Each option comes with its own maintenance cost. OpenStreetMap is easier to turn on, but public Nominatim has reasonable-use rules, including rate limits and an expectation that the application be identifiable. Google Maps requires a key, enabled APIs, and properly configured key restrictions. So the "best provider" is not chosen by brand name alone - it depends on traffic, audience geography, team habits, and maintenance requirements.

Campaign Data Before the First Launch

Make a short list of campaigns that should appear on the map. For each one, prepare a verifiable location: city, street, or a well-known place. If a campaign is tied to a region rather than an exact address, decide in advance which point should be shown: the city center, a district office, the event venue, or a safe public reference point. Do not publish private addresses for beneficiaries, staff, or volunteers if that could put people at risk.

For testing, 3 to 5 campaigns are enough. Spread them across different locations so the map does not look like a single marker. Once the setup is verified, you can fill in the rest. This order saves time: if the provider or key is configured incorrectly, you will not be fixing dozens of entries blindly.

Installing the Extension and Running the First Check

Charitable Geolocation is installed the same way as a standard Charitable extension. The main Charitable plugin must already be active, then you add the extension file, and after that the geolocation settings and extra campaign fields appear in the admin area. You do not need to modify theme files, edit WordPress core, or paste code into templates just to launch a basic map.

A Safe Installation Sequence

1. Create a site backup or work on a staging copy if the map will be added to a live donation page.
2. Make sure the main Charitable plugin is active and campaigns open in the admin area without errors.
3. Install the Charitable Geolocation extension as a normal ZIP plugin through Plugins > Add New > Upload Plugin or through the Charitable extension installer if your version includes it.
4. Activate the extension using the Activate button.
5. Open the Charitable settings and find the geolocation or extensions section.
6. Save the settings even if you do not change anything, especially if the interface asks you to confirm the provider selection.

After activation, do not rush to place the map on your homepage. First verify that the settings path is available, that a Location tab or field has been added to campaigns, and that no admin-side errors appear. If the interface does not change at all, check that the main Charitable plugin is active, the version is compatible, and the extension itself appears in the plugin list.

First Test With a Single Campaign

Open an existing published campaign or create a test one. In the campaign settings, find the Location tab or geolocation field. Enter an address that is long enough to meet the interface threshold, choose an autocomplete suggestion if one appears, and save the campaign with Update. After saving, reopen the campaign and make sure the field did not reset.

If your version's newer documentation includes a Location Data Coverage card, use it as a checkpoint. It should show that at least one campaign is now mappable, meaning it has coordinates. If the counter does not change, the address likely remained in an "Address Only" state, was not converted to coordinates, or the field was not saved. That is an early sign that you need to investigate the provider, key, autocomplete, or user permissions.

Result check: after the first save, open a test page with the map, not just the campaign edit screen. The Location field may save correctly while the public map still fails to appear because of a shortcode parameter, block settings, campaign filters, cache, or a map API error.

Configuring the Map Provider and Google Key

The most important step after installation is choosing the map provider. This is where you decide whether the site will use OpenStreetMap/Leaflet without a key or Google Maps with an API key. That choice affects address suggestions, the basemap look, troubleshooting, key requirements, and possible external service costs.

If OpenStreetMap Is Available

If you can see an OpenStreetMap option in the settings, start with that for the initial test. For most moderate-traffic sites, it is the simplest route: the map and address suggestions work without a separate Google Cloud setup. But simple does not mean unrestricted. Public Nominatim asks you not to create heavy automated load, to use an identifying User-Agent or Referer, and to cache repeated results where appropriate.

In practical terms, that means the following: do not run mass geocoding for hundreds of imported campaigns in a single minute, do not let visitors generate endless address suggestions, and do not treat the public service as a replacement for your own geocoder in a large directory. For a standard Charitable campaign page, the load is usually modest, but for a larger project it is wise to discuss in advance with a developer whether you need a commercial or self-hosted geocoding setup.

What to Set First

• Map Provider: choose OpenStreetMap if you want the fastest start without Google Cloud.
• Default Distance Unit: choose kilometers for an audience that uses the metric system, or miles for a U.S. English-speaking audience.
• Default Map Center: set the center to the region where most campaigns are located so the empty map does not open somewhere random.
• Location Data Coverage: use the coverage card as a task list for campaigns that still lack coordinates.

After saving, check one campaign and then the public page. If the map loads but address suggestions behave inconsistently, do not judge the setup based on one address alone. Test another city, a more complete address, a local-language place name, and a coordinate-based option if the interface allows it.

If You Need Google Maps

Google Maps requires more preparation. According to the official instructions, you need to create an API key in Google Cloud, enable the Maps JavaScript API and Places API, and then paste the key into Charitable settings. Older documentation shows the path as Charitable > Settings > Extensions with a Google Places API Key field. In newer versions, the setting may live under the Geolocation tab as part of the provider selection flow.

The biggest mistake with Google Maps is pasting in a key and leaving it unrestricted. That key is exposed in browser requests because the map loads on the public site. So use HTTP referrer restrictions for the site domain and enable only the APIs you actually need. If Google shows a console message such as Google Maps API error, start with the exact error code rather than randomly changing settings.

Minimum Google Setup Sequence

1. Create or select a project in Google Cloud Console.
2. Create an API key under APIs & Services > Credentials.
3. Enable Maps JavaScript API and Places API if your version of Charitable Geolocation requires them.
4. Restrict the key to your site domain using HTTP referrers.
5. Paste the key into the Charitable geolocation or Google Places API field.
6. Save the settings and test the map in a private browser window.

Do not reuse the same unrestricted key across every agency site. For a production site, staging copy, and local development environment, it is better to have clear restrictions. That makes errors easier to trace, keys easier to rotate, and usage limits less likely to be consumed by another site.

How to Add Locations to Campaigns

Once the provider is selected, you need to fill in the campaigns themselves. This is the most time-consuming step if the site already contains a lot of content. The plugin cannot show a campaign on the map until that campaign has a valid location. Newer Charitable documentation describes provider-agnostic coordinate storage, which means latitude and longitude are not tied to a single provider, so switching maps should not destroy existing location data. But the coordinates still need to be generated and saved.

Manually Adding an Address to a Campaign

Open the campaign in the WordPress admin area. In the campaign settings, find the Location tab or the relevant geolocation field. Enter the address, wait for suggestions, choose the correct result, and save the campaign. If the field accepts manual coordinates or stores the address as a string, use a full address rather than a short word like a city name if you need a precise point.

The address needs to be understandable to the mapping service. For an international site, a full format works best: organization, street, city, country. For a local foundation, city and district may be enough if house-level precision is not appropriate. Do not publish sensitive addresses if the campaign involves private individuals, shelters, medical assistance, child protection, or any other situation where an exact point could cause harm.

Single-Campaign Check

• The campaign is published, not left in draft.
• The Location field is still populated after saving.
• The coverage card, if available, counts the campaign as mappable.
• A new marker appears on the public map, or the visible map area changes.
• When the marker opens, it is clear which campaign it belongs to.

If the marker does not appear, do not only check the address. The map may be showing only active campaigns, a specific category, a specific status, or a limited number of entries. The shortcode documentation mentions parameters such as status, category, tag, number, include_inactive, and others. One extra filter is enough to hide an otherwise valid campaign.

Populating Older Campaigns in Bulk

If the site already contains dozens of campaigns, do not start with a full bulk edit. First choose 3 campaigns: one active campaign, one from the target category, and one problematic or imported campaign. Add addresses to those, verify the map, and only then move on to the rest. This test shows where the issue actually is: the provider, the data, the display filters, or specific legacy records.

Current documentation mentions the Address Only state and the possibility of bulk geocoding imported campaigns through WP-CLI. That is already a task for an administrator who understands WP-CLI, provider limits, and the impact of external requests. For a typical user, the safer path is to save campaigns in small batches and leave the bulk workflow to a developer or technical specialist.

Campaign Map: Block, Shortcode, and Display Parameters

Once campaigns have coordinates, you need to display them on a page. Newer Charitable materials mention a Campaigns Map block, while the shortcode documentation describes the map parameter for [campaigns]. The right option depends on your version, your editor, and your normal content workflow. In the block editor, it is easiest to use the dedicated map block if it exists. In the classic editor, a widget, a template, or a page builder, a shortcode is usually more practical.

Shortcode [campaigns map=1]

Charitable documentation shows that the extension adds extra parameters to the [campaigns] shortcode. The key one is map. If you set map=1 or map="true", the campaign collection is displayed on a map. You can also set width, height, and initial zoom.

[campaigns map=1 width=900px height=600px zoom=5]

For most pages, it is better to start with width=100% and a sensible height such as height=500px or height=600px. A fixed width like 900px only works when the page container is guaranteed to be wider than that. On mobile screens, a fixed width can create horizontal scrolling, so test the map on more than just a desktop view.

When to Adjust zoom

If you have multiple campaigns in one city, the automatic zoom may be too close or too far out. In that case, set zoom manually. For campaigns spread across different countries, it is usually better to keep automatic behavior or choose a zoom level that does not hide distant points. During testing, open the page with different campaign sets: active only, one category, all campaigns. If the map reliably shows the points you need, the zoom level is appropriate.

Campaign Filters on the Same Page

The [campaigns] shortcode supports more than just the map - it also lets you filter the campaign collection. You can display campaigns from one category, change the number of entries, show only active campaigns, or include completed ones. That is useful when you want multiple pages instead of one general map: "School Fundraisers," "Regional Projects," "Team Campaigns," or "Urgent Appeals."

[campaigns map=1 category=school-projects status=active width=100% height=560px]

The strength of this approach is that it lets you align the map with the site's editorial structure. Visitors do not land on one overwhelming list of every campaign - they land on a map for the specific type of campaign they need. The downside is that it is easy to make the filter too narrow. If the category is entered incorrectly or there are no active campaigns with coordinates in that category, the map will be empty. So after publishing each shortcode, save the page and test it as a normal visitor.

If the Campaigns Map Block Is Available

If the WordPress editor includes a Campaigns Map block, start there. A block is usually easier for editors because there is less risk of mistakes with quotes, parameters, or syntax. For a technical administrator, a shortcode is still the more portable option: it is easy to insert into a template, a builder page, or project documentation.

Choosing between a block and a shortcode should not become an argument about the "correct" approach. What matters is that the map uses the same provider selected in settings and displays campaigns with real coordinates. If the block works, use the block. If your version does not include it, use the shortcode. If both are available, choose the one that will be easier to maintain for the person who actually updates campaigns.

Map Scale, Filters, and Behavior for Different Campaign Types

A campaign map is rarely the same across all sites. One foundation works within a few neighborhoods, another runs campaigns across the country, a third supports international initiatives, and a fourth uses the map as an archive of completed projects. In Charitable Geolocation, that means that once the map is technically enabled, you still need to configure the user-facing behavior separately: what zoom level to open with, which campaigns to show, how to explain the filter, and when not to force everything onto one map.

The biggest mistake is putting every campaign onto one map with no editorial purpose. If the site has many fundraisers, the map can become overloaded: markers cluster together, visitors cannot tell which campaigns are active, and completed projects compete with current ones. It is better to define the role of each map in advance. One page can be navigational - active campaigns only. Another can be report-focused - completed projects and the geography of your impact. A third can be topic-based - one category of campaigns.

Local Map: City, District, or Event

For a local foundation, school, parish, club, or sports team, the map usually needs to open close to the operating area. Here, the block height, initial center, and clear marker titles matter. Visitors should not need to zoom out from street level to country level just to understand where a campaign is located. If a default Map Center setting is available, set it to the city or district center. If you are using a shortcode, choose a zoom level that fits several points in view without over-zooming.

In a local setup, it is useful to limit the map to active campaigns and a single category. For example, a school fundraising page might show only campaigns in the school-projects category, while a volunteer events page shows only events. That makes the map easier to read. After publishing, be sure to test the edge case of a category with only one campaign. If a one-marker map feels too empty, add supporting text, a list of related campaigns, or a link to the broader section nearby.

Regional or National Map

When campaigns are spread across a country, the initial zoom should show the full area. There is little value in manually forcing a tight zoom onto one city. It is better to give the map some breathing room and explain that visitors can zoom into the region they need. In the page copy, mention that the map shows only campaigns with a completed location. That reduces confusion when some campaigns appear in a list but do not yet have coordinates.

For a regional map, categories and statuses are especially useful. Active fundraisers are usually better kept separate from report-style projects. If you want to show completed campaigns as evidence of the foundation's work, do not mix them with active campaigns unless the page clearly labels that distinction. Otherwise, a visitor may open a closed campaign and assume the site is outdated or the fundraiser is unavailable.

International Map and Address Formats

International campaigns require a stricter address format. A city name can exist in multiple countries, and the geocoder will not always guess the right one. For an international map, use an address that includes both city and country. If a point represents a region rather than an exact place, mention that in the campaign description and choose a safe public reference point.

Check how the map behaves with multiple distant markers. If one marker is in Europe, another in Africa, and a third in Asia, the starting view should help visitors understand the full geographic spread instead of zooming in around the first address only. If the map keeps opening around one campaign and hiding the others, review the center, zoom, and display filters. For some international sites, several region-based maps may work better than one oversized global map.

Filters as Part of the Page's Meaning

Shortcode parameters should not be technical accidents. Every filter should answer an editorial question: which campaign should a visitor see on this page? status=active works well for a page focused on current fundraising choices. category helps separate topics. number limits the campaign count when the map is embedded into a summary page. But any filter can hide the points you need, so test each one after every change.

A good workflow is to publish the map without filters on a private test page first. If markers appear, add the status. Then the category. Then a number limit, if you need one. After each step, check how many campaigns remain. This is faster than pasting in a complex shortcode immediately and then trying to figure out why the map is empty.

Quick Filter Check

• The campaign has the category or tag specified in the shortcode.
• The campaign status matches the output parameter.
• The number limit is not cutting off campaigns you need.
• The campaign has coordinates, not just an address string.
• The page cache has been cleared after changing the campaign or shortcode.

If the map becomes empty again, go back to the base shortcode [campaigns map=1]. That is your control point. If the base version works, the problem is in the parameters. If the base version is also empty, go back to the campaign data and the provider.

How to Design a Map Page That Supports Donations

Even a technically correct map can still make for a weak page if the visitor does not know what to do next. A campaign map should fit into the donation journey: first the person understands what the page is for, then chooses a region or marker, then opens a campaign and donates. If the map stands alone, without explanation, without connection to the campaigns, and without a clear next step, it turns into a visually attractive but ineffective block.

With Charitable Geolocation, it is especially important to keep the link to the main Charitable workflow intact. The map is not the final destination. It helps someone choose a campaign, while the donation itself happens on the campaign page through the Charitable form. That means the page structure should include a short intro, the map itself, an explanation of regions or campaign types, a fallback campaign list, and a link to the main fundraising page in case the map does not show the needed option.

The Hero Section of the Map Page

At the top of the page, visitors should immediately understand what they are looking at. Do not start with a huge map and no context. Add one short paragraph explaining which campaigns are shown, why they appear on a map, how to open details, and what to do if there is no nearby marker. This is especially important for older visitors, mobile users, and people arriving from search results onto an internal page.

If the map does not load instantly, there should be meaningful static text next to it or above it. That way the user does not see an empty area and assume the site is broken. A good pattern is a heading, one paragraph, and the map below. A poor pattern is making the map the first and only element, especially when external map resources may be blocked by the browser, a privacy extension, or a slow connection.

A Fallback Campaign List Under the Map

The map is helpful, but it should not be the only way to reach campaigns. It is usually smart to keep a normal list or grid of active campaigns below the map. That helps in several situations: the map fails to load, the visitor uses a keyboard or screen reader, markers are too close together, a campaign has regional meaning without an exact address, or the user is searching by project name rather than geography.

If you are using shortcodes, you can output the map with one shortcode and the campaign list with a separate block or shortcode using the same filters but without the map parameter. The key is not to create two different content rules. If the map shows the school-projects category, the list underneath should show the same category, otherwise visitors will see a mismatch and lose trust.

Marker Text and the Path to the Campaign

Charitable documentation and announcements show that the map can connect markers to campaigns and display campaign information. But the exact appearance of the pop-up depends on your version, theme, and settings. When testing, focus less on how pretty the marker looks and more on whether it works: is it clear which campaign this is, can the user open the full campaign page, is the title cut off, and does the pop-up cover too much of the map on mobile widths?

Use short, distinct campaign titles. If five markers all use names like "Support Fund," visitors will not understand the difference. Better options would be "School Supplies - Austin," "Shelter Food Drive - North District," or "Volunteer Team - Downtown." That is not a plugin setting - it is editorial discipline - but it is exactly what makes the map useful.

Accessibility and Non-Map Navigation

A map is harder for screen readers to interpret than a plain text list. That is why it is worth keeping a text-based campaign view next to it. The Alt text of an image in the article and the map caption do not solve the accessibility of the interactive map itself. Users need another path: a campaign list, links, categories, site search, or menu navigation.

The test is simple: try to find the right campaign without using the map at all. If that is impossible, the page depends too heavily on a visual interface. For a nonprofit site, that is a real risk, because part of the audience uses older devices, script blockers, high-contrast modes, and assistive technologies.

The Charitable Ambassadors Workflow and the Public Submission Form

One important product-specific use case for Charitable Geolocation involves Charitable Ambassadors. When Ambassadors is active, the public campaign submission form can include a Location field. That changes the workflow: the address is entered not only by an administrator in WordPress, but also by the participant creating the campaign on the public side of the site.

This is useful for peer-to-peer fundraising, team fundraisers, personal initiatives inside a larger campaign, regional ambassadors, and event-driven campaigns where participants create their own pages. It reduces manual admin work and helps the map fill up faster. But it also introduces a new risk: publicly submitted addresses may be inaccurate, too personal, or incompatible with the organization's publishing rules.

How to Build a Safe Workflow

Before enabling the public Location field, decide exactly what people are allowed to enter. For an open charity event, it makes sense to request the city and venue. For a personal medical fundraiser, a shelter, or direct aid to an individual, it is safer to show only the city, district, or region. The Location field should never pressure someone into revealing a private address if that is not necessary for the meaning of the campaign.

If the Location field is optional, users may skip it. That lowers the friction of campaign submission, but some campaigns will never appear on the map. If the map is your main navigation method for public campaigns, you can make the field required through a documented filter, but only after testing on a staging copy and only if your editorial policy truly requires a location for every campaign.

Safe Snippet to Make the Location Field Required

The official Charitable Geolocation documentation shows a filter for modifying Ambassadors form fields. The example below makes the Location field required if it has already been added by the extension. Add it through a child theme or Code Snippets, not into WordPress core, theme core, or plugin files.

<?php
add_filter( 'charitable_ambassadors_submission_form_fields', function( $fields ) {
    if ( isset( $fields['location'] ) ) {
        $fields['location']['required'] = true;
    }

    return $fields;
}, 20 );

After enabling it, open the public campaign submission form in a private window. Try submitting a campaign without a Location: the form should ask you to fill in the field. Then enter a safe test address and confirm that the campaign saves, goes through your moderation process, and appears on the map after publication. If users start abandoning the form or entering random addresses, roll back the snippet and return to an optional field with editorial review.

Moderation and Address Quality

For public campaigns, it is a good idea to add editorial review. Even if the geocoder found coordinates, the user may have chosen a city with the same name in another country, entered a home address instead of the event location, or provided text that is too vague. A good practice is to review new campaigns before publishing them, especially if the map appears on the homepage or a regional fundraising page.

Use one address format across the entire project. For example: "city, country" for an international map, "city, state" for U.S. campaigns, or "town, region" for local foundations. A consistent format makes searching easier, reduces duplicates, and helps the administrator understand why some campaigns are not appearing on the map.

Practical Example: A "Find the Nearest Campaign" Page

Let us walk through a practical workflow that many foundations with regional initiatives need. The goal is to create a page where visitors see a map of active campaigns, open the nearest fundraiser, and move on to donate. This example does not require template customization and relies on the built-in capabilities of Charitable Geolocation, Charitable campaigns, and either a map block or a shortcode.

Goal

You want a "Find the Nearest Campaign" page that shows only active campaigns with coordinates. The map should open in the region where the organization operates, have enough height for markers to be readable, and not replace the campaign page itself. The visitor uses the map for navigation, while the donation happens on the selected campaign page.

Preparation

• The main Charitable plugin is installed and working.
• Charitable Geolocation is activated.
• OpenStreetMap or Google Maps has been selected, and if you use Google, a valid API key has been entered.
• There are at least three published active campaigns with locations.
• The editor knows where the new page will live on the site and how it will be connected to the menu.

Steps

1. Open the first campaign, fill in the Location field, and save it.
2. Repeat this for several more campaigns so you can test the zoom level and marker distribution.
3. Create a new WordPress page with a clear title such as "Find the Nearest Campaign."
4. If the Campaigns Map block is available, insert it and configure it to display active campaigns.
5. If you are using a shortcode, add a Shortcode block and insert [campaigns map=1 status=active width=100% height=560px].
6. Publish the page, open it in a private window, and verify the map without administrator privileges.
7. Add the page to the menu or connect it to the campaigns section if the map will be a permanent entry point.

Expected Outcome and Verification

The page should display a map with markers for active campaigns. When you click a marker, the visitor should understand which campaign it represents and have a path to the full campaign page. The map should load quickly, should not break the page width, and should not overlap the donation form if the form appears lower on the page.

Check the page in three states: desktop browser, mobile width, and a private window. Then temporarily add a test campaign in the target category, save its Location, and confirm that the map updates. If page caching is enabled, clear the cache after the change and test again.

One Common Pitfall

If the shortcode filters campaigns by category, and the test campaign is not assigned to that category, it will not appear on the map. This looks like a geolocation failure, but the real cause is the display parameters. That is why troubleshooting should start with the simplest version, [campaigns map=1], and only then bring back category, status, number, and the other filters.

An Editorial Policy for Location-Based Campaigns

Technical map setup is only half the job. The other half is maintaining campaign data so the map does not become outdated. Charitable Geolocation shows whatever is saved in campaigns. If editors forget addresses, use inconsistent formats, leave completed campaigns active, or stop checking markers after edits, the map quickly stops being a trustworthy source.

Create a short policy for the team. It does not need to be a formal document. A single internal knowledge base page is enough: when to fill in Location, what level of precision to use, who verifies addresses, what to do with completed campaigns, and how to test the public map after publishing. This is especially important if campaigns are created by multiple staff members, volunteers, or ambassadors.

Use a Consistent Address Format

Choose one format and stick to it. For international campaigns, that might be "city, country." For a national foundation, "city, region." For events, "venue, city." For offices and public support locations, a full address. A consistent format reduces geocoding errors and makes the map easier to validate visually.

Do not mix exact addresses and very broad regional points without explanation. If one campaign shows a specific building and another shows an entire area, visitors may misread the scale. In the campaign description, explain that the map point is a reference point if you intentionally do not publish the exact address.

Campaign Statuses and the Map

If the map shows only active campaigns, completed fundraisers should disappear from it or move into a separate archive. If the map includes completed campaigns as well, visitors should understand that some points are already closed. The shortcode documentation includes status parameters and the ability to include inactive campaigns. Use those intentionally rather than leaving old fundraisers mixed in with active ones without explanation.

For a "Find the Nearest Campaign" page, active campaigns usually make the most sense. For a "Geography of Impact" page, completed projects may be appropriate, but then the purpose of the page changes: it becomes a report and proof of work, not a path to donation. The same plugin can support both use cases, but the shortcode, copy, and labels should be different.

Checklist After Publishing a New Campaign

Add a short checklist to your campaign publishing process:

1. The campaign title is clear without opening the card.
2. Location is filled in using the chosen format.
3. The map point does not reveal unnecessary personal information.
4. The campaign is published and has the correct status.
5. The category or tag matches the map where the campaign should appear.
6. The public map page updates after the cache is cleared.

This list looks simple, but it prevents the most common errors. When a campaign does not appear on the map, administrators often blame the Google key or the extension, even though the actual cause may be draft status, the wrong category, or an address with no coordinates.

How to Handle Campaigns Without an Exact Public Address

Sometimes the organization needs the address internally, but it should not be public. In that case, do not try to "hide" the exact address only at the visual level. It is safer not to save it as the public Location for the map at all. Use a safe point instead: city, district, nearest public landmark, the foundation office, or a regional center. In the campaign description, you can say plainly that the exact location is not published for safety reasons.

If the team still stores exact addresses in another system, keep that data separate. Charitable Geolocation should display only what is acceptable for a public campaign map. Internal addresses, contacts, and detailed records are better kept in a CRM, a restricted-access spreadsheet, or another secure tool, not in the public campaign map.

Verifying the Result After Setup

Once the map is published, it is not enough to say "it opened for me." The map depends on several layers: campaign data, the provider, the block or shortcode, the WordPress page, the theme, cache, the browser, and external requests. Validation should move from the data layer to the public-facing result, otherwise it is easy to miss an error that donors will still see.

Data Check

Start in the admin area. Make sure every campaign that should appear on the map is published and has a Location. If the settings include Location Data Coverage, compare the number of campaigns with coordinates to the total number of published campaigns. A high count of Address Only or No Location does not mean the map is broken - it means the campaign database is not ready yet.

If you have imported campaigns, check several older entries manually. The import may have saved an address string but failed to generate latitude and longitude. In that case, the campaign looks complete to the editor but is not a true map point.

Public Page Check

Open the map as a regular visitor. Do not rely only on an administrator account, because an admin may see unsaved drafts, bypassed cache, or extra interface elements. Check the following:

• The map loads without a dark overlay, key warnings, or an empty container.
• The markers match the published campaigns.
• The shortcode or block filters are not hiding campaigns that should be visible.
• The map height is sufficient, so visitors do not just see a narrow strip.
• The map does not create horizontal scrolling on mobile widths.
• After clicking a marker, there is a clear path to the campaign or clear campaign information.

Check After Switching Providers

If you switched from OpenStreetMap to Google Maps or back, do not test only the new map itself - test the older campaigns as well. Current documentation says that campaign coordinates are stored independently of the provider, but the behavior of the basemap, address suggestions, and default center may still change. So after switching providers, walk through a short path: settings, one older campaign, one new campaign, the public map, mobile width, and the browser console.

Critical standard: the setup is only truly verified when a published visitor can see the map, the expected campaigns, and a clear path to donate. A saved Location field in the admin area is an intermediate step, not the final check.

Safe Enhancements and Controlled Customization

Charitable Geolocation does not require code for basic use, but advanced projects sometimes need targeted adjustments: forcing the public map to use OpenStreetMap, making Location required for ambassadors, setting a regional map center, or moving the Google key out of the database. The official documentation shows filters for these cases. Use them carefully: test on staging first, then on the live site, and always keep a clear rollback path.

Forcing OpenStreetMap on the Public Page

Imagine that Google Maps is more convenient in the admin area, but you want the public campaign map to use OpenStreetMap in order to reduce dependence on the Google key. The documentation provides the charitable_geolocation_map_provider filter. The example below leaves the global setting unchanged, but returns leaflet on the page with the slug public-campaign-map.

<?php
add_filter( 'charitable_geolocation_map_provider', function( $provider ) {
    if ( is_page( 'public-campaign-map' ) ) {
        return 'leaflet';
    }

    return $provider;
} );

The test is simple: open the page with that slug and confirm that the map uses the intended basemap. Then open another page with a map and check that it has not changed. If the result is unexpected, disable the snippet in Code Snippets or remove the code from the child theme. Do not leave a filter like this undocumented in project notes: otherwise a future administrator will look for the cause in Charitable settings and never understand why one page behaves differently.

Setting a Regional Default Map Center

By default, Map Center affects the state when the map has nothing to show yet or when the relevant markers have not loaded. For a local foundation, it is usually better to set the center to your city or region instead of leaving a generic default point. If the interface supports it, use the latitude and longitude fields in settings. If you need a code-based approach for a project with custom rules, the documentation shows the charitable_geolocation_default_center filter.

<?php
add_filter( 'charitable_geolocation_default_center', function( $center ) {
    return array(
        'lat' => 51.5074,
        'lng' => -0.1278,
    );
} );

Replace the coordinates with the center of your operating area. After saving, test a page where filters temporarily leave no campaigns to display. The map should open in the region you specified. If the coordinates were entered incorrectly, visitors may see the wrong city or even the wrong country. The rollback is the same: disable the snippet or restore the setting through the interface.

Compatibility With Cache and Theme

Maps depend on JavaScript and external requests, so caching and optimization plugins can affect how they load. Do not disable all site caching at the first sign of trouble. First test the page without script minification, then exclude the specific map page from aggressive deferred loading if the optimizer is delaying or combining Google Maps, Leaflet, or Charitable scripts. If the map starts working after that exclusion, the issue was not campaign data - it was the script loading chain.

Theme issues are more often visual: a container that is too narrow, hidden overflow, height conflicts, or a map placed inside a tab or accordion that loads in a hidden state. If the map appears as a gray rectangle inside a hidden tab, try moving it to a plain page with no tabs. That separates a map problem from a layout problem.

SEO, Performance, and Privacy on a Map Page

A map page should help visitors, but it does not need to become the heaviest page on the site. An external map library, basemap tiles, autocomplete, and markers all add requests. For a nonprofit site, this matters even more: a visitor may arrive on mobile data, and the donation form still needs to remain accessible.

SEO Without Over-Optimization

A map alone does not guarantee more search traffic. Search value appears when the page explains which campaigns are available, how to choose a fundraiser, which regions are covered, and what to do next. So add a short helpful text near the map: who the page is for, why the campaigns are shown on a map, how to open the full campaign page, and what to do if the needed region is missing.

Do not stuff headings with repeated plugin names. Normal phrasing works better: "Map of Active Campaigns," "How to Check Whether a Campaign Appears on the Map," or "Why a Marker Did Not Show Up." Headings like these make sense to people and match real search intent such as "how to set up a Charitable campaign map" or "why Charitable map is not showing campaigns."

Loading Speed

If the map sits on the homepage, it may load for every visitor. Sometimes it is better to place it on a dedicated "Find a Campaign" page and leave only a link or a short block with a few important campaigns on the homepage. That reduces above-the-fold load and keeps the map for people who actually want to browse by location.

For shortcodes, use a height that does not force the map to constantly recalculate during load. Avoid nesting the map inside complex tabs, carousels, and popups unless you truly need that structure. If script optimization breaks the map, exclude only the problematic page or the specific mapping scripts instead of turning off performance features site-wide.

Privacy and Address Precision

Geolocation is tied to addresses. Even when a campaign is public, the precision of the point should be chosen deliberately. A foundation office or public event venue can usually use an exact address. For personal aid, social housing, shelters, medical stories, and other sensitive fundraisers, it is usually safer to use the city, district, or another neutral public point.

If you use Google Maps, the public side of the site communicates with Google services. If you use OpenStreetMap/Nominatim for suggestions, keep the usage rules in mind and do not send sensitive addresses unless you truly need to. It is also worth describing which external services are involved in map rendering in the site's privacy policy if that matters for your audience or jurisdiction.

Troubleshooting Common Problems

Most Charitable Geolocation issues are easiest to diagnose by following the chain: campaign data, provider settings, map output, browser console, cache, and theme. Do not change multiple parameters at once. One step, one check, one result. That is the fastest way to see exactly where the map is failing.

The Map Does Not Load or Shows a Google Maps Error

Symptom: instead of a map, you see a dark overlay, a development-mode message, an empty container, or a browser console error beginning with Google Maps API error. Official Google documentation explains that these errors are often tied to the API key, billing, enabled APIs, or key restrictions.

What to check: open browser developer tools, go to the Console tab, refresh the page, and find the exact error code. Then confirm that the key is entered in Charitable settings, the required APIs are enabled, the site domain is allowed in HTTP referrers, and the Google Cloud project has the correct billing setup if the selected Google product requires it.

How to fix it: do not create a new key blindly. Start by fixing the exact error code: enable the missing API, add the domain, remove an incorrect IP restriction for a client-side map, or update the key in settings. After making the change, clear the page cache and test the site in a private window.

The Map Loads but Shows No Campaigns

Symptom: the basemap is visible, but there are no markers. That means the map provider itself is working, and the problem is most likely in the campaign data or the display filters.

What to check: open the campaigns that should appear on the map. Make sure they are published, active, and have a Location. If Location Data Coverage is available, check how many campaigns have coordinates, how many are in the Address Only state, and how many have no location at all. Then temporarily replace the complex shortcode with a simple [campaigns map=1].

How to fix it: resave the addresses for several campaigns, verify the category and status, and temporarily remove the category, tag, status, and number filters while diagnosing. If markers appear afterward, bring the filters back one at a time.

The Address Saves but Coordinates Never Appear

Symptom: the campaign contains an address string, but the map does not show it, and coverage counts the record as Address Only. This can happen after an import, after changing providers, or when autocomplete fails.

What to check: enter the address manually and choose a suggestion if one is available. Use a more complete address with city and country. For OpenStreetMap, keep Nominatim limits in mind and do not run bulk requests too quickly. For Google, verify both Places API and Maps JavaScript API.

How to fix it: resave the campaign, check the console, and test a different address. If you have many imported campaigns and your version's documentation supports bulk geocoding through WP-CLI, run it only after testing on a small group and only with provider limits in mind.

The Location Field Does Not Appear in the Ambassadors Form

Symptom: the administrator expects a location field in the public campaign submission form, but visitors do not see it. This is usually because Ambassadors is not active, Geolocation is not enabled, the form is not actually a campaign submission form, or an older template is being used.

What to check: make sure both extensions are active, the form is being rendered through the correct Charitable Ambassadors mechanism rather than a third-party form, and test the page without cache and with a temporary default theme on a staging copy. If the field appears only in the default theme, the problem is in the template or an override.

How to fix it: update the form template, disable conflicting overrides, and check whether CSS is hiding the Location field. If you added a snippet that makes the field required, temporarily disable it and confirm the default behavior first.

The Map Breaks the Layout on Mobile

Symptom: the map extends outside the container, creates horizontal scrolling, or becomes too short to use. The cause is usually a fixed shortcode width, theme limitations, or a map embedded inside a complex layout block.

What to check: replace width=900px with width=100%, keep a reasonable height, and open the page at mobile width. Check whether the parent container has CSS rules that hide content or enforce an overly small height.

How to fix it: use a relative width, avoid putting the map in a narrow sidebar, and avoid hidden tabs. If the map needs to live in a side column, it is usually better to place a link there to a dedicated full-size map page.

The Map Worked Until Optimization Was Enabled

Symptom: the map displayed correctly before caching or minification was enabled, but after optimization you see an error or an empty block. The issue is usually related to JavaScript load order.

What to check: temporarily disable script combining, deferred loading, and delayed JavaScript execution for the map page. If the map returns, create an exclusion rule only for the necessary scripts or only for the map page. Do not leave the entire site without caching if you can isolate the conflict more precisely.

How to fix it: save the rule in the optimizer settings and test the page again after clearing the cache. If you are not sure which scripts need to be excluded, start by excluding the map page itself and then refine the rule together with a developer.

Useful Combinations With Other Charitable Features

Geolocation becomes much stronger when it is built into the larger campaign system instead of hanging off a separate page. But each combination should be described honestly: only what is confirmed by documentation or the developer's site should be called an official integration. Everything else is simply a practical setup built from standard WordPress and Charitable functionality.

Geolocation + Campaigns shortcode

The most obvious combination is the map with the [campaigns] shortcode. Geolocation handles coordinates and the map, while the shortcode controls which campaigns appear in the output. That makes it possible to build several different pages: a general map, a map of active campaigns, a category-specific map, or a map of team fundraisers.

The setup order is straightforward: provider first, then campaign addresses, then a simple map, then filters. The most likely conflict is an overly narrow filter or an incorrect category slug. The check is to open the map without filters and then add parameters one at a time. The rollback is to remove the filters and return to the base shortcode.

Geolocation + Ambassadors

If the site uses Charitable Ambassadors, a Location field in the public form reduces manual admin work. Participants enter the location themselves, and the administrator reviews the quality before publishing. This is especially practical for local teams, school groups, sports events, and personal pages inside a larger initiative.

The main risk is the quality of public data. That is why the form needs supporting text explaining what exactly should be entered, whether an exact address is allowed, and when a city alone is enough. The verification step is to create a test campaign as a normal user and follow the full path to the map. The rollback is to make the field optional again or disable the snippet that made it required.

Geolocation + Reporting and Editorial Workflow

Charitable already includes campaigns, donations, donors, and reporting, while geolocation adds the geographic layer of those campaigns. Even if the map does not directly affect reports, it strengthens editorial discipline: every local campaign should have a responsible region, a valid address, and a clear public campaign card.

A practical workflow is to add "check Location" to the editorial policy, use the coverage card as a task list, and regularly review campaigns that still have no location. The possible problem is that the team may start treating the map as the only source of truth. That is inaccurate: the map shows only campaigns with valid coordinates, not everything the foundation is doing.

Questions to Resolve Before Launching the Map

Can you use Charitable Geolocation without Google Maps?

Current official descriptions for newer versions mention OpenStreetMap via Leaflet as an option that does not require a Google API key. But the interface depends on your installed version. If the settings include a Map Provider choice, start with OpenStreetMap for testing. If your version shows only a Google Places API Key field, follow the Google workflow or check the developer documentation for updates.

Why does a campaign with an address not appear on the map?

An address string and coordinates are not the same thing. A campaign can have an address but still have no saved latitude and longitude. Check Location Data Coverage if that card is available, resave the campaign, choose an address suggestion, and temporarily remove shortcode or block filters.

Should the Location field be required for Ambassadors?

Only if the map is an important part of your public campaign directory. A required field improves map completeness, but it can also interfere with submissions and push users to enter random or overly personal addresses. Test the optional field first, then decide.

What is better for an international foundation: kilometers or miles?

Choose the unit that is clearest to your primary audience. Geolocation settings describe a default Distance Unit, which affects distance labels and distance-based sorting if you use it. For Russian-speaking, European, and most international audiences, kilometers are usually more intuitive. For a U.S. audience, miles are often more familiar.

Can the map be placed on the homepage?

Yes, but that does not always mean it should be. If the map helps visitors quickly choose a regional campaign, it makes sense. If the homepage needs to load as fast as possible and push people toward one main donation form, a link to a separate map page is often the better option. Check performance and mobile rendering before publishing.

Why did the map stop working after caching was enabled?

The optimizer may have changed JavaScript load order or delayed the map scripts. Test the page without script combining and delay, then create a targeted exclusion for the map page or the required files. Do not disable caching for the entire site if the problem can be solved locally.

Is it safe to show exact campaign addresses?

Not always. For public events and office locations, an exact address may be useful. For private aid, medical stories, social projects, and vulnerable groups, it is usually better to use the city, district, or another safe point. Geolocation should help donors, not expose unnecessary personal information.

When Charitable Geolocation Is the Right Choice

Charitable Geolocation is worth using when location genuinely helps people choose a campaign and your team is ready to keep address data organized. The plugin is especially effective for local initiatives, regional foundations, ambassador campaigns, events, teams, and projects where a map makes the purpose more obvious. It does not replace strong campaign copy, a good donation form, or solid reporting, but it adds an important navigation layer.

Before launch, verify the full chain: the provider is selected, campaigns have coordinates, the map is displayed through a block or shortcode, the mobile view does not break, the browser console shows no errors, cache does not interfere with scripts, and your address policy does not expose unnecessary data. If that chain holds up, you can download Charitable Geolocation and test the extension on your site copy.

The best outcome looks simple: the editor adds a campaign, enters a safe location, saves the entry, and the visitor sees a clear map and quickly moves to the right fundraiser. If that is what you achieved, the map is doing its job. If the map raises more questions than it answers, start small: one test page, a few campaigns, one provider, and calm step-by-step troubleshooting.