Logo
FeaturesAI GeneratorExploreCollectionsDocs
Back to Documentation

CSV Import Guide

Import location data from CSV files into Mapiry with this complete guide covering format requirements, best practices, Google Sheets import, and troubleshooting

Last updated: January 17, 2026

CSV Import Guide

Mapiry also supports importing from a public Google Sheet by pasting the sheet URL into the same import dialog. Internally, Mapiry fetches the sheet as CSV and runs the exact same preview and import flow described below.

If you want a saved sheet connection with repeatable updates, read the Google Sheets Sync Guide.

Got a spreadsheet full of locations? CSV import lets you quickly add multiple locations to your map instead of adding them one by one.

What is CSV Import?

CSV (Comma-Separated Values) is a simple file format used by Excel, Google Sheets, and most database programs. It stores data in rows and columns.

When to use CSV import:

  • You have 10+ locations in a spreadsheet
  • You're migrating from another platform
  • You receive location data from partners
  • You maintain a database of locations

Use Google Sheets sync instead when you want a one-way linked spreadsheet workflow with preview, row-key matching, and repeatable sync runs.

Supported Fields

Required Fields

Your CSV must include the name column. Coordinates are optional — if omitted, Mapiry will automatically geocode the location using its name:

  • name - Location name (required)
  • lat or latitude - Decimal latitude coordinate (optional — geocoded automatically if absent)
  • lng or longitude - Decimal longitude coordinate (optional — geocoded automatically if absent)

Optional Fields

