Entity feed

  • Entity feeds must follow a specific JSON or Protobuffer format, including entity_id, name, telephone, url, and location for each Entity.

  • Feed data and descriptor files, including timestamps in their names, should be uploaded daily as full refreshes to the generic SFTP server.

  • The descriptor file's name field must be set to reservewithgoogle.entity and uploaded to the generic SFTP server.

  • SFTP server details and feed ingestion status can be monitored in the Partner Portal under "Configuration > Feeds" and "Feeds > History" respectively.

Create and upload entity feeds

When creating and uploading entity feeds, follow these instructions:

  • Follow the spec described in the entity feed for entity data files. We recommend using unique entity data file names for each upload. Include a timestamp in the filename, for example, entity_1633621547.json.
  • In the fileset descriptor, set the name field to reservewithgoogle.entity. For an example of the descriptor file, refer to the JSON sample. We recommend using unique descriptor file names for each upload. Include a timestamp in the filename, for example, entity_1633621547.filesetdesc.json. The descriptor file must be uploaded to the generic SFTP server.
  • Upload feeds to the generic SFTP server daily as full refreshes.
  • You can find SFTP server details in the Configuration > Feeds section of the Partner Portal.

    • Selecting feed servers

    Selecting feed servers in the Partner Portal
  • View feed ingestion status in the Feeds > History section of the Partner Portal.

Definitions

EntityFeed Definition

message EntityFeed {
  repeated Entity data = 1;
}

Entity Definition

//
// Information about an Entity that is on the partner's platform. For example,
// an Entity could be a retail store, a hospital, an online business etc.
message Entity {
  // An opaque string generated by the partner that identifies an Entity.
  // Must be unique across all entities.
  // Strongly recommended to only include URL-safe characters.
  // This ID should be immutable. Changing or recycling them to represent the
  // same entity may cause issues and outages.
  // (required)
  string entity_id = 1;

  // If present, the name, telephone, url and location are used to support
  // matching partner inventory with entities already present on Google. This
  // information will not be displayed.

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

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

  // The url of the Entity's public website. Highly recommended.
  // (optional)
  string url = 4;

  // The location of the Entity.
  // (required)
  madden.ingestion.GeoCoordinates location = 5;


  // Bookability info for the entity.
  // Only applies to entities representing a merchant selling services or
  // products, and is only relevant for use cases enabled for agentic bookings
  // on Google.
  // (optional)
  BookabilityInfo bookability_info = 8;

  // Entity-specific policies.
  // Only applies to entities representing a merchant selling services or
  // products, and is only relevant for use cases enabled for agentic bookings
  // on Google. Brand-wide policies should be configured in the Brand settings
  // rather than repeated across individual entities.
  // (optional)
  PolicyInfo policy_info = 9;
}

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 {
  // [-90, +90] degrees (inclusive). (optional)
  double latitude = 1;

  // [-180, +180] degrees (inclusive). (optional)
  double longitude = 2;

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

    // An unstructured address could also be provided as a fallback.
    // E.g. "1600 amphitheatre parkway mountain view, ca 94043"
    string unstructured_address = 4;
  }
}

PostalAddress Definition

// The postal address for a merchant.
message PostalAddress {
  // The country, using 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;
}

BookabilityInfo Definition

// Bookability info for the entity.
// Only applies to entities representing a merchant selling services or
// products, and is only relevant for use cases enabled for agentic bookings on
// Google.
message BookabilityInfo {
  // Indicates whether the entity or service can be booked online.
  // (optional)
  bool is_online_bookable = 1;

  // Indicates whether payment is required when booking online.
  // (optional)
  bool payment_required = 2;

  // Indicates whether a credit card must be on file.
  // (optional)
  bool card_on_file_required = 3;

  // Indicates whether a One-Time Password (OTP), such as an email or SMS code,
  // is required when booking an appointment online.
  // (optional)
  bool otp_required = 4;

  // Indicates whether a user must sign in to book an appointment online.
  // (optional)
  bool sign_in_required = 5;
}

PolicyInfo Definition

