Merchant Feed Samples and Definitions

Merchant Feed sample

Following are the definitions of two merchants:

  • dining-1: this merchant ID uses a structured address, which is the recommended format.
  • dining-2: this merchant ID uses an unstructured address.
{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 0,
    "total_shards": 1,
    "nonce": "11203880",
    "generation_timestamp": 1524606581
  },
  "merchant": [
    {
      "category": "restaurant",
      "merchant_id": "dining-1",
      "name": "Dining Eats",
      "url": "www.dining1publicsite.com",
      "telephone": "+1 123-456-7890",
      "geo": {
        "latitude": 37.422113,
        "longitude": -122.084041,
        "address": {
          "locality": "Mountain View",
          "country": "US",
          "region": "CA",
          "street_address": "1600 Amphitheatre Pkwy",
          "postal_code": "94043"
        }
      }
    },
    {
      "category": "restaurant",
      "merchant_id": "dining-2",
      "name": "Burger Heaven",
      "url": "www.dining2publicsite.com",
      "telephone": "+1 123-456-12345",
      "geo": {
        "latitude": 37.422113,
        "longitude": -122.084041,
        "unstructured_address": "345 Spear St., San Francisco, CA 94105"
      }
    }
  ]
}

Definitions

Merchant Feed definition

The Merchant Feed contains the FeedMetadata object and the merchant array.

message MerchantFeed {
  FeedMetadata metadata = 1;
  repeated Merchant merchant = 2;
}

Merchant definition

// Info about a merchant that is on the aggregator's platform.
// A merchant feed should be a list of this message.
message Merchant {

  // An opaque string generated by the partner that identifies a merchant.
  // Must be unique across all merchants.
  // Strongly recommended UID or UUID, or to only include URL-safe characters.
  // Don't use URIs (required)

  string merchant_id = 1;

  // The name, telephone, URL and geo are used to support matching partner
  // inventory with merchants already present on Google Maps. This
  // information is not be displayed but should be a close match to
  // merchant's Google Business Profiles.

  // The name of the merchant. (required)
  string name = 2;

  // The contact telephone number of the merchant including its country and
  // area codes, e.g. +14567891234. Highly recommended. (optional)
  string telephone = 3;

  // The URL of the merchant's public website. Highly recommended.
  // This isn't a booking link to your platform. (optional)
  string url = 4;

  // The Geo info of the merchant, including latitude, longitude, and
  // address. (required)
  GeoCoordinates geo = 5;

  // The category of the business in aggregator's platform. (required)
  // You must categorize this business as you categorize it in your
  // inventory.
  // We use the category you provide as a parameter when we try to determine
  // the best location match to the physical business.
  string category = 6;

  // The specific merchant's Terms and Conditions displayed to the user when
  // a service is being booked through Reserve with Google.
  // In addition to these the aggregator partner's Terms and Conditions are
  // always displayed to the user and must not be provided here. (optional)
  Terms terms = 13;

  // An opaque string that identifies the consumer-facing brand to use when
  // displaying partner attribution. This field allows partners with
  // multiple consumer-facing brands to provide merchants for all brands
  // within the same feed.
  //
  // A brand consists of consumer-facing properties like the name, logo,
  // Terms of Service, and Privacy Policy.
  //
  // If there is only one consumer-facing partner brand, this field doesn't
  // need to be set and can be ignored.
  //
  // If the partner...
  //
  //   Doesn't have multiple consumer-facing brands?
  //     --> Ignore this field
  //
  //   Has Multiple Brands that are configured?
  //
  //       If this field is set
  //         --> Associated consumer-facing brand attribution is used
  //
  //       If this field is unset or the empty string
  //         --> Default consumer-facing brand attribution is used
  //
  // Careful Note: Most partners don't need to set this field. If a partner
  // wishes to use this field, they must contact us first to configure
  // separate brands, including the default brand.
  string brand_id = 14;

GeoCoordinates definition

// The Geo data of a location, including latitude, longitude, and address.
// At least one of [lat/lng or address] should be provided (or both).
message GeoCoordinates {
  double latitude = 1;  // In degrees. (optional)

  double longitude = 2;  // In degrees. (optional)

  // Address for a location, can either be structured or unstructured.
  oneof addresses {
    // Postal address of the location, preferred.
    PostalAddress address = 3;

    // An unstructured address can also be provided as a fallback.
    // E.g. "1600 amphitheater parkway mountain view, ca 94043".
    // Use of only unstructured_address can impact matcher quality.
    string unstructured_address = 4;
  }
}

PostalAddress definition

// The postal address for a merchant.
message PostalAddress {
  // The country, with ISO 3166-1 alpha-2 country code, e.g. "US". (required)
  string country = 1;

  // The locality/city, e.g. "Mountain View". (required)
  string locality = 2;

  // The region/state/province, e.g. "CA". This field is only required in
  // countries where region is commonly a part of the address. (optional)
  string region = 3;

  // The postal code, e.g. "94043". (required)
  string postal_code = 4;

  // The street address, e.g. "1600 Amphitheatre Pkwy". (required)
  string street_address = 5;
}

Terms definition

// A set of rules and guidelines that are displayed to the
// user in order to make a booking through Reserve with Google.
message Terms {
  // The URL to the Terms and Conditions. (optional)
  string url = 1;

  // The text to be displayed to the user.
  // Use localized_text here for new integrations.
  string text = 2;

  // The localized text to be displayed to the user. (required)
  Text localized_text = 3;
}

Text definition

// A possibly-localized text payload. Some Text fields may contain marked-up
// content.
message Text {
  // Required. Text value in an unknown locale, which is displayed if
  // `localized_value` for the user locale is empty or missing. The locale for
  // this value can depend on the partner or service provider, and it
  // shouldn't be assumed to be any specific language.
  string value = 1;

  // Per-locale text values. Required.
  repeated LocalizedString localized_value = 2;
}

LocalizedString definition

// Instance of a string in one locale.
message LocalizedString {
  // IETF BCP 47 language code, such as "en", "mas", "zh-Hant", "de-CH-1901".
  // See http://www.w3.org/International/articles/language-tags/.
  string locale = 1;

  // Message in the locale here (UTF-8).
  string value = 2;
}