Apple Maps Business Listings Integration Specifications Document Version 1.7.3B

Apple Maps Business Listings Integration Specifications Document Version 1.7.3b

Maps Content Provider

2016 | Apple Confidential Contents

CONTENTS ...... 2

OVERVIEW ...... 3

BASE AND RICH ATTRIBUTES ...... 4 Data Definition ...... 4 Data Format ...... 15

PHOTOS AND REVIEWS ...... 19 Data Definition ...... 19 Data Format ...... 22

2016 | Apple Confidential Overview

This document defines the set of attributes required to capture information about a business listing. Attributes have been classified as either "Base and Rich" or "Photos and Reviews". Base and Rich attributes describe a business, Photos and Reviews are for supplemental and user-generated content. Photos and Reviews have a different refresh frequency compared to Base and Rich attributes. To streamline the processing of content serving, Base and Rich and Photos and Reviews attribute sets need to be delivered in two separate feeds. Both feeds must be UTF-8 character encoded. The files are txt files with each record conforming to the JSON specification provided below. Closed businesses have to be indicated using the business_status data attribute flag. Once a business has been verified and indicated as closed, the corresponding business record has to be provided in the data feed for at least 90 days with the business_status set to "Closed". The Required/Optional flag of each attribute defines whether an attribute has to be provided to be considered a technically valid record (Required) or if it doesn’t affect the validity (Optional).

Base and Rich Attributes

All information required to describe a business listing is captured using attributes listed in this section. Each business listing must have a site_code, business_status and one value for names, as well as either main_address or display_point. If possible, all records should have a valid phone_number, home_page, and category. Base and Rich attributes contain static information about the business.

Data Definition

Attribute Type Description Required/Optional Unique identifier, e.g. Required store number. The same site_code must be used for a given business each site_code String time the business is submitted if "Photos and Reviews" attributes are provided. An object that describes Required the current status of this business. The main property of this object is status, which should have one of the following values: • Open business_status Structure • Closed • Temporarily Closed • Duplicate • Moved Additional properties must be specified under the following conditions:

If status is Temporarily Closed, the reopen_date must be indicated (in “yyyy-MM- dd’T’HH:mm:ssZ”). If status is Duplicate, the correct_site_code of the proper business record must be indicated. If status is Closed, the closed_date is closed date and it cannot be future date. It is required to provide closed businesses once a business has been verified as closed for atleast 90 days after the first time a business has been indicated as closed in the data feed. The localized names of Required the business that will be displayed is represented Collection as an array of objects, names of where each object has Structures two attributes: name and locale. locale is an IETF language tag, such as fr- FR or en-US. Additional names, such Optional as aliases for the Collection business, represented as alternate_names of an array of objects. Each Structures object in the array should follow the same format

as names. The primary address for Required if the business, represented display_point is as an object in one of not provided two formats. The first format is an object with one attribute, full_address. The full_address should be text, containing all of the parts of the address formatted onto a single line. The second format is an object with one attribute, structured_address. structured_address should be an object with the main_address Structure following attributes: • street_address, an array of strings. Each element of the array should represent a line of the full street address, including door number, street direction, street name, street type, and unit number (e.g. suite or apartment number). • floor, the floor or level

information with 0 being ground floor and underground levels being denoted by negative integers. • neighborhood, to represent an official sub- locality necessary for delivery of mail. • locality, to represent an official locality, such as a city or town, necessary for delivery of mail. • state_province, to represent an official administrative area, such as a colonia, state or province, necessary for delivery of mail. • postal_code, in the format for the region of the place. • country_code, the two letter country code for the

