Managing Locator Data in CMS

This guide explains how to add, edit, export, and import locator rows in the CMS at cms.mapviewer.eu or your custom CMS URL.

Overview

The locator database stores location data for the store locator. Each row represents a retail location or point of interest with geographic coordinates and business information.

Database Schema

Column	Type	Description
`id`	int8 (auto)	Primary key, auto-incremented
`google_place_id`	text	Google Places unique identifier
`google_resource_name`	text	Google resource identifier
`google_plus_code`	text	Google Plus Code (e.g., `8FVC2222+22`)
`store_id`	text	Your internal store identifier
`display_name`	text	Display name for the location
`business_status`	text	Current business status (OPERATIONAL, CLOSED, etc.)
`monday_hours` - `sunday_hours`	text	Opening hours for each day (format: `09:00-18:00`)
`phone`	text	Contact phone number
`website`	text	Store website URL
`address`	text	Full street address
`country_code`	text	ISO country code (NL, BE, DE, etc.)
`city`	text	City name
`zipcode`	text	Postal code
`user_properties`	text	Custom user-defined properties
`tags`	json	JSON array of tags (e.g., `["category 1", "category 2"]`)
`types`	json	JSON array of product categories (e.g., `["category 1", "category 2"]`)
`last_updated`	text	Timestamp of last update (ISO format)
`latitude`	float8	Geographic latitude (WGS84)
`longitude`	float8	Geographic longitude (WGS84)
`geom`	geometry(Point,4326)	PostGIS point geometry (auto-generated from lat/lng)

Accessing CMS

Navigate to https://cms.mapviewer.eu
Log in with your credentials
Select the Mapviewer project (if applicable)
Navigate to the locator collection

Adding New Locations

Method 1: Through CMS UI

Navigate to the collection
- Click on Collections in the sidebar
- Select locator collection
Create new entry
- Click the + Create button (top-right)
Fill in required fields

Core Information

Field	Required	Format	Example
`display_name`	Yes	Text	`Store name`
`latitude`	Yes	Decimal	`51.3`
`longitude`	Yes	Decimal	`4.2`

Recommended Fields

Field	Format	Example
`store_id`	Text	`id`
`address`	Text	`Kerkweg`
`city`	Text	`Maasland`
`zipcode`	Text	`3155 VL`
`country_code`	ISO 3166-1	`NL`
`phone`	E.164	`+31`
`website`	URL	`https://example.com`
`types`	JSON Array	`["category 1", "category 2"]`
`business_status`	Text	`OPERATIONAL`

Hours Fields

Enter hours in HH:MM-HH:MM format. Leave empty for closed days.

monday_hours:    "09:00-18:00"
tuesday_hours:   "09:00-18:00"
wednesday_hours: "09:00-18:00"
thursday_hours:  "09:00-20:00"
friday_hours:    "09:00-20:00"
saturday_hours:  "10:00-17:00"
sunday_hours:    "12:00-17:00"

Special Fields

types: JSON array of product categories. Use lowercase names matching your store product types:
```
["category 1", "category 2", "category 3"]
```
Tip: Multiple types can be selected. This determines which filter categories the location appears under in the locator app.
tags: JSON array for additional categorization:
```
["flagship", "display", "seasonal"]
```

Save the entry
- Click Save (top-right)
- The id and geom fields are auto-generated
- The last_updated field is auto-populated with the current timestamp

Method 2: Import from Google Places

If you have Google Places data:

Ensure you have the Google Place ID
Create a new entry and paste the google_place_id
CMS can auto-populate some fields from Google (if configured)
Manually verify and complete missing fields

Editing Existing Locations

Finding a Location

Navigate to locator collection
Use the search box to find by display_name, store_id, or address
Click on the entry to open the edit view

Updating Fields

Basic fields: Edit text directly in the form fields
Coordinates: Update latitude and longitude decimal values
- Use Google Maps or similar to find coordinates
- Format: 52.3667 (not 52,3667 - use period, not comma)
JSON fields (types, tags): Edit as JSON arrays
- Example: ["category 1", "category 2"]
- Validate JSON syntax before saving
Hours: Update each day separately in HH:MM-HH:MM format

Bulk Editing

For editing multiple locations at once:

Navigate to the locator collection
Use the checkboxes to select multiple entries
Click Actions > Batch Update
Select the field to update (e.g., business_status)
Enter the new value
Click Apply

Note: Batch update only allows updating one field at a time for all selected entries.

Exporting Data to CSV

Method 1: CMS CSV Export

Navigate to locator collection
Click the Export button (top-right, looks like a download icon)
Select CSV as the format
Choose which fields to include (recommended: select all)
Click Export
The CSV file will download automatically

Method 2: Filtered Export

Apply filters to the collection view (e.g., filter by country_code or types)
Click Export > CSV
Only the filtered results will be exported

CSV File Structure

The exported CSV will have columns matching the database schema. Important notes:

JSON fields (types, tags, user_properties) will be exported as JSON strings
Geometry field (geom) may appear as WKT format (e.g., POINT(4.8945 52.3667))
Empty fields will be empty strings in CSV

Importing Data from CSV

Before Importing

⚠️ Important Preparation Steps:

