Getting Data into Meridian

The Meridian Editor can import Pages, Placemarks, and Events from XML, RSS, and JSON feeds. Events can also be imported from iCal Feeds.

RSS and iCal Feeds

The properties of each item in RSS and iCal feeds are associated with their corresponding Meridian Entities properties. For example, an RSS feed would be associated as follows:

<link> -> entity.url
<title> -> entity.name
<summary> -> entity.description

If you're importing an RSS feed, the valid RSS elements are:

  • title
  • link
  • description
  • author
  • category
  • comments
  • enclosure
  • guid
  • pubDate
  • source

For RSS and iCal properties that don't map predictably, you can manually select the feed properties to map to the entity properties.

Example iCal mapping

In RSS feeds, the only supported list property is tags which maps to categories.

XML and JSON Feeds

Importing XML and JSON entities requires a custom parser, in either CoffeeScript or JavaScript, to receive each item from a feed and return a structure that Meridian can import.

If the original feed format was in JSON, then the custom parser receives the raw JSON for each item in the variable item.

If the original feed format was in XML, then the custom parser receives an instance of XMLQuery, a lightweight XML parser class, in the variable item.

This CoffeeScript parser translates an RSS feed into Meridian events:

new_item = {}
new_item['uid'] = item.childNamed('guid').val()
new_item['name'] = item.childNamed('title').val()
new_item['dtstart'] = item.childNamed('pubDate').val()
new_item['url'] = item.childNamed('link').val()
return new_item

This Javascript parser translates a JSON feed into Meridian events:

new_item = {}
new_item['uid'] = item['guid']
new_item['name'] = item['title']
new_item['dtstart'] = item['pubDate']
new_item['description'] = item['description']
return new_item

Importing Placemark Feeds

Importing placemark details to the Editor with a feed can speed up the placemark customization for your location. However, before a placemark can be imported it must first be placed on a map in the Editor.

For a placemark feed to be valid, the placemark needs to have a UID. UIDs need to be added to the placemark manually.

You can add a UID to a placemark on the placemark details ... sidebar menu.

Placemark JSON Feed Example

{
  "items":[
  {
    "name": "My Placemark",
    "uid": "1234567890",
    "description": "An example of a JSON placemark",
    "type": "cafe",
    "custom_1": "booth"
  }
 ]
}

Meridian Feeds

The Meridian Editor can import an XML or JSON feed, without a custom parser, if the feed follows this structure:

<?xml version="1.0" encoding="UTF-8" ?>
<feed>
    <items>
        <item>
            <uid></uid>
        </item>
    </items>
</feed>

Each item is a single entity (Event, Page, or Placemark) in Meridian and is associated based on the value of the UID property.

Category names in feeds are limited to 100 characters.

Properties of an item

Pages Only. The domain of another Meridian-powered app.

categories

Set of categories. Not included in search indexes.

custom_1

Custom valued used by lists to filter entities.

custom_2

Custom valued used by lists to filter entities.

custom_3

Custom valued used by lists to filter entities.

custom_4

Custom valued used by lists to filter entities.

description

Text or basic HTML describing the entity. The supported HTML tags are:

<p>, <ul>, <li>, <a>, <b>, <u>, <i>, <br>

Since this HTML is in an XML feed, CData tags are required:

<![CDATA[<b>Meridian</b> will import this as HTML<]]>

dtstart

Events Only. The start time of an event in ISO 8601. If you plan on using a custom parser, you'll want to use the extended version of ISO 8601.

dtend

Events Only. The end time of an event in ISO 8601. If you plan on using a custom parser, you'll want to use the extended version of ISO 8601.

email

Email address of the entity

hint

Placemarks Only. A placemark hint is used to disambiguate multiple placemarks of the same name.

image_url

URL of an image that will be imported for the entity. Images are imported hourly.

After a feed imports, it takes at least an hour before the image will appear in your Meridian-powered app.

keywords

List of keywords. Used by search to users find entites.

layout

Pages Only. Defines how the image_url image will be shown on the page. The possible values are:

  • page_layout_1 - the image is shown inline with text wrapping around the image.
  • page_layout_2 - the image is shown at the full width of the divice.

