AI Location Import

AI Location Import turns raw, unstructured source material — a CSV, a spreadsheet, a list of URLs, pasted text, or even a blank slate — into a set of reviewable location drafts. You describe what you have, the AI extracts structured records, and you approve (or edit) each one before anything is saved to your workspace.

When to use AI Import vs. plain CSV Import

How to start an AI Import

AI Import lives inside the AI Hub panel, which is attached to the Finder Builder — not the standalone Locations list.

1. Open a finder in the Builder.
2. Click the AI Hub button in the builder toolbar (labeled “AI Launch Finder” or similar). The panel opens and lands on the Source screen.
3. Choose your source type from the cards at the top of the panel:
   • Upload a CSV — select a .csv file; the content is read client-side and sent to the AI
   • Upload spreadsheet — .csv, .xlsx, .xls, or .tsv
   • Connect Google Sheet — paste a sheet URL
   • Paste website URLs — one URL per line; AI crawls the pages and extracts location records
   • Paste raw text list — copied lists, email content, or semi-structured rows
   • Use existing finder data — use the current workspace dataset as the launch source; good for cleanup and structured re-import
   • Demo data — generates realistic sample records so the finder is populated immediately
4. Fill in the context fields:
   • Brand or network name — e.g., “Cobblestone Coffee” (optional)
   • Business type — e.g., “coffee shops”, “urgent care clinics”, “auto dealerships” (required)
   • Geographic scope — e.g., “Ohio”, “United States”, “Northeast Europe” (required)
   • Expected location count — approximate number helps the AI aim for the right batch size
5. Depending on the source type, paste your content or upload your file.
6. Click Launch Finder with AI. The job is queued and you’ll see a live progress log — you can close the panel and come back later; the job keeps running in the background.

🟡 [SCREENSHOT: AI Hub panel on the Source screen, showing source type cards and context fields with a CSV file attached]

What the AI can extract

For each location, the AI attempts to populate:

⚠️ Warning: The AI fills fields from the source material you provide. If exact details are not in the source, it leaves the field blank rather than fabricating values. Always review the drafts before importing.

After the AI draft is generated, addresses without coordinates are enriched using Google Maps geocoding. If a precise street-level geocode cannot be confirmed, coordinates are left blank and flagged as a warning.

Input limits

For file-based sources (CSV, spreadsheet), the client reads the file and truncates it to the first 12,000 characters before sending. For raw text and URL sources, the assembled source field has a 4,000-character server-side limit. If your file or text is larger than these limits, consider splitting it into multiple AI Import runs or using the plain CSV import for large datasets.

When AI Import works well

• Clean-ish CSVs and spreadsheets with consistent columns — the AI re-structures the rows into the location schema even if column names don’t match exactly
• Copy-pasted content from web pages — address blocks, contact listings, or location directories
• Semi-structured plain text — lists like “Store Name — 123 Main St, City, ST” convert reliably
• Demo or seed data — the demo data source type generates realistic placeholder records that make a new finder immediately usable
• Existing workspace data — useful when you want to re-import with better structure, apply tags at scale, or do a cleanup pass on existing locations

When AI Import struggles

• Scanned PDFs or image-based files — the AI only receives plain text; image content cannot be extracted
• Highly abbreviated or coded data — internal shortcodes, legacy IDs, or heavily abbreviated fields produce low-confidence drafts
• Very large files — only the first 12,000 characters of file content are included; later rows will be missing
• Unique or niche address formats — non-US addresses, P.O. boxes, and rural routes are parsed with lower accuracy
• Locations with no address or region data — validation requires at least one address-context field (street, city, state, zip, or country) to be present

💡 Tip: For large or complex datasets, run AI Import in smaller batches (50–100 rows at a time) for more accurate results and faster review.

Reviewing the AI’s drafts

After the generation job completes, the panel moves to the Extract screen with a preview summary, then to the Review screen.

The Review screen

The Review screen shows every draft location with a status, a confidence indicator, and any warnings:

• High confidence — all core fields are present and validated
• Medium confidence — some fields are missing but at least one address context is available
• Low confidence — required fields are missing or validation errors are present; the item cannot be imported until it is fixed

Each item is classified as either ready (valid, no duplicate conflict) or an exception (has warnings, duplicates, or validation errors). The UI surfaces exceptions first so you can focus your attention.

Actions per item:

• Approve — marks the item for import
• Reject — removes the item from the import batch without deleting it from the draft
• Edit — update any field (name, address, city, state, zip, country, phone, website, tags, custom fields, or coordinates); save the edit and then approve

Bulk actions:

• Approve all clean records — approves every item that is valid and has no duplicate conflict in a single click
• Import approved — starts the apply job for all currently approved items

Resolving duplicates

If the AI extracted multiple records that look like the same location, they appear together in the Resolve duplicates view. Select the record you want to keep; the others are automatically rejected.

🟡 [SCREENSHOT: Review screen showing a mix of high/medium/low confidence rows with per-row approve and reject controls]

🟡 [SCREENSHOT: Duplicate resolution view showing two candidate records side by side with a “Keep this one” action]

Accepting and importing

Once you are happy with your approvals:

1. Click Import approved on the Review screen.
2. A short background job runs to write the approved records as real Locations in your workspace.
3. When it finishes, the panel moves to the Launched screen with a summary: locations imported, failed, tags created.
4. Newly created locations are immediately available on the Locations list and in any finder that uses your workspace.

If you click Import approved without approving anything individually, all valid pending items are auto-approved in the same action — you do not need to approve each row manually to get a quick bulk import.

💡 Tip: After importing, consider running Builder Improvements from the Launched screen. The AI will scan your new locations and suggest tags, categories, and grouped cleanup that make the finder easier to use. See AI Location Improvement for details.

🟡 [SCREENSHOT: Launched screen showing import summary — “12 locations imported, 2 tags created”]

Monitoring progress with the Jobs tray

Both the generation job and the apply job are tracked as background processes. You can watch them in the Jobs tray (bottom of the app shell):

• Queued → Running → Waiting for review (generation job) or Completed (apply job)
• If a job fails, a red indicator appears with an error message; click Retry to try again
• You can close the AI Hub panel while the generation job is running — the draft will be waiting in the panel when you reopen it

Cost and plan availability

AI Import is available on all plans — there is no per-plan gating on the feature.

🔴 [NEEDS CLARIFICATION: Is AI Import usage metered or rate-limited per workspace or per plan tier? No per-plan limits were found in the codebase; routes sit under standard auth middleware with no subscription_tier guard. Confirm with product whether any soft limits exist.]

The AI processing is handled by an AI provider on the backend. There is no additional charge to you for using this feature beyond your normal plan subscription.

Discarding a draft

If you decide not to proceed with a batch, click Discard in the Review screen footer. The batch is marked discarded and removed from the AI Hub panel. Discarding does not affect any Locations that were already imported from a previous run of the same batch.

Related pages

• Locations — managing your location records after import
• AI Location Improvement — use AI to clean up and enrich locations already in your workspace
• Add Locations — the getting-started guide, including plain CSV import