Download a template: Export a CSV first to see the exact column names
Match column headers: Ensure your CSV headers exactly match CMS field names (case-sensitive)
Validate JSON fields: For types and tags, use valid JSON array syntax:
- Correct: ["category 1", "category 2"]
- Incorrect: category 1, category 2 (comma-separated won't work)
Check coordinates: Ensure latitude and longitude are valid decimals
Remove auto-generated fields: Do NOT include id, geom, or last_updated in your import CSV

Method 1: CMS CSV Import

Navigate to locator collection
Click Import button (top-right)
Select CSV as the format
Upload your CSV file
Map fields: CMS will attempt to auto-map columns to fields
- Verify each column maps to the correct CMS field
- Unmapped columns will be ignored
Select import mode:
- Insert: Add new rows only
- Update: Update existing rows (requires matching key)
- Upsert: Insert new or update existing
Click Import

Method 2: Import via API (Advanced)

For large datasets or automated imports:

curl -X POST \
  https://cms.mapviewer.eu/api/items/locator/import \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/locator_data.csv' \
  -F 'fields=display_name,latitude,longitude,address,city,types'

Tips and Best Practices

Data Quality

Always verify coordinates: Use a service like LatLong.net or Google Maps to verify lat/lng
Standardize address format: Use consistent format for all addresses
Validate JSON arrays: Use a JSON validator for types and tags fields
Country codes: Use ISO 3166-1 alpha-2 codes (NL, BE, DE, FR, etc.)

Workflow Recommendations

Small updates: Edit directly in CMS UI
Multiple updates (1-50): Use batch update in CMS
Large updates (50+): Export → Edit CSV → Reimport
Regular syncs: Set up automated API imports for external data sources

Common Issues

Issue	Solution
CSV import fails	Check CSV encoding (use UTF-8), verify column names
JSON fields rejected	Ensure valid JSON syntax: `["value1", "value2"]`
Coordinates not working	Use period as decimal separator, not comma
Geom field empty	Will be auto-generated from lat/lng
Duplicate entries	Add `store_id` as unique identifier

Required Fields

For a location to appear correctly in the locator app, at minimum provide:

display_name
latitude
longitude
types (at least one product type)

CMS Collection Configuration

If you have admin access, you can customize the CMS collection:

Field Display Settings

Navigate to Settings > Data Model > locator
Click on a field to edit its display settings
Recommended configurations:

Field	Display Type	Settings
`display_name`	Input	Required: Yes
`latitude`, `longitude`	Number	Precision: 8, Required: Yes
`types`, `tags`	JSON	Interface: List (Multi-Select)
`business_status`	Dropdown	Choices: OPERATIONAL, CLOSED, TEMPORARILY_CLOSED
`address`	Textarea	Rows: 3
`monday_hours` - `sunday_hours`	Input	Placeholder: `09:00-18:00`

Creating a Custom Interface

For better usability, create a custom interface:

Go to Settings > Interfaces
Create new interface for locator
Group related fields:
- Location Info: display_name, store_id, address, city, zipcode, country_code
- Contact: phone, website, email
- Coordinates: latitude, longitude
- Hours: All day_hours fields
- Products: types, tags
- Google: google_place_id, google_resource_name, google_plus_code

Example CSV Template

store_id,display_name,address,city,zipcode,country_code,phone,website,latitude,longitude,types,tags,business_status,monday_hours
STORE-001,Main Store,Main Street 1,Amsterdam,1012 JS,NL,+31201234567,https://example.com/amsterdam,52.3667,4.8945,["category 1","category 2"],["flagship"],OPERATIONAL,09:00-18:00
STORE-002,Second Location,Side Street 45,Rotterdam,3011 AL,NL,+31109876543,,51.9225,4.4792,["category 1","category 2","category 3"],["outdoor"],OPERATIONAL,10:00-19:00

API Access (for Developers)

Authentication

Get your access token from Settings > Access Tokens in CMS.

List All Locations

curl -X GET \
  'https://cms.mapviewer.eu/api/items/locator?limit=-1' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Create a Location

curl -X POST \
  https://cms.mapviewer.eu/api/items/locator \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "display_name": "Store Utrecht",
    "latitude": 52.0907,
    "longitude": 5.1214,
    "address": "Main Street 123, 3511 AL Utrecht",
    "city": "Utrecht",
    "country_code": "NL",
    "types": ["category 1", "category 2"]
  }'

Update a Location

curl -X PATCH \
  https://cms.mapviewer.eu/api/items/locator/123 \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "business_status": "CLOSED",
    "monday_hours": "10:00-17:00"
  }'

Support

For issues with:

CMS access: Contact your Geofacta administrator
Data not appearing in locator: Verify coordinates and types fields are populated
Import errors: Check CSV format and field mappings

Overview​

Database Schema​

Accessing CMS​

Adding New Locations​

Method 1: Through CMS UI​

Core Information​

Recommended Fields​

Hours Fields​

Special Fields​

Method 2: Import from Google Places​

Editing Existing Locations​

Finding a Location​

Updating Fields​

Bulk Editing​

Exporting Data to CSV​

Method 1: CMS CSV Export​

Method 2: Filtered Export​

CSV File Structure​

Importing Data from CSV​

Before Importing​

Method 1: CMS CSV Import​

Method 2: Import via API (Advanced)​

Tips and Best Practices​

Data Quality​

Workflow Recommendations​

Common Issues​

Required Fields​

CMS Collection Configuration​

Field Display Settings​

Creating a Custom Interface​

Example CSV Template​

API Access (for Developers)​

Authentication​

List All Locations​

Create a Location​

Update a Location​

Support​