You can also include:

  • description - Text describing the location
  • category - Category name (will create new category if doesn't exist)
  • tags - Semicolon-separated tags, for example family;outdoor
  • hidden - "true" or "false" to hide location from public view
  • image_url or imageurl - Image URL to attach
  • order - Numeric sort order
  • id - Existing Mapiry location ID for update mode

Google Sheets sync supports the same fields by default, plus one extra required concept: a unique row key column that you choose in sync settings. If your sheet uses different header names, the sync settings let you map custom columns to these fields.

CSV Format Requirements

Basic Structure

Your CSV should look like this:

name,lat,lng,description,category,hidden
Coffee Haven,40.7580,-73.9855,Best coffee in NYC,Restaurant,false
Central Park,40.7829,-73.9654,Famous urban park,Attraction,false
Brooklyn Bridge,40.7061,-73.9969,Iconic bridge,Landmark,false

Important Notes

Coordinate Format:

  • Use decimal degrees only
  • ✅ Correct: 40.7580, -73.9855
  • ❌ Wrong: 40°45'29"N (degrees/minutes/seconds)
  • ❌ Wrong: 40.7580N (letters)

Valid ranges:

  • Latitude: -90 to 90
  • Longitude: -180 to 180

Text with Commas: If your text contains commas, wrap it in quotes:

name,description
Joe's Pizza,"Authentic, wood-fired pizza since 1975"

Multi-line Descriptions: Use quotes for descriptions with line breaks:

name,description
Museum,"Home to 5,000 works.
Open Tuesday-Sunday."

Column Names:

  • Case-insensitive: "Name", "name", and "NAME" all work
  • Alternative names accepted:
    • latitude or lat
    • longitude or lng

Categories:

  • Each location can only have ONE category
  • If category doesn't exist, it will be created automatically
  • Category names are matched case-insensitively

UTF-8 Encoding: For international characters (é, ñ, 中文), save as UTF-8:

  • Excel: File > Save As > "CSV UTF-8 (Comma delimited)"
  • Google Sheets: File > Download > CSV (UTF-8 automatic)

Preparing Your Data

Step 1: Create Spreadsheet

Open Excel or Google Sheets and create these columns:

namelatlngdescriptioncategory
Location 140.7580-73.9855Great spotRestaurant
Location 240.7829-73.9654Nice parkAttraction

Step 2: Validate Coordinates

Test a few coordinates:

  1. Copy a lat/lng pair
  2. Paste into Google Maps: 40.7580, -73.9855
  3. Verify it shows the correct location

Step 3: Clean Your Data

Before importing:

  • Remove duplicates (Excel: Data > Remove Duplicates)
  • Ensure all required fields are filled
  • Remove extra spaces before/after text
  • Verify coordinates are in valid range

Step 4: Save as CSV

From Excel:

  1. File > Save As
  2. Choose "CSV UTF-8 (Comma delimited)"
  3. Click Save

From Google Sheets:

  1. File > Share > publish/share sheet publicly if needed
  2. Either paste the sheet URL directly into Mapiry's Google Sheets import mode, or download "Comma-separated values (.csv)"

Importing Your CSV

Step 1: Open Import Dialog

  1. Open your map in Mapiry
  2. Look for Import button (usually in the map editor)
  3. Choose either CSV File or Google Sheets
  4. Upload your CSV or paste your Google Sheets URL

Step 2: Review Preview

  • Mapiry shows the first 10 rows as a preview
  • Check that columns are detected correctly:
    • Name column recognized
    • Lat/lng columns recognized
    • Description and category (if present)

Step 3: Handle Categories

If your CSV includes a category column:

  • Existing categories will be matched automatically (case-insensitive)
  • New categories will be created with default colors
  • Categories show "New" badge in preview if they'll be created

Step 4: Import

  1. Click "Import Locations"
  2. Wait for import to complete
  3. Review the result summary:
    • ✅ Successfully imported count
    • ⚠️ Any errors or skipped rows

What Happens During Import

Locations:

  • Each valid row creates one location on your map
  • Locations are created in batches for performance

Categories:

  • New categories are created automatically
  • Existing categories are matched by name (case-insensitive)
  • Categories get default colors from a preset palette

Errors:

  • Invalid coordinates (out of range or not numbers) are skipped
  • Rows missing required fields (name) are skipped
  • Import log shows which rows had errors

Automatic Geocoding:

  • Rows without lat/lng are geocoded automatically at import time using the location name
  • Geocoding costs 2 credits per location (deducted from your plan's credit balance)
  • If you don't have enough credits for the full batch, Mapiry geocodes as many rows as your budget allows (top-to-bottom CSV order) and marks the rest as failed
  • Rows Mapiry cannot resolve (ambiguous names, no Google result) count as failed — they are not silently dropped
  • The preview shows a "Will be geocoded" indicator and an estimated credit cost before you confirm import
  • Geocoding is only available for create mode imports (not update mode)

Common Issues & Solutions

"Invalid coordinates" error

Problem: Latitude/longitude outside valid ranges or not numbers

Solutions:

  • Ensure lat is between -90 and 90
  • Ensure lng is between -180 and 180
  • Use decimal degrees, not degrees/minutes/seconds
  • Remove any letters (N, S, E, W)
  • Check for typos

"Missing required field" error

Problem: Required field (name, lat, or lng) is empty

Solutions:

  • Check CSV for blank cells in required columns
  • Use Excel's "Find & Select > Go To Special > Blanks" to find empty cells
  • Fill in missing data or delete incomplete rows

Locations appear in wrong places

Problem: Coordinates are swapped or incorrect

Solutions:

  • Verify lat column maps to "Latitude" (not longitude!)
  • Remember: latitude is smaller range (-90 to 90)
  • Longitude is larger range (-180 to 180)
  • Test first lat/lng pair in Google Maps

Descriptions have weird characters

Problem: Encoding issue (é becomes é)

Solutions:

  • Re-save CSV as UTF-8 in Excel/Sheets
  • Use "CSV UTF-8" option, not plain "CSV"
  • Test with one row containing special characters first

Categories not created

Problem: Category column not recognized or has issues

Solutions:

  • Check spelling and capitalization
  • Ensure column is named "category"
  • Check that category names aren't empty

Some locations missing after import

Problem: Fewer locations imported than expected

Solutions:

  • Check import result message for error count
  • Verify all required fields are present
  • Check that coordinates are valid
  • Look for duplicate location names

Example CSV Files

Minimal Example

name,lat,lng
Empire State Building,40.748817,-73.985428
Statue of Liberty,40.689247,-74.044502
Times Square,40.758896,-73.985130

Complete Example

name,lat,lng,description,category,hidden
Central Cafe,40.7580,-73.9855,"Cozy cafe serving breakfast and lunch",Restaurant,false
Tech Hub,40.7489,-73.9680,"Co-working space for startups",Office,false
City Museum,40.7794,-73.9632,"Modern art and history museum",Museum,false
Secret Spot,40.7531,-73.9712,"Hidden gem only for special guests",Restaurant,true

With Categories

name,lat,lng,category
Starbucks,40.7580,-73.9855,Coffee Shop
Public Library,40.7531,-73.9712,Education
Hotel Grand,40.7589,-73.9851,Hotel

Best Practices

1. Start Small

Test with 5-10 locations first:

  1. Create a small test CSV
  2. Import and verify it works
  3. Then import your full dataset

2. Use Descriptive Names

Instead of "Location 1", use "Downtown Office" or "Main Street Cafe"

3. Include Descriptions

Descriptions make your map more useful:

  • Explain what each location is
  • Include hours, tips, or special notes
  • Keep them concise (2-3 sentences)

4. Plan Categories

Before importing:

  • Decide on 5-8 main categories
  • Use consistent naming
  • Consider organizing by type, region, or purpose

5. Backup Large Maps

If adding to an existing map with many locations:

  • Clone your map first as a backup
  • Import to the clone
  • Verify it looks good before updating your main map

6. Verify After Import

After importing:

  1. Zoom out to see all locations
  2. Check for outliers (markers in wrong countries)
  3. Click several random locations to verify data
  4. Check that categories were created correctly

Limitations

What CSV import does NOT support:

  • ❌ No file size limits specified - but very large files may timeout
  • ❌ No duplicate detection - duplicates will be imported
  • ❌ No update mode - can only create new locations, not update existing
  • ❌ No image uploads - images must be added manually after import
  • ❌ No custom fields - only the 6 supported fields work
  • ❌ No multiple categories per location - one category only
  • ❌ No automatic backups - clone your map first if needed
  • ❌ No undo - once imported, must delete locations manually

Getting Coordinates

If you have addresses but no coordinates, Mapiry can geocode them automatically:

Option 1: Let Mapiry Geocode (Recommended)

  • Simply omit the lat and lng columns from your CSV
  • Mapiry geocodes each row at import time using the location name
  • Costs 2 credits per location (shown as an estimate in the preview)
  • Works best when names include enough context (e.g., "Eiffel Tower, Paris" rather than just "Tower")
  • For large datasets or when credits are limited, consider external tools below

Option 2: Use Google Maps

  1. Search for the address in Google Maps
  2. Right-click the location
  3. Click the coordinates to copy them
  4. Paste into your spreadsheet

Option 3: Batch Geocoding Services Use online tools to convert addresses to coordinates:

  • GPS Visualizer
  • Geocodio
  • Batch Geocoder

Then add the coordinates to your CSV.

Migrating from Other Platforms

From Google My Maps

Google My Maps uses KML format:

  1. Export from Google My Maps as KML
  2. Use our KML Import instead
  3. Or convert KML to CSV using online tools

From Google Sheets

  1. File > Download > CSV
  2. Import directly to Mapiry
  3. Or use Google Sheets Sync if you want an ongoing connection instead of a one-time import

From Excel

  1. File > Save As
  2. Format: CSV UTF-8 (Comma delimited)
  3. Import to Mapiry

What's Next?

Related Articles

Bulk Operations

Import and export multiple locations using CSV or KML files

KML Import Guide

Import maps from Google Earth and Google My Maps using KML/KMZ files, with support for folders, descriptions, and styling