Data Models
This section documents the internal data structures used by pitchmappr. These are primarily relevant for developers building integrations, for understanding JSON export structure, or for advanced users who want to manually edit project JSON files.
Location Object
Each location on the map is stored as an object with these properties:
| Property | Type | Description |
|---|---|---|
id | number | Auto-incremented unique identifier assigned when the location is created. Used internally for tracking and reference. Never exposed in the UI or in map labels. |
name | string | Display name from geocoding (e.g. "New York", "London"). This is the primary identifier shown in the location list and used as the default map label when no custom label is set. |
label | string | Optional custom label override. When set, this text is displayed on the map instead of the geocoded name. Useful for abbreviations, custom descriptions, or internal identifiers (e.g. "NYC HQ", "Target A"). The original geocoded name is always preserved. |
lat | number | Latitude coordinate from geocoding. Determines the marker's north-south position on the map. Stored as a decimal degree value (e.g. 40.7128 for New York). |
lon | number | Longitude coordinate from geocoding. Determines the marker's east-west position on the map. Stored as a decimal degree value (e.g. -74.0060 for New York). |
type | string | Location type: 'standard' or 'hq' (headquarters). Derived, never set directly — a location is 'hq' when its dataset is named HQ / Headquarters. HQ locations render with their own dataset's shape and colour, like any other markers — a new HQ dataset simply defaults to a red star. A project can have as many HQ locations as that dataset holds. |
datasetId | string | Reference to the parent dataset's ID. Determines which dataset the marker belongs to, which in turn controls the marker's color, shape, and visibility group. Removing a dataset asks whether to delete its locations or move them to a dataset you choose — nothing is reassigned silently. |
Rows waiting to be placed. Locations you've pasted or imported but not yet geocoded are held separately from the list above until you press Geocode locations. A waiting row keeps its address, label, dataset, and source — and its latitude/longitude too, if the imported file supplied them. Waiting rows survive saving and reopening the project, and they never appear on the map until you place them.
Dataset Object
Each dataset is a group of locations that share styling and visibility settings:
| Property | Type | Default | Description |
|---|---|---|---|
id | string | auto-generated | Unique identifier used internally for dataset references and for linking locations to their dataset. Never shown to users. |
name | string | 'Default' | User-facing display name shown in the sidebar, the dataset selector dropdown, and export metadata. Renameable. New maps seed exactly one dataset named Default — the first dataset is where unassigned rows land, and its Size & Halo seed every new dataset. |
color | string | theme-based | Hex color code for the dataset's markers. Selected from the active color scheme palette or entered manually as a hex value. A new HQ-named dataset defaults to red (#E63946). |
shape | string | 'circle' | Marker shape for all locations in this dataset. Options: circle (filled circle), square (upright square with rounded corners), star (5-pointed star). A new HQ-named dataset defaults to star. |
visible | boolean | true | Master visibility toggle. When false, all markers in this dataset are hidden on the map, in the live display, and in exports. A per-view dataset visibility override can turn the dataset back on for one specific view. |
labelShow | boolean | true | Label visibility toggle. When false, markers appear without text labels. Useful for datasets with many closely-spaced locations where labels would overlap heavily. |
halo | number | 1.5 | The dataset's white halo (0–5, in 0.5 steps) — one value that drives both the white ring around its markers (ring width = halo × 2/3) and the white glow behind its label text. 0 turns both off. Always white. Replaces the old labelBg white/none background: older projects migrate on load ('none' → the value that preserves the marker ring; 'white' → the derived default). |
markerScale | number | 1.0 | The dataset's marker size multiplier (0.2–2.0). Always concrete — new datasets copy the Default dataset's current value at creation. While settings.lockStyles is on (the default for new maps), every dataset's effective Size & Halo follow the first dataset live; each dataset's own stored values are untouched and return when Lock is turned off. |
Saved View Object
Each saved view captures a specific map position and crop configuration:
| Property | Type | Description |
|---|---|---|
id | number | Auto-incremented unique identifier. |
name | string | User-given name (e.g. "US Overview") or auto-generated ("View 1"). Appears in the saved views list. Export filenames are built from the Project ID or Project Name, not the view name. |
center | [lat, lng] | Map center coordinates at the time the view was saved. Used to restore the exact viewport position when navigating to the view. Stored as [latitude, longitude] — the reverse of MapLibre's own [lng, lat] order, which pitchmappr converts at the MapLibre call boundary. |
zoom | number | Map zoom level at the time of save. Combined with center, fully defines the viewport. |
cropRatioId | string | Crop ratio identifier (e.g. '16x9', '4x3'). Determines the export dimensions and the crop overlay frame shape. |
mapMode | string | The map mode when the view was saved: 'regular' or 'focus'. The mode is used when exporting to ensure the correct rendering pipeline is used. |
overrides | object | Per-view settings overrides, primarily dataset visibility. Allows different views to show different subsets of data from the same project, enabling multiple export variants without changing global settings. |