Loading...

Data Sync - Getting started

The following guide shows how to setup map data so that it can be synced with with Mappedin CMS.

Overview

For partners with an existing central CMS, a data sync can be set up to treat that as the single source of truth. The Mappedin CMS will still be required to make any structural changes to the maps, using our powerful Map Editor, and to manage location types not present in your system (typically: amenities). All other location, category, and event data can come from your CMS. To do that, your CMS needs to provide an API that meets our requirements.

API

To synchronize with your system, Mappedin requires access to a REST API returning JSON data. Mappedin will run the sync once a day typically. In the future, syncing a venue in response to a webhook may be available.

Images

Mappedin can sync Images from your system in a number of places (Store logos being the primary example). In order to use an image, the sync platform needs a programmatic way to know if the image has changed. Ideally this would be the name of the image (different name is interpreted as a different image), but we can also use, in order of preference: a last changed date property, a hash of the image stored in your API along side it, or an eTag on the image resource itself.

Please ensure that images conform to the MIME type of image and it's subtypes jpeg, png or svg+xml

For best results, please supply an SVG or 512px resolution PNG/JPGs, with a minimal amount of padding and no larger than 15MBs.

Data

The Mappedin system has four types of object that can be synced: Venues, Locations, Categories and Events. Mappedin products (like Mappedin Dynamic Directory and Mappedin Web) require certain properties on these objects to be populated in order to function correctly. Some other properties are optional, but can enhance the user experience. Others still can just be stored, either for potential use in a future version of a product, or to be available in the SDKs for a custom app you build.

Descriptions for the what the object types are and what fields can be synced are as follows:

Venue

A Venue is defined as a whole property (like a Mall, or a Hospital) that has Locations inside of it. This is an optional object and not required for a data sync to be setup.

It should have the following properties:

PropertyDescriptionTypeImportance
nameName of the venue to be displayedstringRequired
externalIdUnique identifier of the venuestringRequired
addressStreet address of the venuestringOptional
cityCity namestringOptional
stateState or provincestringOptional
postalPostal code or zip codestringOptional
telephonePhone numberstringOptional
websiteURL to venue's websitestringOptional
operationHoursVenue opening hours in OpeningHoursSpecification format (including holiday information)objectOptional
Click to view sample of an ideal JSON
[
{
"name": "Mappedin Demo Mall",
"externalId": "mappedin-demo-mall",
"address": "460 Phillip St #300",
"city": "Waterloo",
"state": "Ontario",
"postal": "N2L 5J2",
"telephone": "519-594-0102",
"website": "http://www.mappedin.com",
"operationHours": [
{
"@type": "OpeningHoursSpecification",
"opens": "10:00",
"closes": "23:00",
"dayOfWeek": ["Sunday"]
},
{
"@type": "OpeningHoursSpecification",
"opens": "09:00",
"closes": "22:00",
"dayOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
]
},
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": ["Saturday"],
"validFrom": "2018-06-30",
"validThrough": "2018-06-30",
"opens": "00:00",
"closes": "00:00"
}
]
}
]

Location

A Location is an individual place of interest (like a store, restaurant, tenant, or amenity) in a Venue. A location can be tied to multiple physical locations. For example, all the restrooms might be modeled as a single location. Multiple Starbucks might be modeled as one location or several. An Anchor may span multiple floors. Locations should have the following properties:

Required:

  • A unique alpha-numeric ID that will not change on subsequent syncs (Tenant ID)
  • A unit ID or equivalent that links to a space in the mall
  • Name
  • Location Hierarchy (if applicable) - If multiple locations are to be attached to the same physical space (Sears and Sears Optical, for example), a way to determine which is the main one (Sears)

Highly Recommended:

  • Description
  • Logo image
  • Categories

Optional:

  • Parent location if this location is the child of another location (tenant ID of the parent location)
  • Type (ie, Store vs Restaurant)
  • State (if the location is closed temporarily, new or coming soon)
  • Hours (especially if different from Mall hours), in OpeningHoursSpecification
  • Search keywords (tags)
  • Phone Number
  • URLs to social media accounts (Twitter, Facebook, Instagram)
  • A Website URL for a tenant's own website, or a Details URL that links to information on the current site Contact name and email
  • URL friendly name (must be unique per venue, for use in the URL when deep linking in to Mappedin Web)
PropertyDescriptionTypeImportance
nameName of the location to be displayedstringRequired
externalIdUnique identifier of the locationstringRequired
polygonsUnit ID of the polygon to attach the location toArray<string>Required
descriptionDescription of the locationstringOptional
languageIf there are other languages than the defaultstringOptional
telephonePhone numberstringOptional
operationHoursOpening hours for the location for each day as well as special hoursArray<object>Optional
detailsUrlWebpage link for the locationstringOptional
logoKeyURL for location logostringOptional
categoriesCategory IDs of the locationArray<string>Optional
socialSocial media linksobjectOptional
tagsList of search tags for the locationArray<string>Optional
parentThe externalId of the parent locationstringOptional
statesStatus of location, coming-soon, new, closed-temporarily or pop-upArray<object>Optional
picturesKeyLinks to pictures of the locationArray<string>Optional

Note: We've often found that Amenities (washrooms, ATMs, etc) are not managed in our partner's internal CMS. In that case Amenities are managed entirely within the Mappedin CMS. If you do have complete amenity information in your system, we can sync it like another type of Location. Amenities require a name, amenity type, icon, and a reference to any places they exist on the map.

