Google Sheets sync
Connect a Google Sheet so the map refreshes itself when the sheet changes. Mapji only ever reads the sheet.
On this page
Connect a Google Sheet and the map keeps itself up to date: edit the sheet, and the map follows within minutes. Mapji only ever reads the sheet — it asks Google for read-only access and never changes your spreadsheet.
Sheets sync works on Cluster, Heatmap, Choropleth, Store Locator and Time Slider maps.
Connect a sheet
Open Google Sheets
Select Import in the editor toolbar, then Google Sheets.
Grant access the first time
If Mapji doesn't have read access to your sheets yet, select Grant Google Sheets access (or Connect Google & grant Sheets access if you signed in with GitHub or Microsoft) and approve read-only access in Google's window. See Accounts and sign-in.
Paste the sheet's address
Paste the URL of the sheet into Google Sheets URL and select Connect. The first row must hold the column headers. Private sheets work, as long as the Google account you connected can open them. If the file has several tabs, choose one.
Map the columns
Choose which columns hold the map's data. Mapji suggests the latitude and longitude columns from their names.
Connect and sync
Select Connect & Sync. The first sync runs straight away, and the map shows the sheet's data.
Columns by map type
| Map type | Required | Optional |
|---|---|---|
| Cluster, Store Locator | Latitude, Longitude | Title, Description |
| Heatmap | Latitude, Longitude | Title, Description, Weight |
| Time Slider | Latitude, Longitude, Time | Title, Description |
| Choropleth | Region code | Value |
Include all columns as feature properties is on by default, so every other column comes through too, for popups, filters and styling.
For a Choropleth map, set up the regions in the editor first. The Region code column must contain each region's code exactly as shown under its name in the Selected areas tab; the sheet then updates the values of those regions, and never adds or removes regions. See Choropleth.
How syncing works
- Mapji checks the sheet about every five minutes, and updates the map only when something changed. In practice a change appears within five to ten minutes.
- When the sheet has changed, the sync rebuilds the map's data from it. The first 10,000 valid rows are used, and the chip says when the limit was reached (Choropleth maps have no row limit).
- Rows without valid coordinates are skipped and counted. Coordinates must be numbers, such as
38.7223; a number cell is fine whatever your sheet's number format, but text such as38,7223or38°43'Nmakes the row invalid. - The map's settings — colors, gradients, the store locator's layout — are kept across syncs.
The sheet is the source of truth. On a Store Locator, adding, editing and deleting locations in Mapji is switched off while a sheet is connected. On the other map types, data you change in the editor — a point you delete, a region value you type — is replaced by the sheet's the next time the sheet changes.
The status chip
Once a sheet is connected, a chip in the editor toolbar shows when the sheet was last checked and how many features came from it.
| Dot | Meaning |
|---|---|
| Green | The last check succeeded |
| Amber | A sync is running (pulsing), the sync worked with a warning — skipped rows, the row limit, unrecognized region codes — or automatic sync is paused |
| Red | The last check failed, with the reason, such as a column that was renamed or removed |
Sync now checks the sheet immediately. Disconnect Google Sheets stops syncing; the data already on the map stays.
Auto-sync paused
If Google stops letting Mapji read the sheet — access was revoked, the connection expired, or the sheet is no longer shared with that account — the chip turns red with the reason, and automatic syncing pauses (the chip later reads Auto-sync paused). Fix the access, then select Sync now. Automatic syncing comes back on after a sync that finds a change in the sheet, or when you connect the sheet again.
A column was renamed
Mapji finds columns by their header names. If you rename or delete the latitude, longitude or time column (the region code or value column on a Choropleth map), the sync fails and the chip shows which column is missing. A renamed title, description or weight column doesn't fail the sync — its values just stop coming through. Rename the column back, or disconnect and connect the sheet again to map the new name.