Upgrading Ninja Geolocation from 3.1.x to 3.5

Introduction

Ninja Geolocation 3.5 is a major upgrade. It introduces package-aware feature loading, current Google Maps Platform services, an embedded WPGeo Framework runtime, expanded fields, and versioned migration of existing settings and forms.

Do not treat this as a routine point update. Create a complete backup and test the full update on staging before installing it on a production website.

Before you upgrade

1. Create a complete database backup and a complete file backup.
2. Restore both backups to a staging site and perform the upgrade there first.
3. Record the installed plugin version, package name, license status and Google API configuration.
4. List the forms and pages that use geolocation fields, repeaters or submission-map shortcodes.
5. Retain the exact pre-upgrade plugin ZIP for rollback.

Requirements

• WordPress 6.5 or newer.
• PHP 7.4 or newer.
• Ninja Forms 3.13.2 or newer active.
• A Google Cloud project with billing and the APIs required by the site's features.
• The Ninja Geolocation package supplied for the license.

The compatible WPGeo Framework runtime is embedded in Ninja Geolocation. A separate framework plugin is not required.

Confirm the package

Compare the Starter, Pro, and Agency packages before selecting the ZIP.

• Starter: core location fields and tools, 1 site.
• Pro: Starter plus validation, routing and submission maps, 3 sites.
• Agency: Pro plus nearest-location and drawing tools, 20 sites.

Personal and Business are legacy license names. Eligible Personal and Business entitlements are delivered through the canonical Pro package; they are not separate 3.5 ZIP builds. Do not replace a legacy entitlement with Starter merely because the original license may have a smaller site allowance.

The installed package determines feature availability. A license key does not add implementations excluded from the ZIP. A valid activation provides eligible updates and support; an expired license does not remove field implementations that are already installed.

Prepare Google APIs

Version 3.5 normally uses Places API (New) and Routes API. Review Google Maps API Keys for Ninja Geolocation 3.5 before updating.

• The Browser key can require Maps JavaScript API, Places API (New), Routes API, Address Validation API and Maps Static API.
• The Server key can require Geocoding API and Routes API for database-source nearest-location matrix calculations.
• Routes API may therefore need to be allowed on both keys.

Temporary Places API (Legacy) and Directions API (Legacy) fallbacks are intentionally narrow. They do not cover validation, distance, nearest-location or other 3.5 features and do not replace the new services.

Install the update

1. Confirm that the backups can be restored.
2. Install the correct 3.5 package using the WordPress updater or replacement ZIP upload.
3. Activate the plugin if WordPress does not reactivate it automatically.
4. Open the local license controls and confirm that the package and activation are correct.
5. Open Ninja Forms → Settings → Geolocation and review both API keys, region/language settings and advanced marker behavior.
6. Clear WordPress, host, object and CDN caches.

What migrates

The versioned migration runs automatically and completes its steps in this order:

1. License data
2. Plugin settings
3. Forms and actions
4. Top-level and repeater field settings

The migration records completion only after every step succeeds. Running it again is safe: current 3.5 values take priority, legacy keys are retained and nested repeater field settings are processed recursively.

Examples of normalized settings include Auto Locator targets, Address autocomplete values, Directions methods and travel-mode vocabulary, manual/automatic trigger values and legacy field references.

Historical submission values are not rewritten. Legacy Base64-encoded Geocoder, Map and Directions values are decoded when read. This preserves the original stored bytes and avoids a destructive bulk rewrite.

Compatibility notes

• Existing sites retain Standard Marker behavior; Advanced Markers remain the default for new installations.
• Legacy Places autocomplete and Directions fallbacks activate only for narrowly recognized “new API unavailable/disabled” conditions.
• The Places fallback does not activate for quota, billing, invalid or expired key, referrer, transient or unrelated permission failures.
• The Directions fallback applies only to the Directions field and does not support Two-wheeler mode.
• If both the current and legacy Directions providers fail, the field completes without a route so the form-processing queue is not left waiting indefinitely.
• Legacy Directions Panel stored-value output is intentionally deprecated. Use the Directions field's value and merge tags.
• The historical Mashup Map attribute forms_id is not recognized by the current shortcode. Update it to the supported Mashup Map attribute form_ids: forms_id="7,12" becomes form_ids="7,12".

Verification checklist

1. Open and save an existing geolocation form.
2. Test Address autocomplete and select a suggestion.
3. Confirm that connected Geocoder, Coordinates and Map fields synchronize.
4. Submit and inspect a new location.
5. Open an old submission and confirm that legacy Geocoder, Map and Directions output remains readable.
6. If using repeaters, add, remove and reindex rows and retest autocomplete and linked fields.
7. Test every Pro/Agency feature used by the site with known data.
8. Test Single Submission and Mashup Map shortcodes if used.
9. Inspect the browser console for API, referrer, billing or JavaScript errors.
10. Run the same critical checks again after cache/CDN clearing.

Rollback

If the staging or production verification fails and the issue cannot be corrected safely:

1. Stop new form submissions temporarily.
2. Restore the complete pre-upgrade database.
3. Restore the matching pre-upgrade Ninja Geolocation files.
4. Clear all caches.
5. Verify a known form and submission before reopening the workflow.

Do not manually delete migration options or partially reverse field settings. The retained legacy keys are compatibility data, not a substitute for a tested full backup.

Troubleshooting

Select the issue below that best matches what you are experiencing.

Helpful Links

• Installing and Activating Ninja Geolocation
• Google Maps API Keys for Ninja Geolocation
• Ninja Geolocation Plans and Feature Comparison