Logo
FeaturesAI GeneratorExploreDocs
Back to Documentation

CSV Import Guide

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

Last updated: January 17, 2026

CSV Import 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

Supported Fields

Required Fields

Your CSV must include these three columns:

  • name - Location name (required)
  • lat or latitude - Decimal latitude coordinate (required)
  • lng or longitude - Decimal longitude coordinate (required)

Optional Fields

You can also include:

  • description - Text describing the location
  • category - Category name (will create new category if doesn't exist)
  • hidden - "true" or "false" to hide location from public view

That's it! Only 6 fields are supported. The CSV import does not support addresses, phone numbers, website URLs, images, or other 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 > Download
  2. Select "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. Select your CSV file

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, lat, lng) are skipped
  • Import log shows which rows had errors

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 geocoding (converting addresses to coordinates) - you must provide lat/lng
  • ❌ 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:

Option 1: 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 2: 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

From Excel

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

What's Next?

Related Articles

Adding & Managing Locations

Master the art of adding, editing, organizing, and managing locations on your Mapiry maps

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