Click to view sample of an ideal JSON
[
{
"name": "Example Store",
"externalId": "tenant_id_1",
"parent": "parent_tenant_id",
"description": "The best place to buy your favourite things - Guaranteed.",
"detailsUrl": "http://www.example.com/StoreDetails",
"categories": ["category_id_1", "category_id_2"],
"polygons": ["space_id_matching_CAD_1"],
"logo": "http://www.example.com/Example-Store-Logo-filename-that-changes-if-the-file-changes.jpg",
"phone": "(555) 555-5555",
"social": {
"facebook": "https://www.facebook.com/ExampleStore",
"twitter": "https://twitter.com/ExampleStore",
"instagram": "https://instagram.com/ExampleStore",
"website": "https://www.examplestore.com"
},
"tags": "clothes, things, brand name, shoes",
"states": [
{
"type": "coming-soon",
"start": "2019-01-01",
"end": "2025-01-01"
}
],
"operationHours": [
{
"@type": "OpeningHoursSpecification",
"opens": "10:00",
"closes": "23:00",
"dayOfWeek": ["Sunday"]
},
{
"@type": "OpeningHoursSpecification",
"opens": "09:00",
"closes": "22:00",
"dayOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
]
},
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": ["Saturday"],
"validFrom": "2018-06-30",
"validThrough": "2018-06-30",
"opens": "00:00",
"closes": "00:00"
}
]
}
]

Categories

A Location can belong to one or more Categories, and Categories can have a parent/child hierarchy.

Highly Recommended:

  • Picture (Full colour image for Dynamic Directory)
  • Logo (Pictograph for use in Mappedin Web)
PropertyDescriptionTypeImportance
nameName of the category to be displayedstringRequired
externalIdUnique, durable identifier for the category which is used for the locationsstringRequired
languageIf there are other languages than the defaultstringOptional
iconKeyURL to logostringOptional
pictureKeyURL to picturestringOptional
parentsList of parent categoriesArray<string>Optional
descriptionDescription of the categorystringOptional
Click to view sample of an ideal JSON
[
{
"name": "Clothing",
"externalId": "category_id_1",
},
{
"name": "Fashion",
"externalId": "category_id_2",
"language": "en",
"iconKey": "http://www.example.com/Fashion-filename-that-changes-if-the-file-changes.jpg",
"parents": ["category_id_1"]
}
]

Events

An Event is a thing that happens for a period of time, either once or with some recurrence. It can optionally be associated with a location, or just present at the Venue in general. This is an optional object and not required for a data sync to be setup.

Required:

  • Name
  • Durable ID
  • Start date
  • End date

Highly Recommended:

  • Image
  • Show date (if you want to show it before it's live)

Optional:

  • Location ID, corresponding to a Tenant ID that matches an existing Location

For recurring events, if the rules are more complicated than "weekly at the same time", we require an iCalendar string. See rrule or similar for help generating these.

PropertyDescriptionTypeImportance
nameName of the event / promotionstringRequired
externalIdUnqiue identifer for the eventstringRequired
typeType of event such as event or promotionstringRequired
startDateUnix timestamp of event start datenumberRequired
endDateUnix timestamp of event end datenumberRequired
showDateUnix timestamp of when to start displaying the eventnumberOptional
locationLocation the event is taking place; using the externalId of the locationstringOptional
descriptionDescription of the eventstringOptional
imageKeyURL to image of event or promotionstringOptional
Click to view sample of an ideal JSON
[
{
"name": "Event",
"externalId": "vN7m3kH9rU1Mxxz",
"location": "NqtdVzVkfrCkDtODwnWb",
"type": "event",
"startDate": "1577854816800",
"endDate": "1609347616800",
"showDate": "1577854816800",
"description": "Sample of an event",
"imageKey": "http://www.example.com/Example-event-image-filename-that-changes-if-the-file-changes.jpg"
},
{
"name": "Promotion",
"externalId": "QZd6cuI7raKDFiD",
"type": "promotion",
"startDate": "1577854816800",
"endDate": "1609347616800"
}
]

Overlay

Mappedin's DD+ also supports the option for Ad Overlays. In order to sync Ad Overlays, there are two main differences from other events. The event type needs to be set as ad or ad overlay, in order to differentiate it from other event types, and a url to an image is required.

PropertyDescriptionTypeImportance
nameName of the adstringRequired
typeSet as 'ad' or 'ad overlay'stringRequired
startDateUnix timestamp of event start datenumberRequired
endDateUnix timestamp of event end datenumberRequired
imageKeyURL to image of Ad OverlaystringRequired
Click to view sample of an ad overlay
{
"name": "Ad Overaly",
"type": "ad",
"startDate": 1643691600000,
"endDate": 1651377600000,
"imageKey": "https://www.example.com/"
}

X_ properties

Venue, Location, Category and Event can all have extra, optional properties not part of the standard Mappedin data model. These are referred to as x_ properties, because they are all prefixed with x_ when they are accessed from the object. If you are building an application with our SDKs and need access to certain properties present in your CMS, they can potentially be added via x_ properties. Work with your Mappedin Developer Relations contact to determine if this is appropriate, and what the data might look like.

Was this page helpful?