Upgrading WP Job Manager Geolocation from 2.3.3 to 3.0
WP Job Manager Geolocation 3.0 is a major rebuild. It introduces Starter and Pro packages, embeds the WPGeo Framework runtime, moves existing locations into WPGeo location storage, and reorganizes the plugin settings and license tools.
Do not treat this as a routine point update. Back up and test the complete upgrade on staging before updating a production job board.
Begin only when the stable 3.0 package is offered in your account or WordPress updater. If the available download is still 2.3.3, wait rather than installing a beta or release-candidate build on production.
Before you upgrade
- Create a complete database backup and a complete file backup.
- Restore those backups to a staging site and perform the upgrade there first.
- Record the currently installed WP Job Manager Geolocation version, active package, license status, Google API key configuration, and pages that contain geolocation shortcodes.
- Confirm that the staging site can send outgoing HTTPS requests to Google Maps Platform and to the licensing service.
- Plan a maintenance window for the production update, particularly if the legacy location table contains many rows.
The version 3.0 migration leaves the legacy places_locator table intact, but that table is not a complete website backup. A reliable rollback requires the matching pre-upgrade database and plugin files.
Check the requirements
WP Job Manager Geolocation 3.0 requires:
- WordPress 6.5 or newer.
- PHP 7.4 or newer.
- WP Job Manager 2.0 or newer.
- A Google Cloud project with billing and the required Google Maps Platform services enabled.
- An eligible WP Job Manager Geolocation license for updates and support.
The compatible WPGeo Framework runtime is included in the plugin package. Do not install a separate framework plugin for this upgrade.
Choose Starter or Pro
Starter
Starter provides the core geolocation features for WP Job Manager job listings and is available for one website.
Pro
Pro includes the job-listing features plus Resume Manager and Job Alerts integrations. Pro is available for 1, 3, or 20 websites.
Important: Pro does not include WP Job Manager’s own extensions. Resume features require the separately installed WP Job Manager Resume Manager extension version 2.0 or newer. Alert features require the separately installed WP Job Manager Job Alerts extension version 3.0 or newer.
Follow Resume Geolocation Setup and Migration and Job Alerts Geolocation Setup when those Pro integrations are active.
Starter and Pro are different plugin packages. A license activates eligible updates and support for the installed package; entering a Pro license into a Starter package does not add the Pro files. Install the Pro package when moving from Starter to Pro.
Standalone Resume Manager Geolocation extension
The former standalone Resume Manager Geolocation extension is no longer required because its functionality is included in WP Job Manager Geolocation Pro. Keep your complete backup, install and verify Pro first, and then deactivate and remove the standalone extension. Version 3.0 displays an administrator notice while that deprecated extension remains active.
Prepare the Google API keys
Version 3.0 uses two keys with different restrictions:
- Browser API Key: a website-restricted key used for maps, address autocomplete, and browser-side geocoding.
- Server API Key: an IP-restricted key used privately by WordPress for server-side geocoding.
Enable the following services in the Google Cloud project:
- Maps JavaScript API
- Places API (New)
- Geocoding API
Sites upgrading from 2.3.3 may already have Places API (Legacy) enabled. That does not replace Places API (New) in version 3.0. Enable Places API (New) and add it to the Browser API Key’s API restrictions before upgrading. Routes API is not required for this plugin’s proximity searches.
Follow Generating Google Maps API Keys for the complete service and restriction setup. Allow a few minutes for newly enabled services or changed restrictions to propagate.
Upgrade the plugin
- Confirm that the file and database backups can be restored.
- Install the correct Starter or Pro package through the normal WordPress update flow or by uploading the replacement ZIP.
- Activate the plugin if WordPress does not reactivate it automatically.
- Open Job Listings → Settings → Geolocation → License and confirm the license status. Connect the WPGeo account or activate a compatible license if needed.
- Open Job Listings → Settings → Geolocation → General, enter the Browser API Key, and review the country, language, and autocomplete settings.
- Confirm the Server API Key under Job Listings → Settings → General. Return to the Geolocation General tab and use Test API Key to test server-side Geocoding API access.
The built-in Test API Key action checks the Server API Key against the Geocoding API. It does not test the Browser API Key, Places autocomplete, or map rendering; those must be verified on the front end.
Complete the location migration
Version 3.0 copies legacy rows from places_locator into WPGeo location storage in bounded batches. Jobs and resumes are processed together. The migration is retry-safe, does not geocode addresses, can retain rows even when the related post no longer exists, and does not alter or delete the legacy table.
The plugin processes a bounded batch on eligible requests while the migration is incomplete. During that period, administrators see a notice explaining that location-based search results may be incomplete.
To complete the process without waiting for additional requests:
- Go to Job Listings → Settings → Geolocation → Tools.
- Find Location Upgrade.
- Click Finish / Resume Migration.
- Keep the page open while the progress runner processes the remaining batches.
- Confirm that the panel reports completion and that the migration notice disappears.
If a batch fails, the migration remains incomplete and can be resumed after the underlying error is corrected. Read Location Tools: Migration and Repair for the migration runner and the separate missing-location repair workflow.
Review geolocation shortcodes
Version 3.0 uses wpjmgeo_mode to enable geolocation on the standard WP Job Manager shortcodes:
[jobs wpjmgeo_mode="settings"]uses the saved Search & Map settings.[jobs wpjmgeo_mode="shortcode"]uses geolocation attributes supplied directly in that shortcode.[resumes wpjmgeo_mode="settings"]is the Pro equivalent for Resume Manager.
For clarity, replace the older wpjmgeo_use="2" value with wpjmgeo_mode="settings", and replace wpjmgeo_use="1" with wpjmgeo_mode="shortcode". Version 3.0 retains compatibility handling for the older values, but new and updated pages should use the current attribute.
See Geolocation Shortcode Attributes for the complete reference.
Verify the upgraded site
- Clear WordPress page and object caches, the host cache, and any CDN cache.
- Create or update a test job with address autocomplete and confirm that coordinates are saved.
- Run a location search with a known result and verify the radius, distance, ordering, and marker.
- Test a search with the results map disabled; proximity search does not require a visible map.
- Open a single job and verify its map and marker.
- If a separate search/listing shortcode and results-map shortcode are used, confirm that both use the same explicit element ID.
- In Pro, repeat the search and map checks for resumes.
- In Pro with Job Alerts installed, create or update a location-based alert and verify that the form works in the active theme.
- Open the browser console and confirm that Google is not reporting blocked services, invalid referrers, or billing errors.
If existing posts still lack indexed locations after the versioned migration completes, use Scan for Missing Job Locations or, in Pro, Scan for Missing Resume Locations. These repair tools are separate from the one-time legacy-table migration and do not overwrite existing WPGeo locations.
Rollback plan
If the staging or production verification fails and the issue cannot be corrected safely:
- Stop new listing submissions and edits.
- Restore the complete pre-upgrade database.
- Restore the matching WP Job Manager Geolocation 2.3.3 plugin files.
- Clear all application and CDN caches.
- Verify a known job search and listing before reopening the site.
Do not delete WPGeo rows, edit migration markers, or rely on the retained legacy table as a substitute for restoring the tested backup.