AI Location Improvement
AI Location Improvement runs an AI pass over the locations already in your workspace. It reads your existing records as a group, finds missing fields, inconsistent naming, and structural patterns the data suggests, then surfaces a draft of suggested changes you can review and selectively apply.
It is not an import tool — it only changes records you already have. Use AI Location Import to create new locations from scratch.
When to use Improvement vs. Import
| Goal | Use |
|---|---|
| Fill in missing phone, website, or hours on existing locations | AI Location Improvement |
| Normalize inconsistent addresses and naming across a large set | AI Location Improvement |
| Generate new locations you don’t have yet | AI Location Import |
| Enrich freshly imported locations with a follow-up cleanup pass | AI Location Improvement |
Where to find it
AI Location Improvement is available in two places inside the Finder Builder:
Row Improver — improves a single location. On any location row in the Locations tab, look for the AI improvement button (or the “AI row improver” label in the panel header). The panel runs the AI pass on just that one record and shows you the suggested patch alongside the current values.
Builder Improvements (Structural) — improves your entire workspace in one pass and also suggests tag, category, and cleanup recommendations that span multiple locations. Open the AI Hub panel (the AI icon in the Finder Builder toolbar) and choose Builder Improvements, or complete an AI Import and click Review Builder Improvements on the post-launch screen.
🟡 [SCREENSHOT: Finder Builder toolbar showing the AI Hub icon and the panel header labelled “Builder Improvements”]
🟡 [SCREENSHOT: Row Improver panel showing the “Current location” card on the left and the “AI suggested patch” card on the right]
How to trigger an improvement run
Row Improver (single location)
- Open the Finder Builder for the finder you want to work on.
- On the Locations tab, click the AI icon or “Improve with AI” button on a location row.
- The AI Hub panel opens in AI row improver mode and begins generating a suggestion automatically.
- When the suggestion appears, review the fields in the “AI suggested patch” card.
- Edit any fields you want to change, then click Approve to accept the suggestion or Apply now to write the changes immediately.
Builder Improvements (workspace batch)
- Open the AI Hub panel from the Finder Builder toolbar.
- If a previous improvement batch is pending, you’ll see a “Recent AI cleanup batch” card — click Open AI maintenance to resume it instead of starting a new one.
- To start a fresh run, click Run Builder Improvements. The process is queued immediately.
- The panel shows a progress log while the AI works. You can close the panel — you’ll be notified when suggestions are ready.
- When generation completes, the panel enters the review step automatically.
💡 Tip: A scoped run is faster and more reliable than a full workspace run. If you only need to fix a subset of locations, use the Row Improver or contact support about filtering by location IDs.
What gets improved
The AI reviews each location record against the full workspace dataset and suggests updates for:
| Field | AI can fill in | AI can improve |
|---|---|---|
| Name / title | No | Yes — normalizes casing and formatting |
| Street address | Yes — if inferable from context | Yes — normalizes format |
| City / state / zip / country | Yes — if inferable | Yes — fills gaps |
| Coordinates (lat/lng) | Yes — via geocoding after suggestion | Yes — fills missing coordinates |
| Phone | Yes — if findable in the dataset context | Yes |
| Website | Yes | Yes |
| Tags | Yes — suggests tags based on patterns | Yes — normalizes inconsistent values |
| Categories (Sets) | Yes — if a Map category is appropriate | Yes |
Custom fields (_hours, etc.) | Yes — if prioritize_missing_fields is on | Yes |
What the AI does not change:
- Coordinates that are already set are not overwritten. Manual coordinates you’ve entered are preserved through subsequent improvement passes.
- Fields with validation errors (e.g., an invalid website URL) are flagged and will block approval for that item until you fix them.
- The AI will not rename your location to an empty string — a location name is required for approval.
The review step
After generation, every suggested update appears as an improvement item in the review panel. Each item shows:
- Original values — what was in your workspace before the AI ran.
- Suggested values — the AI’s proposed changes for each field.
- Confidence badge —
high(3+ fields changed, no warnings),medium(some fields changed, possible gaps), orlow(validation errors present). - Warnings — which fields are still missing after the suggestion (e.g., “Phone number is still missing”).
- Validation errors — problems that block approval (e.g., “Location name is required”).
Reviewing an item
- Approve — mark the suggestion ready to apply. Approved items are collected and applied when you click Apply now or trigger the apply step.
- Reject — discard the suggestion for that location. The location record is not changed.
- Save edits — edit the suggested values in-form before approving. This lets you accept most of the suggestion but correct one or two fields.
- Apply now — immediately writes approved items to your location records (Row Improver mode).
Selective apply vs. apply all
You can approve items one at a time or in bulk. The Builder Improvements view also has an Approve all clean action that approves every item marked is_valid in a single step.
⚠️ Warning: Bulk-approving without inspecting low-confidence items can overwrite correct data with AI-inferred guesses. The Approve all clean button in the review panel and the Accept all button in Builder Improvements both skip the inspection step. At minimum, scan the low-confidence items before using either. The AI can confidently suggest plausible but wrong details — especially for phone numbers and websites on obscure or regional businesses.
Builder Improvements: structural recommendations
In addition to per-location field suggestions, the Builder Improvements pass produces 5–12 structural recommendations — workspace-level changes that affect groups of locations:
| Type | What it does |
|---|---|
| New tag | Creates a new tag and suggests applying it to locations that share a pattern |
| New category | Creates a new Set/category for the active Map |
| Merge | Consolidates tag spelling variants (e.g., “Drive-Thru / drive thru / drive-thru” → “Drive-Thru”) across all affected locations |
| Split | Flags a tag that covers two distinct groups and suggests splitting it into two |
Each card shows the type badge, how many locations are affected, a title, and a description of why the AI is recommending it.
Actions per card:
- Skip — ignore this recommendation without applying it.
- Accept / Create — accept the recommendation. It is queued for the finalize step.
- Skip all / Accept all — bulk-action all pending cards at once.
After you’ve handled all pending cards, the Done button finalizes the accepted recommendations. Finalization creates or merges tags and categories immediately — this cannot be undone via the panel.
⚠️ Warning: Merge recommendations rename and delete tag variants across all locations in the workspace. Review the “merge_variants” list on each merge card before accepting. If you’re not sure, skip the merge and do it manually from the Tags settings page.
💡 Tip: Split recommendations are marked “Review & split” rather than “Accept.” They require manual follow-up because the AI can’t reliably determine which locations belong in which group.
What happens to the original data
AI Location Improvement replaces field values on the location record when you apply a suggestion. The changes are atomic — each suggestion is applied in a database transaction.
There is no one-click rollback. Applied changes are recorded in the system audit log, which captures the mutation, but the panel does not expose a revert action. To undo an applied suggestion you’ll need to edit the location manually in the Locations tab.
🔴 [NEEDS CLARIFICATION: Confirm whether audit log entries expose the pre-change payload in the dashboard UI, or whether reverting always requires a manual field-by-field edit.]
When AI improvement works well
The AI performs best when:
- Locations have a name and at least partial address data — the more context, the more accurate the suggestions.
- Your workspace has multiple locations of the same type (chains, franchises, networks) — the AI uses cross-record patterns to infer correct values.
- You want to normalize inconsistent casing, formatting, or address abbreviations across a large set.
- You need to backfill hours or category data across records that share a business type.
When it struggles:
- Very sparse records — if locations have only a name and nothing else, the AI has little to work from and may return no suggestions or low-confidence ones.
- Obscure or one-of-a-kind locations — the AI’s training data is richer for national chains than for small regional businesses. Phone numbers and websites are most likely to be wrong for obscure locations.
- Non-English addresses — address normalization is less reliable for non-Latin character sets or regions with limited geocoding coverage.
- Large workspaces — the entire workspace dataset is sent as the prompt. Very large workspaces (hundreds of locations with full custom field data) can hit the 90-second timeout. Scope the run to a subset if this happens consistently.
See Troubleshooting → AI Location Improvement for the four known failure modes and their fixes.
Geocoding during improvement
When the AI suggests an address for a location that has no coordinates, the system attempts to geocode the suggested address before adding it to the review batch. The geocoder only assigns coordinates for high-precision matches (rooftop or range-interpolated) — partial or ambiguous matches are skipped intentionally to avoid placing pins at the wrong location.
If a suggestion has an address but no coordinates after the improvement run, you can enter the coordinates manually on the location edit form.
Cost and plan access
AI Location Improvement is a premium feature and requires at least a Premium plan. The Structural / Builder Improvements mode (workspace batch + tag/category recommendations) is labeled Premium AI in the panel.
The Row Improver (single-location mode) availability by plan is 🔴 [NEEDS CLARIFICATION: confirm whether Row Improver is restricted to Premium only or available on Bronze].
Each improvement run is one AI call regardless of how many locations are in scope. There is no per-location charge. Token usage for each run is logged internally but is not currently surfaced to users in the dashboard.
Rate limits and timeouts
- The AI call has a 90-second timeout. If your workspace is large and the request times out, the run fails with an error. Fix: use the location filter to scope the run to a smaller subset.
- There is no hard per-workspace daily limit on improvement runs, but each run queues as a background job. If another improvement job is already running for your workspace, the new run will queue behind it.
- If the AI provider is briefly unavailable, the run fails with a timeout or generation error. Waiting a minute and retrying usually resolves transient issues.
For full error descriptions and fixes, see Troubleshooting → AI Location Improvement.
Related pages
- Locations — managing location records manually
- AI Location Import — creating new locations with AI
- Troubleshooting → AI Location Improvement — timeout, empty results, inaccessible locations, wrong suggestions