country of the business. This should be one of the ISO 3166-1 alpha-2 codes. structured_address must at least contain either: • street_address, locality, state_province and country_code, or • postal_code and country_code. The main phone number Optional represented as an object with two attributes: number, an optional type and intent. number should be in the format phone_number Structure for the region of the place. type may be one of the following: Fax, Landline, Mobile or Toll- free. Phone numbers should to be in E.164 format. An array of additional Optional Collection phone numbers. Each alternate_phone_numbers of element of the array Structures should follow the same format as phone_number. Provide a valid URL with Optional scheme, sub, main, and home_page String top-level domain information. (e.g.

http://www.apple.com) An array of URLs, where Optional each value represents a presence on social media (e.g. Facebook, social_media_urls Collection FourSquare, Twitter, Yelp). The format of each URL in the array should follow the same format as home_page. Operating hours for a Optional week. • Format as day_range time_range. Multiple blocks are specified separated by semicolons. • day_range may consist of consecutive days specified as: two hours String different days of the week separated by a hyphen, or individual days of the week separated by commas. • Days in each day_range are specified as days of the week by their first two

letters, capital then lowercase: Mo, Tu, We, Th, Fr, Sa, Su. • time_range is specified as HH:MM-HH:MM. HH is a two-digit hour, on a 24- hour clock (00 to 23). MM is minutes after the hour (00 to 59). • Multiple time ranges may be specified per block, separated by commas. For example: • A business open Monday, Tuesday, Wednesday and Friday, from 8 AM to noon and 2 PM to 5 PM each of those days is specified as: Mo- We, Fr 08:00- 12:00, 14:00-17:00 • A business open weekdays from 9 AM to 9 PM, and weekends from 10 AM to 5 PM is specified as: Mo- Fr 09:00-21:00; Sa-

Su 10:00-17:00 • A business open 24 hours a day, 7 days a week, is specified as: 24/7 • A business open 24 hours a day, weekends only, is specified as: Sa-Su 00:00-24:00 An array of all categories Optional appropriate for this Collection business. If a primary categories of Strings category exists, it must be the first element of the collection. Collection of narrative Optional descriptions of the place or business provided in various locales. A single Collection structure contains content of attributes short_abstract Structures and locale representing the actual text and IETF language tag, such as fr- FR or en-US respectively. Optional. coordinates object Required if including the latitude main_address is and longitude of the not provided place in decimal degrees display_point Structure formatted as string. The source defines how the point was captured: Manually Placed or Calculated.

If you have known entry Optional points for the locations, please provide an array of objects, each with two Collection attributes: point and entry_points of navigation. Object point Structures should follow the same format as display_point. navigation should be be Driving or Walking. Hex-encoded WKB Optional geometry of type point, polygon or multi- geometry String polygon. Easily created and parsed with JTS Topology Suite. An array of all Optional Collection chain appropriate chain names of Strings for this business. An array of all Optional appropriate amenities if any: Reservations, Delivery, Take Out, Good For Kids, Parking, Free Parking, Parking Garage, Collection Wheelchair Access, Pets amenities of Strings Allowed, Free Breakfast, 24-Hour Front Desk, Non- Smoking Throughout, Fitness Room, Spa, Swimming Pool, Business Center, WiFi, Free Internet, Free Wifi, Airport Transportation,

Shuttle. Applicable to online Optional restaurant table reservation only. Flag to indicate the online_reservation Boolean provided business accepts online table reservation via provider platform. Valid values: true, false An array of all Optional appropriate payment methods: Cash, Visa, Debit, Maestro, Mastercard, JCB, Amex, Diners Club, BC Card, Carte Bleue, China UnionPay, Dankort, Collection Girocard (EC), Interac, payment_methods of Strings Laser, Check, Solo, CB, CoGeBan, Banrisul, SPAN2, ZKA, RuPay, Store Card, Traveler’s Check, Invoice, Discover, Financing, Paypal, Square, Google Checkout, Bitcoin, Personal Check. Indicate whether the Optional business accepts Apple Pay using the following apple_pay_status String values: • Accepted • Not Accepted contactless_payments_status String Indicate whether the Optional

business POS accepts Contactless Payments using the following values: • Accepted • Not Accepted

String indicator Optional representing one or more dollar “$” signs indicating less to more costly, such as $(less costly), $$, $$$ and $$$$(very costly). Object range has three pricing Structure attributes currency_code representing ISO 4217 currency code for the pricing information, minrate minimum rate for item/service and maxrate maximum rate for item/service. Object containing type Optional and value of the Collection authoritative rating. For rating of example, Travelers Structures Choice Awards, Zagat, RottenTomatoes, etc. Collection of structures Optional with each comprising of Collection type and localization. metadata of Attribute type is more Structures like unique identifier for the metadata element. Attribute localization is

again collection of localized values having attributes label, value and locale representing display label text , display value text and IETF language tag, such as fr- FR or en-US respectively. A collection of structures Optional with specific information for a defined listing Collection category. category_specific_attributes of Only applicable in Structures combination with a supplementary, category specific document. JSON structure Optional Map of containing additional any valid information. Such additional_info JSON room_facilities, check structure in/out information, etc.

Data Format Each record in the feed will be a valid JSON structure as shown in Listing 1. Base and Rich Attributes. Each JSON record contains data attribute/elements listed in Data Definition section under Base and Rich attribute representing one business listing. Each JSON record must be stored as a string in one line of the data feed, i.e. a JSON record must not contain newline characters. Please note that the entire file is not a JSON format but each line is a valid JSON format. Note: All data elements in Listing 1. are mocked up and URLs may or may not retrieve actual content. The category example is assuming that Apple categories are provided. The entire record below appears as one line in the data feed although it is shown in multiple lines below.

Listing 1. Base and Rich Attributes

{ "site_code": "10003", "names": [{ "name": "Asterisk Hotel", "locale": "en-US" }], "main_address": { "structured_address": { "street_address": [ "Den Texstraat 16" ], "locality": "Amsterdam", "country_code": "nl", "postal_code": "1017 ZA" } }, "phone_number": { "number": "+31206241769", "type": "Landline" }, "alternate_phone_numbers" : [{ "number": "+31206241768", "type": "Landline", "intent": "reservation" },{ "number": "+31206382790", "type": "Fax" }], "home_page": "http://www.asteriskhotel.nl", "social_media_urls": [ "http://www.goodvendor.com/hotel/nl/asterisk.html" ], "hours": "Mo 10:00-12:00,12:30-15:00; Tu-Fr 08:00-12:00,12:30-15:00; Sa 08:00-12:00", "categories": [ "hotelstravel.resorts" ], "content": [{ "short_abstract": "Description of the hotel", "locale": "en-US" }], "display_point": { "coordinates": { "latitude": "52.358834", "longitude": "4.893867" }, "source": "Calculated" }, "entry_points": [{ "point": { "coordinates": { "latitude": "52.358834", "longitude": "4.893834"

}, "source": "Manually Placed" }, "navigation": "Driving" }], "geometry": "01030000000100000005000000B2CDD776247F52C0F0D0C144CD5F44409EA921BB1C7F52C0FD48B65FE35F 4440638BEE6A037F52C0086FB488CD5F4440420F10270B7F52C0E458CD29B75F4440B2CDD776247F52C0F0D 0C144CD5F4440", "chain": [], "amenities": ["Free Parking", "Wheelchair Access", "Pets Allowed", "Free Breakfast", "24-hour front desk", "Non-smoking throughout", "Fitness Room", "Swimming Pool", "Business Center", "WiFi", "Free Internet", "Airport Transportation", "Shuttle" ], "payment_methods": ["Visa", "MasterCard", "AmEx", "DinerClub", "JCB", "Discover", "Traveler’s Check", "Personal Check", "Cash" ], "apple_pay_status": "Accepted", "contactless_payments_status": "Accepted" "pricing": { "indicator": "$$", "range": { "currency_code": "EUR", "minrate": 120.0, "maxrate": 200.0 } }, "business_status": { "status": "Temporarily Closed", "reopen_date": "2013-06-09T00:00:00-0400" }, "metadata": [ { "type": "elevation", "localizations": [ { "locale": "en-US", "label": "Elevation", "value": "220' (67 m)" }, { "locale": "de-DE", "label": "Durchfahrtshöhe", "value": "67 m" } ] }, { "type": "height", "localizations": [ { "locale": "en-US", "label": "Height", "value": "746' (227 m)"

}, { "locale": "de-DE", "label": "Höhe", "value": "227 m" } ] } ], "content": [ { "locale": "en-US", "short_abstract": "This is a sample description" }, { "locale": "de-DE", "short_abstract": "Dies ist eine Beispielbeschreibung" } ], "additional_info": { "room_facilities": [], "checkin": { "time": "14:00" }, "checkout": { "time": "11:00" } } }

Photos and Reviews

Photos are fetched directly from the provider’s content delivery network to the device. The feed will provide metadata about the photo or collection of photos and their corresponding URLs. Reviews are snippets of textual content and their corresponding rating and user information. Full reviews are stored in the provider’s content store and accessible through a deep link.

Data Definition

Attribute Type Description Required/Optional

Business listing site_code Required which these photos and reviews are linked to. Must be site_code String unique throughout the feed and permanently linked to this business listing Preferred photo id for the Required (if business listing. The photo business listing pref_photo_id String referenced by pref_photo_id contains photos) has to be present in the supplied photo collection Total quantity of photos for the Required (if business contained in the business listing supplier’s database. This should contains photos) total_photo_count Integer not be confused with the number of photos in the feed for the given business listing. List of up to 15 photos that are Required photos Collection prioritized for display. - id String Unique id for the photo Required Date photo was added. Format Required - date_added Date must be ISO 8601 “yyyy-MM- dd’T’HH:mm:ssZ” - caption Structure Structure containing text and Optional

locale representing a short (recommended) description of the photo and IETF language tag, such as fr-FR or en-US. Collection of photos sizes such Required as thumbnail, small, medium, large and original. Object containing actual content delivery url for the user image size, pixel_height height and pixel_width width for the photo in pixels. The "original" size is the largest; all remaining sizes Map of are reduced versions of it. - photo_sizes photo Typical minimum pixel sizes sizes (shortest dimension) are: • thumbnail: 150px • small: 250px • medium: 400px • large: 600px • xlarge: 800px • xxlarge: 1200px • original: original dimension Collection of review rating overall/aggregated ratings for required (if the business listing, each business listing Map of object is represented by its contains reviews). overall_rating ratings enum literal, such as star and Can contain 1 star review, where each rating attribute or 1 object has to contain a score review attribute or and a scale. 1 each or none. - score Decimal Numeric value of overall score Required - scale Decimal Numeric value of scale Required Total quantity of reviews for Required (if total_review_count Integer the business contained in the business listing

supplier’s database. This should contains reviews) not be confused with the number of reviews in the feed for the given business listing. Collection of reviews for the Required reviews Collection business - id String Unique id for the review Required Date review was added. Format Required - date_added Date must be ISO 8601 “yyyy-MM- dd’T’HH:mm:ssZ” Number of times a review was Optional - helpful_count Integer flagged as helpful; 0 being nobody has voted so far Object containing the Required. Must attributes text, title and locale contain at least representing the review text, text and locale the title and the locale of the review respectively. The locale - review Structure is an IETF language tag, such as fr-FR or en-US. Optionally (if corresponding data is available) specific positive and negative review texts can be provided. Numeric rating associated with Required - score Decimal review Numeric value of the scale of Required - scale Decimal the review score Object containing attributes of Required, and must the user provide the review at minimum first_name, a string containing contain - user Structure first or given name of the user profile_name last_initial, a string attribute containing last name initial of the user

profile_name, a string containing the profile name of the user. If the actual user name fields are not available, at least the profile_name should be provided. photo_sizes, map representing photo sizes as photo_sizes. Collection of user profile or avatar image object, each object is represented by its enum literal, such as thumbnail, small, medium, large and original.

Data Format Each record in the feed will be a valid JSON structure as shown in Listing 2. Photos and Reviews Attributes. Each JSON record contains data attribute/elements listed in Data Definition section of this document. All data elements are mocked up and URLs may or may not retrieve actual content. Note that the JSON record in Listing 2. Photos and Reviews Attributes has been split into multiple lines for clarity. In actual delivery file each line should correspond to one complete JSON record. Listing 2. Photos and Reviews Attributes

{ "site_code": "102003", "pref_photo_id" : "388827887", "total_photo_count" : 23, "photos" : [{ "id" : "388827887", "date_added" : "2012-01-31T00:00:00-0500", "caption" : { "text" : "The Hotel Captain Cook", "locale" : "en-US" }, "photo_sizes" : { "thumbnail" : { "url" : "http://goodvendor.com/images/hotel/max50/388/3887887.jpg", "pixel_height" : 100, "pixel_width" : 100

}, "small" : { "url" : "http://goodvendor.com/images/hotel/max150/388/3887887.jpg", "pixel_height" : 240, "pixel_width" : 240 }, "medium" : { "url" : "http://goodvendor.com/images/hotel/max300/388/3887887.jpg", "pixel_height" : 320, "pixel_width" : 320 }, "large" : { "url" : "http://goodvendor.com images/hotel/max500/388/3887887.jpg", "pixel_height" : 520, "pixel_width" : 520 }, "original" : { "url" : "http://goodvendor.com/images/hotel/max1500/388/3887887.jpg", "pixel_height" : 1500, "pixel_width" : 2000 } } },{ "id" : "399221158", "date_added" : "2012-01-31T00:00:00-0500", "caption" : { "text" : "The showroom in the hotel", "locale" : "en-US" }, "photo_sizes" : { "thumbnail" : { "url" : "http://goodvendor.com/images/hotel/max50/399/3991158.jpg", "pixel_height" : 100, "pixel_width" : 100 }, "small" : { "url" : "http://goodvendor.com/images/hotel/max150/399/3991158.jpg", "pixel_height" : 240, "pixel_width" : 240 }, "medium" : { "url" : "http://goodvendor.com/images/hotel/840x460/399/3991158.jpg", "pixel_height" : 320, "pixel_width" : 320 }, "large" : { "url" : "http://goodvendor.com/images/hotel/max500/399/3991158.jpg", "pixel_height" : 520, "pixel_width" : 520 }, "original" : { "url" : "http://goodvendor.com/images/hotel/max1500/399/3991158.jpg", "pixel_height" : 1500, "pixel_width" : 2000

} } }], "overall_rating": { "star" : { "score": 4, "scale": 5 }, "review" : { "score": 8.4, "scale": 10 } }, "total_review_count" : 83, "reviews" : [{ "id" : "165373930", "date_added" : "2014-07-24T00:00:00-0400", "helpful_count": 3, "review" : { "text" : "Good public areas in very nice location. As were rooms but there was more noise than expected -.", "title" : "Excellent", "locale" : "en-US" }, "score": 8.8, "scale": 10.0, "user" : { "first_name" : "Tom", "last_initial" : "D.", "profile_name" : "TomTom", "photo_sizes" : { "thumbnail" : { "url" : "http://goodvendor.com/images/photo- t/453663/35368387gh/avatar.jpg", "pixel_height" : 100, "pixel_width" : 100 }, "small" : { "url" : "http://goodvendor.com/images/photo- s/453663/35368387gh/avatar.jpg", "pixel_height" : 240, "pixel_width" : 240 }, "medium" : { "url" : "http://goodvendor.com/images/photo- m/453663/35368387gh/avatar.jpg", "pixel_height" : 320, "pixel_width" : 320 }, "large" : { "url" : "http://goodvendor.com/images/photo- l/453663/35368387gh/avatar.jpg", "pixel_height" : 520, "pixel_width" : 520

} } } }] }