// Policy info for the entity.
// Represents entity-specific policies. Brand-wide policies should be configured
// in the Brand settings rather than repeated across individual entities.
// Only applies to entities representing a merchant selling services or
// products, and is only relevant for use cases enabled for agentic bookings on
// Google.
message PolicyInfo {
  // Entity-specific policies.
  // (optional)
  repeated Policy policies = 1;
}

Policy Definition

// A named entity-specific policy.
// Only applies to entities representing a merchant selling services or
// products, and is only relevant for use cases enabled for agentic bookings on
// Google. Displayed to the user when performing agentic bookings on Google.
message Policy {
  // A partner-defined policy identifier, not user-facing and possibly not
  // unique. The partner can use this to identify a specific policy content
  // or version. Treated as an opaque identifier by Google.
  // (optional)
  string id = 1;

  // A user-facing localized name for this policy.
  //
  // Standard, Title Case naming is strongly recommended to ensure a clean,
  // consistent, and recognizable user experience. Avoid informal abbreviations
  // or shorthand (e.g., do NOT use "T&C", "T&Cs", "ToS", or "Cancel").
  //
  // Recommended standard names for common policy types:
  //   - "Terms & Conditions" (or "Terms and Conditions" / "Terms of Service")
  //   - "Privacy Policy" (or "Privacy")
  //   - "Cancellation Policy" (or "Refund Policy")
  //   - "Health & Safety Policy"
  //
  // (required)
  Text name = 2;

  // The content of the policy to be displayed or linked to the user.
  // (required)
  oneof content {
    // The textual content of the policy.
    Text text_content = 3;

    // A URL linking to the full policy page.
    Text url_content = 4;
  }
}

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 will be displayed if
  // `localized_value` for the user locale is empty or missing. The locale for
  // this value may depend on the partner or service provider, and it should not
  // 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 above (UTF-8).
  string value = 2;
}

Entity feeds samples

Entity Feed

{
  "data": [
    {
      "entity_id": "appointments-merchant-1",
      "name": "Lorem ipsum Barbershop",
      "telephone": "+11111222233",
      "url": "https://barbershop.com",
      "location": {
        "latitude": 37.422113,
        "longitude": -122.084041,
        "address": {
          "country": "US",
          "locality": "Mountain View",
          "region": "California",
          "postal_code": "94043",
          "street_address": "1600 Amphitheater Drive"
        }
      },
      "bookability_info": {
        "is_online_bookable": true,
        "payment_required": false,
        "card_on_file_required": false,
        "otp_required": false,
        "sign_in_required": false
      },
      "policy_info": {
        "policies": [
          {
            "id": "policy-1",
            "name": {
              "value": "Cancellation Policy",
              "localized_value": [
                {
                  "locale": "en",
                  "value": "Cancellation Policy"
                },
                {
                  "locale": "es",
                  "value": "Política de cancelación"
                }
              ]
            },
            "text_content": {
              "value": "Appointments must be canceled at least 24 hours in advance.",
              "localized_value": [
                {
                  "locale": "en",
                  "value": "Appointments must be canceled at least 24 hours in advance."
                },
                {
                  "locale": "es",
                  "value": "Las citas deben cancelarse con al menos 24 horas de anticipación."
                }
              ]
            }
          },
          {
            "id": "policy-2",
            "name": {
              "value": "Terms & Conditions",
              "localized_value": [
                {
                  "locale": "en",
                  "value": "Terms & Conditions"
                },
                {
                  "locale": "es",
                  "value": "Términos y condiciones"
                }
              ]
            },
            "url_content": {
              "value": "https://barbershop.com/terms",
              "localized_value": [
                {
                  "locale": "en",
                  "value": "https://barbershop.com/terms"
                },
                {
                  "locale": "es",
                  "value": "https://barbershop.com/es/terms"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Descriptor File

{
  "generation_timestamp": 1677545962,
  "name": "reservewithgoogle.entity",
  "data_file": [
    "entity_1677545962_0001.json",
    "entity_1677545962_0002.json"

  ]
}