Apple Maps Business Listings Integration Specifications Document Version 1.7.3B
Total Page:16
File Type:pdf, Size:1020Kb
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). 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 3 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: 2015-01-20 | Copyright © 2015 Apple Inc. All Rights Reserved | Apple Confidential 4 Base and Rich Attributes 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 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 5 Base and Rich Attributes 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 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 6 Base and Rich Attributes 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 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 7 Base and Rich Attributes 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. 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 8 Base and Rich Attributes 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 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 9 Base and Rich Attributes 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- 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 10 Base and Rich Attributes 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. 2015-06-24 | Copyright © 2016 Apple Inc. All Rights Reserved | Apple Confidential 11 Base and Rich Attributes If you have known entry Optional points for the locations, please provide an array