Placemarks Only. A list of references to external websites or to internal Meridian Pages or Events. The following example shows a link to a Page with an ID of 123, a link to an Event with an ID of 456, and a link to Google's homepage. The title property is optional. If there is no title property, internal links use their linked entity's name and external links use the link value.

<links>
  <link>
    <link>pages/123</link>
    <title>My Page</title>
  </link>
  <link>
    <link>events/456</link>
    <title>My Event</title>
  </link>
  <link>
    <link>http://google.com/</link>
    <title>Search</title>
  </link>
</links>

locale

The locale tag is required if translations are supplied for a given item. The locale code attribute should be an ISO 639 language ("es"), but can also include an ISO 3166 country ("zh-CH") if a feed contains multiple locales for a single language (Traditional and Simplified Chinese). The following properties support translation and can, therefore, be included under a locale property:

categories, custom_1, custom_2, custom_3, custom_4, description, keywords, and name

mode

Pages of type 'webpage' only. Determines how the given url is loaded. The possible values are:

  • browser - a typical web page
  • hosted - a Sandbox web view in the Meridian-powered app.

name

The name of the entity

placemarks

Pages and Events Only. Placemarks can be associated either by their name or their UID. Associating a placemark by name always uses the default translation of the placemark name. The following example would attempt to associate two placemarks; the first by its name and the second by its UID.

<placemarks>
    <placemark>
        <name>Room 101</name>
    </placemark>
    <placemark>
        <uid>placemark101</uid>
    </placemark>
</placemarks>

Although placemarks is a list property, Events only support a single placemark. If a feed includes more than one placemark, the Event will use the first in the list.

phone

The phone number of the entity

requires_login

Pages of type 'webpage' only. Determines whether a user must be logged in to view the web page. Possible values are true or false.

type

The type of a page or placemark. Events do not have types.

Page types:

  • default
  • event_list*
  • list*
  • poster*
  • slideshow*
  • tabs*
  • twitter*
  • webpage

  • While you can import these types, their properties are not fully supported.

Placemark types:

  • aed
  • amusement_park
  • atm
  • attraction
  • bar
  • bus
  • cafe
  • cafeteria
  • changing_station
  • club
  • coat_check
  • conference_room
  • customer_service
  • elevator
  • emergency_dept
  • escalator
  • exit
  • first_aid
  • fitness_center
  • fountain
  • gallery
  • gaming
  • gate
  • generic
  • handicap
  • information
  • laptop_lounge
  • lounge
  • museum
  • nursing_station
  • parking
  • pharmacy
  • phone
  • play_area
  • printer
  • restaurant
  • restroom
  • restroom_men
  • restroom_women
  • security_checkpoint
  • shop
  • spa
  • stadium
  • stairs
  • swimming_pool
  • taxi
  • theater
  • ticketing
  • train
  • training
  • vending_machines
  • water_fountain
  • wedding

uid Required

UIDs must be unique across all entities of a given entity type (ie. Pages). If an existing entity matches on an imported item's UID, then the entity will be updated with that item. For example, if an exisiting entity has a name and keywords, and the matching imported item has a name and a description, the resulting entity will have the imported name and description, but would retain its keywords. This is especially useful when importing Placemarks where the location information and UID are created in the Meridian Editor, but additional information is imported. Existing entities, previously imported from a feed, without matching UIDs in the latest feed import, are removed from Meridian.

url

The URL of the entity

Example Multi-language XML Page feed

