Common Data Objects

Data

The Mappedin system has four types of objects that can be synced that are common across all verticals: 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:

Property	Description	Type	Importance
name	Name of the venue to be displayed	string	Required
externalId	Unique identifier of the venue	string	Required
address	Street address of the venue	string	Optional
city	City name	string	Optional
state	State or province	string	Optional
postal	Postal code or zip code	string	Optional
telephone	Phone number	string	Optional
website	URL to venue's website	string	Optional
operationHours	Venue opening hours in OpeningHoursSpecification format (including holiday information)	object	Optional
propertyImage	URL of an image of the property	string	Optional

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)
• URL for a header image

Property	Description	Type	Importance
name	Name of the location to be displayed	string	Required
externalId	Unique identifier of the location	string	Required
polygons	Unit ID of the polygon to attach the location to	Array<string>	Required
description	Description of the location	string	Optional
language	If there are other languages than the default	string	Optional
telephone	Phone number	string	Optional
operationHours	Opening hours for the location for each day as well as special hours	Array<object>	Optional
links	Webpage links for the location. Each link requires a URL and has an optional label	Array<object>	Optional
logoKey	URL for location logo	string	Optional
categories	Category IDs of the location	Array<string>	Optional
social	Social media links	object	Optional
tags	List of search tags for the location	Array<string>	Optional
parent	The externalId of the parent location	string	Optional
states	Status of location, coming-soon, new, closed-temporarily or pop-up	Array<object>	Optional
gallery	Links to pictures of the location. Each item requires an image URL. Caption and embedded URL are optional	Array<object>	Optional
headerImage	URL for a header image. Displayed at the top of the profile card on Mappedin Web.	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"
      }
    ],
    "headerImage": "http://www.example.com/Example-Header-Image-filename-that-changes-if-the-file-changes.jpg",
  }
]

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)

Property	Description	Type	Importance
name	Name of the category to be displayed	string	Required
externalId	Unique, durable identifier for the category which is used for the locations	string	Required
language	If there are other languages than the default	string	Optional
iconKey	URL to logo	string	Optional
pictureKey	URL to picture	string	Optional
parents	An array containing a single externalId of the parent category	Array<string>	Optional

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.

Property	Description	Type	Importance
name	Name of the event / promotion	string	Required
externalId	Unqiue identifer for the event	string	Required
type	Type of event such as event or promotion	string	Required
startDate	Unix timestamp of event start date	number	Required
endDate	Unix timestamp of event end date	number	Required
showDate	Unix timestamp of when to start displaying the event	number	Optional
location	Location the event is taking place; using the externalId of the location	string	Optional
description	Description of the event	string	Optional
imageKey	URL to image of event or promotion	string	Optional

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 Digital Directory 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 an url to an image is required. Learn more about event types.

Property	Description	Type	Importance
name	Name of the ad	string	Required
type	Set as 'ad' or 'ad overlay'	string	Required
startDate	Unix timestamp of event start date	number	Required
endDate	Unix timestamp of event end date	number	Required
imageKey	URL to image of Ad Overlay	string	Required

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.