Importing Store Data

Load stores into a Woosmap project from a CSV, an Excel workbook, a Google Sheet or a JSON file, and keep them in sync with your source of truth.

Your stores already live somewhere else, usually a spreadsheet or an internal system. This page covers getting them into a Woosmap project and keeping them current.

The Data Management endpoint is the API reference for every operation mentioned here. The sample scripts live in Woosmap/woosmap-samples, with Python and Node.js examples.

Choose Your Route

Your situation Use
A single load, data already in Woosmap JSON Console upload
A CSV, Excel workbook or Google Sheet stores-import
A nightly refresh from an internal system stores-sync
A backup, or a handover to QGIS or a BI tool stores-export
Your own pipeline Data Management directly

Upload From the Console

The Woosmap Console takes a native Woosmap JSON file through the Upload JSON button on your project. There is no code to write and no private key to handle, so it suits a first load or a small dataset. Use a script once the import has to run again, or when you need to see which rows failed.

Import From a Spreadsheet

stores-import reads a CSV, an .xlsx workbook or a shared Google Sheet, converts each row to an asset and loads the result with one atomic POST /stores/replace. The previous dataset stays online until the new one is accepted, so a rejected batch leaves the project untouched.

Give every store a stable Store ID before you load anything you intend to update later. An id derived from the store name changes when the name does. The next sync then reads that as one deletion plus one creation.

Clone the repo and run it from the stores-import directory. Every script reads your private key from the WOOSMAP_PRIVATE_KEY environment variable.

Shell
        pip install -r python/requirements.txt
python python/import_stores.py ../data/foodmarkets.csv --dry-run --output stores.json
python python/import_stores.py ../data/foodmarkets.xlsx --sheet foodmarkets

Node equivalents live alongside, under node/.

One row per store. Name, Latitude and Longitude are required; address, contact and Type columns are picked up when present, and --column FIELD=HEADER remaps any header that differs. Run --dry-run first: it validates every row and prints what would be sent without touching the project.

A Google Sheet needs to be shared with “anyone with the link”; pass the browser URL and the script downloads the CSV export. There is no OAuth flow to set up.

Keep a Project in Sync

A full replace re-sends every store, which gets expensive as a nightly job over thousands of them. stores-sync compares a Woosmap JSON file against what the project currently holds and sends only the differences, as POST, PUT and DELETE.

Feed it the output of stores-import --dry-run --output stores.json, or an export. Its --dry-run prints the diff. Read that before you let a scheduled job delete anything. --no-delete keeps stores that have fallen out of the source file.

Export a Project

stores-export dumps every store as Woosmap JSON, which imports back as is, or as GeoJSON for QGIS and BI tools. --query takes the query syntax of the Stores API to export a subset.

Batches and Limits

Write operations are atomic per request: if one asset fails validation, nothing in that batch is written. Request bodies are capped at 15MB, so large datasets have to be chunked. The sample scripts do this for you and refuses an oversized request locally, before it reaches the API.

Write operations need a private key and belong on your server. See Authentication.

‹ Tuning Your Search Results Query Syntax ›
Was this helpful?