<?xml version="1.0" encoding="UTF-8" ?>
<feed>
    <items>
        <!-- A fully translated page using all available properties -->
        <item>
            <app_link_domain>northside-meridian-elementary-123</app_link_domain>
            <categories>
                <category>Teachers</category>
                <category>Employees</category>
            </categories>
            <custom_1>My custom value</custom_1>
            <custom_2>My second custom value</custom_2>
            <custom_3>My third custom value</custom_3>
            <custom_4>My fourth custom value</custom_4>
            <description><![CDATA[<b>Sara</b> is the first grade teacher.<]]></description>
            <email>sara.anderson@meridianelementary.com</email>
            <image_url>http://meridianelementary.com/images/page123.jpg</image_url>
            <keywords>First, 1st, grade, teacher</keywords>
            <name>Sara Anderson</name>
            <phone>1-800-555-5555</phone>
            <placemarks>
                <placemark>
                    <name>Room 101</name>
                </placemark>
                <placemark>
                    <uid>placemark101</uid>
                </placemark>
            </placemarks>
            <uid>page123</uid>
            <url>http://www.meridianelementary.com/teachers/sara_anderson</url>
            <!-- All the Simplified Chinese translations -->
            <locale code="zh-CN">
                <categories>
                    <category>教师</category>
                    <category>员工</category>
                </categories>
                <custom_1>我的自定义值</custom_1>
                <custom_2>我的第二个自定义值</custom_2>
                <custom_3>我的第三个自定义值</custom_3>
                <custom_4>我的第四个自定义值</custom_4>
                <description><![CDATA[的<b>萨拉</b>是一年级的老师。]]></description>
                <keywords>首先,第一,年级,老师</keywords>
                <name>萨拉·安德森</name>
            </locale>
        </item>

        <!-- A page with only a description translation -->
        <item>
            <uid>page124</uid>
            <name>Mr. Rakofsky</name>
            <description>Mr. Rakofsky teaches science to second graders.</description>
            <locale code="zh-CN">
                <description>Rakofsky先生教二年级的科学.</description>
            </locale>
        </item>

        <!-- An untranslated page -->
        <item>
            <uid>page125</uid>
            <name>Mrs. King</name>
            <description>Mrs. King likes math games when teaching third graders.</description>
        </item>
    </items>
</feed>

Example Multi-language JSON Page Feed

{
  "items":[
    {
      "app_link_domain":"northside-meridian-elementary-123",
      "categories":[
        "Teachers",
        "Employees"
      ],
      "custom_1":"My custom value",
      "custom_2":"My second custom value",
      "custom_3":"My third custom value",
      "custom_4":"My fourth custom value",
      "description":"<b>Sara</b> is the first grade teacher.",
      "email":"sara.anderson@meridianelementary.com",
      "image_url":"http://meridianelementary.com/images/page123.jpg",
      "keywords":"First, 1st, grade, teacher",
      "name":"Sara Anderson",
      "phone":"1-800-555-5555",
      "placemarks":[
        {
          "name":"Room 101"
        },
        {
          "uid":"placemark101"
        }
      ],
      "uid":"page123",
      "url":"http://www.meridianelementary.com/teachers/sara_anderson",
      "locale":{
        "zh-CN":{
          "categories":[
            "教师",
            "员工"
          ],
          "custom_1":"我的自定义值",
          "custom_2":"我的第二个自定义值",
          "custom_3":"我的第三个自定义值",
          "custom_4":"我的第四个自定义值",
          "description":"的<b>萨拉</b>是一年级的老师。",
          "keywords":"首先,第一,年级,老师",
          "name":"萨拉·安德森"
        }
      }
    },
    {
      "description":"Mr. Rakofsky teaches science to second graders.",
      "name":"Mr. Rakofsky",
      "uid":"page124",
      "locale":{
        "zh-CN":{
          "description":"Rakofsky先生教二年级的科学."
        }
      }
    },
    {
      "description":"Mrs. King likes math games when teaching third graders.",
      "name":"Mrs. King",
      "uid":"page125"
    }
  ]
}

Limitations

The feed system is subject to a few limitations to improve performance and reliability:

  • 60 seconds - A single feed can't take longer than 60 seconds to download.
  • 5 megabytes - A single feed can't be larger than 5 megabytes (uncompressed).
  • 10,000 items - A single feed can not contain more than 10,000 items to be imported.

Dealing With Invalid Feeds

Sometimes the Meridian Feed Importer will return messages like, "Invalid XML" or "Invalid RSS". If you would like a more detailed analysis of why your feed is invalid, we recommend the following online services for validating a feed:

  • XML Validator http://validator.w3.org/
  • RSS Validator http://validator.w3.org/feed
  • iCal Validator http://icalvalid.cloudapp.net/
  • JSON Validator http://www.freeformatter.com/json-validator.html

Placemark Feed Logs

The Editor logs all of the placemark feeds imported into it and validates the imported placemarks.

To see the Placemark Feed Log, in the sidebar, click MAPS, and then click Placemark Feed Logs.