Airtable Integration

Airtable Integration

Connect your Airtable base directly to Mapsemble and keep your map in sync automatically. When records change in Airtable, your map updates in real time.

Pending Marketplace approval. The Mapsemble Airtable Extension is pending approval on the Airtable Marketplace. You can still install it today using one of the two paths below.

What it does

The Mapsemble Airtable extension lives inside your Airtable base and syncs data to interactive maps via the Mapsemble API. It supports real-time updates through webhooks, cursor-based incremental sync, and automatic field mapping.

Prerequisites

• A Mapsemble account
• An Airtable base with location data (coordinates, addresses, WKT, or GeoJSON)
• The Mapsemble extension installed in your base (see Step 1 below)

Step 1: Install the extension

While the extension is pending Marketplace approval, there are two ways to install it today.

Option A — Remix from GitHub (self-serve)

Works for any Airtable plan. Installs the Mapsemble extension from our public GitHub repo.

1. Open your Airtable base.

2. Click the Extensions panel, then Add an extension → Build a custom extension → Remix from GitHub.

3. Paste the Mapsemble repo URL:

   https://github.com/mapsemble/airtable

4. Follow Airtable's prompts to install the Blocks CLI and run the extension.

See Airtable's own Remix from GitHub guide for the full walkthrough.

Option B — Shared base install (we install it for you)

If you're on a team plan and can share your base with us, we can install the extension directly into your instance. Request a shared-base install from the Airtable integration page — the contact form at the bottom of that page goes straight to us.

Option C — Airtable Marketplace (once approved)

Once our Marketplace listing is approved, you will also be able to search for Mapsemble in the Extensions marketplace and click Add extension. This section will be updated when that path is live.

Step 2: Connect your Mapsemble account

The extension offers two authentication methods:

One-click connection (recommended):

1. Click Connect with Mapsemble in the extension.
2. A popup window opens to the Mapsemble authorization page.
3. Log in and authorize the extension.
4. The extension automatically receives your credentials and exchanges them for an API token.

Manual credentials:

1. Click Enter credentials manually.
2. Enter your Client ID and Client Secret (available from your Mapsemble account settings).
3. The extension exchanges these for an API token.

The token is stored securely within Airtable's extension configuration and refreshes automatically on expiry.

Step 3: Configure location fields

Choose how your table stores location data:

Dual-field mode — Separate latitude and longitude columns:

• Select your Latitude field (numeric).
• Select your Longitude field (numeric).

Single-field mode — One column containing location data:

• Select the Location field.
• Choose the format: Auto-detect, GeoJSON, WKT, Coordinate pair (lat,lng), or Address.

When using Address format, Mapsemble geocodes the addresses server-side. No coordinates are needed in your table.

The extension auto-detects lat/lng fields when possible, based on column names and data types.

Step 4: Map your fields

Select which Airtable columns to include on your map and assign each a Mapsemble field type:

You can also choose an optional Label field that will be used as the display name for each marker on the map.

The extension fetches available field types from the Mapsemble API schema to ensure compatibility.

Step 5: Create the map

1. Enter a map name (label).
2. The extension generates a Mapsemble field schema from your selected fields, including:
   • A hidden _airtable_id field used as the primary key for syncing.
   • Select field options (choices) are automatically pulled from your Airtable column configuration.
3. Click Create map — the extension sends the schema to POST /api/v1/maps.

Step 6: Initial sync

Once the map is created, the extension syncs all records from the current Airtable view:

• Records are converted to GeoJSON features with your mapped fields as properties.
• ≤ 1,000 records: Full reconciliation via PUT /api/v1/maps/{mapId}/features. This upserts matching records by _airtable_id and deletes any that no longer exist.
• > 1,000 records: Batch upsert via POST /api/v1/maps/{mapId}/features in batches of 500.

The extension shows sync progress with phases: uploading records, reading existing data, and pruning deleted records.

Step 7: Set up auto-sync (optional)

For real-time updates, the extension can register an Airtable webhook:

1. Provide an Airtable Personal Access Token with these scopes:
   • data.records:read — to read changed records
   • webhook:manage — to register and manage webhooks
2. The extension validates the PAT has access to your base and table.
3. A webhook is registered that watches for record changes (created, updated, deleted) in your table.
4. When Airtable detects changes, it notifies Mapsemble, which triggers an incremental sync.

Webhook expiry: Airtable webhooks expire after 7 days. The extension can refresh them automatically, or you can refresh manually from the extension UI.

Without auto-sync, you can trigger manual syncs at any time from the extension's home screen.

Cursor-based sync

After the initial sync, Mapsemble uses cursor-based synchronization:

• Only changed records are fetched from Airtable on each sync.
• The sync cursor is maintained by Airtable's webhook system.
• This keeps API usage minimal and syncs fast, even for tables with thousands of rows.

Managing multiple maps

You can create multiple maps from the same Airtable table, each with different field mappings or views. The extension's home screen shows all maps linked to the current table with:

• Map name and link to Mapsemble
• Last sync timestamp
• Quick actions: sync, preview, delete

Location format reference

The extension supports these location formats in single-field mode:

Auto-detect analyzes sample values from your table to determine the format automatically.

Troubleshooting

Token expired: The extension automatically re-exchanges credentials on 401 errors. If this fails, disconnect and reconnect your Mapsemble account.

Map not found (404): If a map was deleted from Mapsemble, the extension detects this and lets you remove it from the configuration.

Feature limit reached: Your Mapsemble plan has a maximum number of features per map. The sync reports the current count vs. limit when this occurs.

Deleted Airtable fields: If a mapped field is deleted from your table, the extension warns you during sync. Deleted fields are skipped — reconfigure the field mapping to resolve.

Rate limits: Airtable enforces 5 API requests per second per base. Mapsemble handles this with automatic retries, but very large initial syncs may take longer.