Google Sheets Sync Guide

Google Sheets sync lets you connect a public spreadsheet to Mapiry, preview changes, and keep map locations updated over time.

Availability

Current product position:

• public Google Sheets sync is a free feature for logged-in users
• private Google Sheets auth is not available yet
• private-sheet sync is planned for a future paid feature set

What It Does

Google Sheets sync can:

• create new locations from new rows
• update existing linked locations
• hide linked locations that disappear from the sheet
• geocode rows that do not include coordinates
• run manually or on a daily schedule

One-Way or Two-Way?

Google Sheets sync is one-way only.

That means:

• Mapiry reads from Google Sheets
• Mapiry writes changes into Mapiry locations
• Mapiry does not write changes back into Google Sheets

Can You Still Edit Locations in Mapiry?

Yes. Users can still edit locations inside Mapiry even when external sync is enabled.

But there is an important rule:

• if a field is present in the synced sheet and Mapiry treats it as source-managed, the next sync can overwrite manual edits in Mapiry for that field
• if a field is not present in the sheet, manual edits in Mapiry stay as they are

Today, source-managed behavior is driven by the sheet columns and field mapping:

• name, coordinates, and the selected row key are sync-managed
• optional fields like description, category, tags, hidden, image_url, and order are only updated when those columns are present or mapped

So practical guidance is:

• keep operational data in the sheet
• keep Mapiry-only storytelling polish in fields that are not synced from the sheet

When to Use It

Use Google Sheets sync when:

• your team already manages locations in Google Sheets
• the data changes regularly
• you want repeatable updates instead of one-off CSV imports
• you have a stable unique ID column

Use CSV import instead when:

• you only need a one-time import
• you want to upload a local file quickly
• your source is not a live sheet

Before You Start

Your Google Sheet must be public or published so Mapiry can fetch it as CSV.

At the moment, private Google Sheets are not supported for sync.

Recommended setup:

• one header row
• one location per row
• one unique row-key column
• stable identifiers such as store_id, branch_code, or location_slug

Supported Fields

By default, Mapiry recognizes:

• name
• lat or latitude
• lng or longitude
• description
• category
• tags
• hidden
• image_url or imageurl
• order
• id

You also choose one row-key column in sync settings.

If your sheet uses different header names, you can map custom columns in the sync settings UI.

Set Up Sync

Step 1: Open the Map

Go to your map detail page and find Google Sheets Sync.

Step 2: Paste the Sheet URL

Use a normal Google Sheets URL such as:

https://docs.google.com/spreadsheets/d/...

Step 3: Choose a Row Key

Pick a column whose value is:

• unique per row
• stable over time
• not just a display label

Step 4: Optional Field Mapping

If your headers differ from Mapiry defaults, map them manually.

Example:

• Name Column -> store_name
• Latitude Column -> y_coord
• Longitude Column -> x_coord

Step 5: Preview Sync

Use Preview Sync to see:

• how many rows would create locations
• how many would update existing linked locations
• how many existing linked locations would be hidden
• how many rows need geocoding
• validation errors

Step 6: Save Settings

Save the connection once the preview looks correct.

Step 7: Run Sync

Click Sync Now to apply the changes.

Manual vs Daily

Manual

Use manual mode when you want full control over when updates apply.

Daily

Use daily mode when you want regular background checks.

Daily sync behavior:

• a map is eligible only if it has not been checked in the last 24 hours
• Mapiry fetches the sheet and computes a content hash
• if the sheet content is unchanged since the previous sync, Mapiry skips apply work
• if the content changed, Mapiry runs the normal sync

Geocoding

If lat and lng are missing:

• new rows may be geocoded during sync
• geocoding uses Mapiry AI credits
• existing linked rows may keep their old coordinates if geocoding fails

If you want the most predictable results, include explicit coordinates in the sheet.

Example Sheet

store_id,name,lat,lng,description,category,tags,hidden
melb-cbd-01,Central Cafe,-37.8136,144.9631,Open daily,Cafe,breakfast;wifi,false
melb-cbd-02,City Bookshop,-37.8150,144.9662,Independent bookstore,Retail,books;local,false

Common Questions

Will sync create duplicates?

It should not if your row key is stable and unique. If the row key changes, Mapiry treats it like a new record.

Will sync delete locations?

No hard delete in this version. Missing linked rows are hidden, not deleted.

Can Mapiry changes override Google Sheets?

No. This is not two-way sync. Changes made in Mapiry stay in Mapiry only, unless later overwritten by the next one-way sync from the sheet.

Related Guides

• CSV Import Guide
• KML Import Guide