metadata queryCopy link

Retrieves all supported values for fields that can be set on a unit and unit space, such as

• Locale codes
• Text keys
• Amenity names and values

Use this helper query to retrieve this data before issuing mutations to ensure you are specifying supported values. It is provided to help you understand what's available as you develop mutations to create and update properties.

Reading amenity metadata

As described above, you can use the metadata query to retrieve all supported values for various unit and space details. While most metadata is easy to read, such as locales and undefined that both provide key values you can simply pass into mutations, amenity metadata is complex. This section is provided to help you understand how to read it so that you can define amenities at any level. The code examples in this section show unit-level amenities, but you can apply your learnings to space-level amenities as well.

Here is the query request to retrieve unit-level amenities:

1query {  
2  metadata {  
3    property {  
4      units {
5        amenities {
6          fieldsRequired
7          key
8          value {
9            fields {
10              key
11              required
12              type
13              typeDetails {
14                ... on AmenityFieldEnumTypeDetails {
15                  multipleValuesAllowed
16                  enumTypeValues: values
17                }
18                ... on AmenityFieldFeeTypeDetails {
19                  feeTypeValues: values
20                }
21              }
22            }
23          }
24        }
25      }
26    }
27  }
28}

Here is an excerpt from the query's response, which shows the housekeeping amenity:

1{
2  "fieldsRequired": true,
3  "key": "housekeeping",
4  "value": {
5    "fields": [
6      {
7        "key": "frequency",
8        "required": false,
9        "type": "enum",
10        "typeDetails": {
11        "multipleValuesAllowed": false,
12        "enumTypeValues": [
13          "ON_REQUEST",
14          "DAILY",
15          "WEEKLY",
16          "ONCE"
17        ]
18      }
19    },
20    {
21      "key": "availability",
22      "required": false,
23      "type": "enum",
24      "typeDetails": {
25        "multipleValuesAllowed": true,
26        "enumTypeValues": [
27          "LIMITED",
28          "WEEKENDS",
29          "WEEKDAYS"
30         ]
31        }
32      }
33    ]
34  }
35}

Here’s an explanation of this metadata:

• fieldsRequired – When true, indicates that at least one field must be specified to save the amenity to the property, unit, or space. When false, no fields are required to save the amenity. In the example above, fieldsRequired is true so either the frequency field or availability key must be set to save this amenity to the unit.

• required – Indicates whether the key must be specified (or whether it’s optional). If fieldsRequired is true but none of the individual fields is required, any one of the fields must be specified but no individual one is required. In the example above, both fields are optional, so you can set either one.

• type – Indicates the key’s type:

  • enum – Enumeration, allowed values provided by the enumTypeDetailsValues object; the multipleValuesAllowed field indicates whether more than one enumeration value can be specified
  • trilean - Values include true, false, or null
  • undefined – Free text
  • fee – Enumeration, allowed values provided by the feeTypeDetailsValues object
  • int – Integer value
  • decimal – Decimal value

For example, to set the frequency field for the amenity in this example, specify one of the enumeration values (because multipleValuesAllowed is false):

Mutation examples based on metadata

These examples demonstrate how to read metadata for an amenity and then set it. Code snippets are provided instead of full request and responses, for brevity.

• Amenity with fields required

  • Metadata
  • Mutation
  • Copy

  1{
  2  "fieldsRequired": true,
  3  "key": "boat",
  4  "value": {
  5    "fields": [
  6      {
  7        "key": "type",
  8        "required": true,
  9        "type": "enum",
  10        "typeDetails": {
  11          "multipleValuesAllowed": true,
  12          "enumTypeValues": [
  13            "BOAT",
  14            "KAYAK"
  15          ]
  16        }
  17      },
  18      {
  19        "key": "boat-description",
  20        "required": false,
  21        "type": "text",
  22        "typeDetails": null
  23      },
  24      {
  25        "key": "kayak-description",
  26        "required": false,
  27        "type": "text",
  28        "typeDetails": null
  29      }
  30    ]
  31  }
  32},

• Amenity with no fields required

  • Metadata
  • Mutation
  • Copy

  1{ 
  2  "fieldsRequired": false, 
  3  "key": "water-sports-equipment", 
  4  "value": { 
  5    "fields": [ 
  6      { 
  7        "key": "description", 
  8        "required": false, 
  9        "type": "text", 
  10        "typeDetails": null 
  11      } 
  12    ] 
  13  } 
  14} 

• Amenity that allows multiple enumeration values

  • Metadata
  • Mutation
  • Copy

  1{  
  2  "fieldsRequired": true,   
  3  "key": "games",  
  4  "value": {   
  5    "fields": [  
  6      {  
  7        "key": "description",  
  8        "required": false,  
  9        "type": "text",  
  10        "typeDetails": null
  11      },
  12      {  
  13        "key": "age",  
  14        "required": false,  
  15        "type": "enum",  
  16        "typeDetails": {  
  17          "multipleValuesAllowed": true,  
  18          "enumTypeDetailsValues": [  
  19            "FOR_CHILDREN",  
  20            "FOR_ADULTS"  
  21          ]  
  22        }  
  23      }  
  24    ]  
  25  }  
  26} 

• Amenity that does not allow multiple enumeration value

  • Metadata
  • Mutation
  • Copy

  1{
  2  "fieldsRequired": false,
  3  "key": "wifi-in-unit",
  4  "value": {
  5  "fields": [
  6    {
  7      "key": "description",
  8      "required": false,
  9      "type": "text",
  10      "typeDetails": null
  11    },
  12    {
  13      "key": "fee",
  14      "required": false,
  15      "type": "fee",
  16      "typeDetails": {
  17        "feeTypeValues": [
  18          "UNSPECIFIED_AMOUNT",
  19          "FREE"
  20        ]
  21      }
  22    },
  23    {
  24      "key": "speed",
  25      "required": false,
  26      "type": "enum",
  27      "typeDetails": {
  28        "multipleValuesAllowed": false,
  29        "enumTypeValues": [
  30          "250_MBPS_GOOD_FOR_3_5_PEOPLE_OR_UP_TO_10_DEVICES",
  31          "100_MBPS_GOOD_FOR_1_2_PEOPLE_OR_UP_TO_6_DEVICES",
  32          "50_MBPS",
  33          "500_MBPS_GOOD_FOR_6_PEOPLE_OR_10_DEVICES",
  34          "25_MBPS"
  35        ]
  36      }
  37    }
  38  ]
  39}

Syntax

1query { 
2  metadata: Metadata 
3} 

Examples

The GraphQL explorer is provided for the examples below. Use this interactive explorer to get comfortable with the sample queries.

• For each query, a test property ID is passed into the explorer; its test data is returned.
• Click Run Query to execute the query in the explorer on the page. You can modify the query to retrieve the desired fields, and the explorer provides a list of fields when you start typing.
• Click API Explorer to launch the full explorer in another tab/window, which provides syntax highlighting, schema introspection, real-time error highlighting, and auto-completion, among other things.

Visit this page to view short videos that demonstrate the explorer.

Unit-level features

Unit-level amenities

Unit spaces