Source: https://developers.woosmap.com/products/stores-api/guides/importing-store-data/

> For clean Markdown of any page, append `.md` to the page URL.

> Routing index (which page answers which question): https://developers.woosmap.com/llms.txt

> Full page list: https://developers.woosmap.com/llms-full.txt

# Importing Store Data



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](/products/stores-api/features/data-management/) is the API reference for every
operation mentioned here. The sample scripts live in
[Woosmap/woosmap-samples](https://github.com/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](#upload-from-the-console)                                 |
| A CSV, Excel workbook or Google Sheet        | [stores-import](#import-from-a-spreadsheet)                                |
| A nightly refresh from an internal system    | [stores-sync](#keep-a-project-in-sync)                                     |
| A backup, or a handover to QGIS or a BI tool | [stores-export](#export-a-project)                                         |
| Your own pipeline                            | [Data Management](/products/stores-api/features/data-management/) directly |

## Upload From the Console

The [Woosmap Console](https://console.woosmap.com/) 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`](https://github.com/Woosmap/woosmap-samples/tree/master/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.

```sh
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`](https://github.com/Woosmap/woosmap-samples/tree/master/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`](https://github.com/Woosmap/woosmap-samples/tree/master/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](/products/stores-api/concepts/query-syntax/) 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](/products/stores-api/features/data-management/#authentication).

## Related

- [Data Management](/products/stores-api/features/data-management/), the full endpoint reference
- [Data Structure](/products/stores-api/features/data-management/#data-structure), the fields an asset accepts
- [Opening Hours](/products/stores-api/concepts/opening-hours/)
- [Choosing Your Stores API Integration](/products/stores-api/guides/integration-path/)