# 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

> [!NOTE]
> **Note:** The Merchant Feed specification is defined in protocol buffer format. However, we recommend you to upload the feeds in JSON format. For more information, see [JSON sample feeds](https://developers.google.com/actions-center/verticals/reservations/e2e/reference/feeds/merchants-feed#samples).

### 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;
    }