The shape of a clean location file
One location per row, column headings in the first row, and nothing else on the sheet. Totals rows, notes, merged heading cells and blank spacer rows all become rows the import has to reject. A retailer or dealer with five branches is five rows, each with its own address, because a visitor searches for the branch near them.
You do not need to rename your headings to match the locator. Handled proposes a match for common spellings, such as Store name, Postcode or Zip, and lets you correct each one before anything is written. The location sheet checklist has a template with every column named the way the importer expects.
| Column | Required | Example | Watch for |
|---|---|---|---|
| Name | Every row | North Loop | Blank names from a column called something else in the source system |
| Address | Unless coordinates are given | 120 N 1st St, Minneapolis, MN 55401 | One full column, or separate street, city, region and postcode columns |
| Country | When the list spans countries | US | A lookup without a country can land in the wrong one |
| Latitude, longitude | Optional | 44.9852, -93.2700 | Swapped pairs, text, degree symbols |
| Phone, email, website | Optional | 612-555-0142 | Head office details copied onto every row |
| Categories | Optional | Pickup, Service | One spelling per tag; these become filters |
| Location type | Optional | online | Storefront, service area or online; blank means storefront |
| Stable ID | Only for a later sync | MN-014 | Never the row number |
Save it so nothing is lost on the way
Save as CSV with UTF-8 encoding. Most spreadsheet apps offer it by name, such as CSV UTF-8 in Excel or the CSV download in Google Sheets. A file saved in an older encoding turns accented names into garbled characters, so Café becomes something unreadable on the card, and that is hard to fix afterwards.
Addresses contain commas, so any address cell must be wrapped in quotes in the CSV. Spreadsheet exports do this for you; hand-edited text files often do not. Handled's importer also reads semicolon-, tab- and pipe-separated files, since spreadsheets in some regions export with semicolons. It takes CSV rather than Excel files, so export from Excel before uploading.
Common data errors and how to spot them
These are the faults that recur in real location exports. Almost none of them make an import fail outright. They import cleanly and then show up weeks later as a pin in the wrong place or a store nobody can find, which is why they are worth ten minutes before the upload.
| Error | How it shows up | How to spot it in the sheet |
|---|---|---|
| Head office address on every branch | A stack of pins on one building | Sort by address and look for repeats with different names |
| ZIP codes lost their leading zero | 01234 arrives as 1234 and the lookup lands elsewhere | Filter postcodes by length; US ZIPs should be five digits |
| Latitude and longitude swapped | A shop in the sea or on another continent | In the contiguous US latitude is positive and longitude negative; check the signs |
| Coordinates of 0, 0 | A pin off the coast of West Africa in tools that accept it; Handled rejects the pair | Filter for zero; it usually means a missing value exported as a number |
| Same store twice from merged exports | The count is wrong while the map looks right | Sort by name, then address, and compare neighbours |
| One row per product | Several pins on one store, each with one product | Repeated store names with a product column; see below |
| Tag spelled several ways | Two filters for one thing | Make a list of unique values in the categories column |
| Unit or suite numbers in odd places | Pins on the right street but the wrong building | Spot-check the pins of your busiest locations after import |
| PO boxes or mailing addresses | A pin at a post office | Search the address column for PO Box |
A ten-minute check before uploading
Run these in the spreadsheet, top to bottom. Or run the file through the free CSV location validator first, which checks the structural problems in your browser without uploading the file.
- Delete totals, notes, blank rows and merged heading rows so only locations remain.
- Filter the name column for blanks and fill or remove those rows.
- Filter for rows with neither an address nor coordinates. Nothing can place them on a map.
- Sort by address and look for one address repeated under different names.
- Make a unique list of your category values and fix every near-duplicate spelling.
- If you have coordinates, sort each column and check the smallest and largest values fall where your locations are.
- Format the postcode and phone columns as text so leading zeros survive the save.
- Save as CSV UTF-8 and reopen the file once to confirm it still looks right.
Tags that become filters
The categories column carries products, services, dealer tiers or amenities as a comma-separated list, and each distinct value becomes a filter visitors can use. Agree the exact names once. Coffee and Coffee products are two filters, and a visitor who picks one never sees the stores tagged with the other.
In Handled, create the categories before the first import. The import matches values in the file to categories that already exist and shows unknown values for review rather than quietly adding to the filter list. Tags should describe what your team maintains, such as which lines a store carries, not live stock.
Distributor and broker reports list a store once per product. You do not need to pivot them first: the importer folds lines that repeat the same store into one location and merges their products into its tags, and the review says how many lines it folded. The distributor reports guide walks through one.
Reading the import review
After column mapping, every row gets a status with its reason, and a problem in one row never blocks the rest. Rows with errors or duplicates start unticked so they are not imported by accident. The file you upload is also checked against your plan's location limit before anything is written.
After import, the Locations table marks each pin as Placed, Approximate or Placed by hand. Approximate means the lookup resolved the address to a street, postcode or town rather than an exact building; it is the short list to check on the map. Three optional settings tidy data on the way in without changing your file: reformatting US and Canadian phone numbers to one pattern, converting all-caps or all-lowercase names and addresses to title case, and restoring the leading zeros spreadsheets strip from US ZIP codes, which is on by default.
| Status | Meaning | What to do |
|---|---|---|
| Ready | Has a name and usable coordinates | Nothing |
| Needs an address lookup | Has an address but no coordinates | Nothing; it is geocoded during import |
| Repeated earlier in this file | Same name and address as an earlier row | Usually leave it out; fix the source file |
| Already in your locations | Matches a location you already have | Leave it out, or edit the existing location |
| No name | The name cell is blank | Fill it in the file and re-import that row |
| No address and no coordinates | Nothing to place on the map | Add an address, or mark it as online |
| Latitude or longitude not valid | A coordinate is text or out of range | Correct it, or clear both and let the address be looked up |
What a CSV does not carry
A location import carries the standard fields, tags and, for dealer networks, territory postcodes. Custom fields, such as a booking link shown as a button, are set per location in the dashboard, through the Location API, or through the Claude and ChatGPT connector, so leave those columns unmapped rather than expecting them to appear.
After the import: keep the file honest
Search a town near several locations, apply each filter, and open a result on a phone: address, phone link, website link and directions. Then decide where the list lives from now on. For occasional batch updates, keep the reviewed file as the source of truth and re-import changes; rows already in your locations are flagged rather than doubled. When several people update the list week to week, move it to a synced Google Sheet with a stable ID column.
Either way, you can export your locations back out as CSV at any time, and the export re-imports without remapping.
Frequently asked questions
What columns does a store locator CSV need?
At minimum a name and either a full street address or latitude and longitude on every row. Useful extras are country, phone, email, website, description, a categories column for filters, and a stable ID if the list will later be synced from a spreadsheet.
Why did my store locations import in the wrong place?
Usually the file, not the geocoder: a missing country, a ZIP code that lost its leading zero, latitude and longitude swapped, or head office's address pasted onto branch rows. Check the pins marked approximate first, then compare their addresses with the source.
How do I stop duplicate locations when importing?
Remove repeats from merged exports before uploading by sorting on name and address. On import, Handled flags rows that repeat earlier in the file or match a location you already have, and leaves them unticked so they are not added twice.
Can I import an Excel file directly?
Save it as CSV UTF-8 first. The Handled importer reads CSV, including semicolon-, tab- and pipe-separated files, rather than Excel workbooks.
Should I include latitude and longitude in the CSV?
Only if you trust them. Rows with valid coordinates skip the address lookup and are marked as placed by hand. Coordinates from an old system are worth spot-checking, because a swapped pair imports without error and puts the pin in the wrong hemisphere.