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: 'location' (standard marker) or 'hq' (headquarters). HQ locations can render as stars and use a special HQ color. Only one location per project can be set to 'hq'. |
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. If the parent dataset is deleted, this is automatically reassigned to the first remaining dataset. |
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 | 'Dataset_N' | User-facing display name shown in the sidebar, the dataset selector dropdown, and export metadata. Can be renamed by the user. |
color | string | theme-based | Hex color code for all non-HQ markers in this dataset. Selected from the active color scheme palette or entered manually as a hex value. |
shape | string | 'circle' | Marker shape for all locations in this dataset. Options: circle (filled circle), square (rotated 45-degree diamond), star (5-pointed star). |
hqColor | string | '#D97706' | Hex color for the HQ marker. Applied globally across all datasets — every dataset's HQ location uses the same color. |
visible | boolean | true | Master visibility toggle. When false, all markers in this dataset are hidden on the map and in the live display. Note that hidden datasets are still included in exports unless overridden by per-view dataset visibility settings. |
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. |
labelBg | string | 'white' | Label background style: 'white' adds a white rectangular background behind label text for maximum readability, 'none' renders text directly on the map with only the halo for contrast. |
markerScale | number/null | null | Per-dataset size override multiplier (0.5–2.0). When null, uses the global settings.markerScale default. When set, this dataset's markers are scaled independently from the global setting. |
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 and is used as part of the export filename. |
center | [lng, lat] | Map center coordinates at the time the view was saved. Used to restore the exact viewport position when navigating to the view. Stored as [longitude, latitude] in the MapLibre convention. |
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'. SVG export is only available for focus mode views. 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. |