This is a library of ready-to-use sample GraphQL queries and mutations for Matterport’s Model API.

Each query and mutation contains a link to try the query in our interactive console. If you are logged into your account at my.matterport.com, you will be able to use the interactive console. If you have a Developer Tools license, the Interactive Console will be able to query all models in your account. If you are in Sandbox mode, it will only be able to query the demo model in your account.

With all queries, be sure to edit the variables, when provided, and insert a valid Model ID and valid data for all variables.

If you would like an application to build collections of API queries for testing and generating code to use in your applications, we recommend using Postman and have these snippets available in a sample collection.

If you are needing assistance with building queries, refer to our API schema or contact us at developer@matterport.com

Testing in Sandbox Mode

API Users in Sandbox mode can test these queries on a demo model in their account. The models() query will only return your demo model. Purchasing a developer license will change this behavior to show the models in your account. You can still find the SID of the demo model in production mode using the provided ‘Search for demo models in your account’ query found below.

Models Queries

models() queries get data from our models search engine. Searchable data can be found here.

Search for your models
query {
  models(query: "*") {
    totalResults
    results {
      id
      name
      description
    }
  }
}

Sample Response:

{
  "data": {
    "models": {
      "totalResults": 1,
      "results": [
        {
          "id": "MODEL_ID",
          "name": "352 E Java Dr",
          "description": ""
        }
      ]
    }
  }
}

Try this query in our interactive console

Search for demo models in your account

All accounts come with a demo model. This can be queried in sandbox mode for testing purposes. If you wish to find the demo models with a models query, use “demo: true” as your query. You can also include ‘demo’ in your results to verify that this is a demo model.

query {
  models(query: "demo:true", include: demo) {
    results {
      name
      demo
      id
    }
    nextOffset
    totalResults
  }
}

Sample Response:

{
  "data": {
    "models": {
      "results": [
        {
          "name": "Get Started",
          "demo": true,
          "id": "xiyHP9VkT1U"
        },
        {
          "name": "Get Started",
          "demo": true,
          "id": "YGYWqVqWDpm"
        }
      ],
      "totalResults": 2
    }
  }
}

Try this query in our interactive console

Search for archived models
query archivedModels {
  models(query: "state:inactive", include: inactive) {
    results {
      name
      state
      id
    }
    nextOffset
    totalResults
  }
}

Try this query in our interactive console

Search for Models with x # of Floors
query {
  models(query: "floors.count: 20") {
    results {
      id
      name
    }
    nextOffset
    totalResults
  }
}

Try this query in our interactive console

Model Queries

model() queries get data from individual models.

Get all Sweep Locations and Panoramic Images

Panoramic images are currently only available as skyboxes.

A skybox is made out of six images - each image individually projected onto the shape of a cube - that is: top, bottom, left, right, front and back sides. Skyboxes are available in 2K and come bundled with position and rotation data.

fragment panoFragment on PanoramicImageLocation{
  id
  skybox {
    id
    status
    format
    children
  }
}

query getSweeps($modelId: ID!){
    model(id: $modelId) {
      locations {
        id
        model { id }
        position { x, y, z }
        floor { id }
        room { id }
        panos { ...panoFragment }

    }
  }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "locations": [{
          "id": "a0723324-ab3e-4500-bdee-8fec13d3ae9d",
          "model": {
            "id": "MODEL_ID"
          },
          "position": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "panos": [{
            "id": "a0723324-ab3e-4500-bdee-8fec13d3ae9d",
            "skybox": {
              "id": "a0723324-ab3e-4500-bdee-8fec13d3ae9d",
              "status": "available",
              "format": "skybox",
              "children": [
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox0.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox1.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox2.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox3.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox4.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox5.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1"
              ]
            }
          }]
        }, ...
      }]
  }
}

Try this query in our interactive console

Get all Tags and Tag Data

Users can get all Tags from a model. Presently, attachments are not queriable.

query getMattertags($modelId: ID!) {
  model(id: $modelId) {
    mattertags(includeDisabled: true) {
      id
      floor { id }
      created
      modified
      enabled
      color
      label
      description
      icon  # New!
      keywords
      media
      mediaType
      position { x, y, z }
      anchorPosition { x, y, z }
      discPosition { x, y, z }
      stemNormal { x, y, z }
      stemLength
      stemEnabled
      stemDirection { x, y, z } # Deprecated, use stemNormal and stemLength
    }
  }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "mattertags": [{
        "id": "ayi201wkujs",
        "floor": {
          "id": "pd0i1c4yq9w0y2zsb07ed23sb"
        },
        "created": "2017-09-29T19:45:57Z",
        "modified": "2019-11-18T22:26:42Z",
        "enabled": true,
        "color": "#03687d",
        "label": "Nest Thermostat",
        "description": "",
        "icon": "public_symbols_video",
        "keywords": [],
        "media": null,
        "mediaType": null,
        "position": {
          "x": 1.20415628,
          "y": -5.35434341,
          "z": 3.1942153
        },
        "anchorPosition": {
          "x": 1.20415628,
          "y": -5.35434341,
          "z": 3.1942153
        },
        "discPosition": {
          "x": 1.40415628,
          "y": -5.35434341,
          "z": 3.1942153
        },
        "stemNormal": {
          "x": 1,
          "y": 0,
          "z": 0
        },
        "stemLength": 0.2,
        "stemEnabled": true,
        "stemDirection": {
          "x": 0.2,
          "y": 0,
          "z": 0
        }
      }, ]
    }
  }
}

Try this query in our interactive console

Get all Dimensional Data from the Model, Floors and Rooms
query getDimensions($modelId: ID!) {
  model(id: $modelId) {
      name
      description
      dimensions {
      ...dimensions
      }
      floors {
      label
      dimensions(units: imperial) {
          ...dimensions
      }
    }
     rooms {
      id
      label
      tags
      dimensions {
          ...dimensions
      }
    }
  }
}

fragment dimensions on Dimension {
areaCeiling
areaFloor
areaFloorIndoor
areaWall
volume
depth
height
width
units
}

# variables

{
"modelId" : ""
}

Sample Response:

{
    "data": {
        "model": {
            "name": "Model Name",
            "description": "Model Description",
            "dimensions": {
                "areaFloor": 270.23811626434326,
                "areaFloorIndoor": 245.12091588974,
                "volume": 1185.8062753677368,
                "units": "metric"
            },
            "floors": [
                {
                    "label": "Floor 1",
                    "dimensions": {
                        "areaFloor": 1811.2674341550348,
                        "areaFloorIndoor": 1763.751272911024,
                        "areaWall": 4200.7835074106215,
                        "volume": 30221.99651317749,
                        "units": "imperial"
                    }
                },
                {
                    "label": "Floor 2",
                    "dimensions": {
                        "areaFloor": 1097.5486255027295,
                        "areaFloorIndoor": 874.7057536345482,
                        "areaWall": 2896.4391288173674,
                        "volume": 11654.396359551525,
                        "units": "imperial"
                    }
                }
            ],
            "rooms": [
                {
                    "id": "h26t7ky77ew74yb0pg8qqf5rd",
                    "label": "6",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 12.459799766540527,
                        "areaFloorIndoor": 12.459799766540527,
                        "areaWall": 41.87590026855469,
                        "volume": 37.56352996826172,
                        "height": 3.0147781372070312,
                        "units": "metric"
                    }
                },
                {
                    "id": "tt6gm2a0463x9wmnx7rn6gugc",
                    "label": "5",
                    "tags": [
                        "laundry"
                    ],
                    "dimensions": {
                        "areaFloor": 5.239500045776367,
                        "areaFloorIndoor": 5.239500045776367,
                        "areaWall": 25.518861770629883,
                        "volume": 15.819963455200195,
                        "height": 3.019364833831787,
                        "units": "metric"
                    }
                },
                {
                    "id": "kuc0fpmsgqxff63egrxrycfud",
                    "label": "16",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 19.056400299072266,
                        "areaWall": 54.98054504394531,
                        "volume": 57.81614303588867,
                        "height": 3.0339488983154297,
                        "units": "metric"
                    }
                },
                {
                    "id": "wbpb7dkfuwnikd1kq2a9hz70a",
                    "label": "14",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 1.646399974822998,
                        "areaWall": 4.429454803466797,
                        "volume": 4.219707489013672,
                        "height": 2.562990665435791,
                        "units": "metric"
                    }
                },
                {
                    "id": "b4qtykzcazp4iumkamm7y7h2b",
                    "label": "12",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 12.713900566101074,
                        "areaFloorIndoor": 12.713900566101074,
                        "areaWall": 38.93343734741211,
                        "volume": 32.931732177734375,
                        "height": 2.590214729309082,
                        "units": "metric"
                    }
                },
                {
                    "id": "3m54yff1z7crxaywd8if9rb0d",
                    "label": "7",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 4.156899929046631,
                        "areaFloorIndoor": 4.156899929046631,
                        "areaWall": 24.900320053100586,
                        "volume": 12.581944465637207,
                        "height": 3.026761531829834,
                        "units": "metric"
                    }
                },
                {
                    "id": "a5f9age4zzxewres6iqux2emc",
                    "label": "9",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 4.8993000984191895,
                        "areaFloorIndoor": 4.8993000984191895,
                        "volume": 12.761096954345703,
                        "height": 2.604677438735962,
                        "units": "metric"
                    }
                },
                {
                    "id": "cdz3fkt38kae7tapstpt0eaeb",
                    "label": "3",
                    "tags": [
                        "kitchen",
                        "living",
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 102.59071350097656,
                        "areaFloorIndoor": 102.59071350097656,
                        "areaWall": 184.97195434570312,
                        "volume": 657.700927734375,
                        "units": "metric"
                    }
                },
                {
                    "id": "ediidma5zg15dufx3n0qyq21a",
                    "label": "13",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 24.611000061035156,
                        "areaFloorIndoor": 24.611000061035156,
                        "areaWall": 49.6417236328125,
                        "volume": 81.93767547607422,
                        "units": "metric"
                    }
                },
                {
                    "id": "xy2x8mpaaqknp7q2c3nnbw1ma",
                    "label": "4",
                    "tags": [
                        "dining",
                        "living"
                    ],
                    "dimensions": {
                        "areaFloor": 17.3887996673584,
                        "areaFloorIndoor": 17.3887996673584,
                        "areaWall": 46.00373458862305,
                        "volume": 52.49049758911133,
                        "height": 3.0186383724212646,
                        "units": "metric"
                    }
                },
                {
                    "id": "2qdmc5i9byxi79ry1pxdkqzea",
                    "label": "8",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 15.340200424194336,
                        "areaFloorIndoor": 15.340200424194336,
                        "areaWall": 41.409175872802734,
                        "volume": 57.230098724365234,
                        "units": "metric"
                    }
                },
                {
                    "id": "m8npxsuk79xy21dd09x9wtped",
                    "label": "11",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 4.3730998039245605,
                        "areaFloorIndoor": 4.3730998039245605,
                        "areaWall": 15.520317077636719,
                        "volume": 11.225411415100098,
                        "height": 2.566923141479492,
                        "units": "metric"
                    }
                },
                {
                    "id": "n81qfe51azs8iexnbqwspye6c",
                    "label": "15",
                    "tags": [
                        "office"
                    ],
                    "dimensions": {
                        "areaFloor": 4.414400100708008,
                        "areaWall": 18.9549503326416,
                        "volume": 13.287762641906738,
                        "height": 3.0100948810577393,
                        "units": "metric"
                    }
                },
                {
                    "id": "19ab05tns5h6y4qm42esqqpea",
                    "label": "10",
                    "tags": [
                        "bedroom",
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 19.325401306152344,
                        "areaFloorIndoor": 19.325401306152344,
                        "areaWall": 64.1736068725586,
                        "volume": 71.8935775756836,
                        "units": "metric"
                    }
                },
                {
                    "id": "613htqkzf66zz7hf7n8kzszed",
                    "label": "2",
                    "tags": [
                        "living"
                    ],
                    "dimensions": {
                        "areaFloor": 22.022300720214844,
                        "areaFloorIndoor": 22.022300720214844,
                        "areaWall": 48.04021453857422,
                        "volume": 66.34620666503906,
                        "height": 3.0126829147338867,
                        "units": "metric"
                    }
                }
            ]
        }
    }
}

Try this query in our interactive console

Get the Colored Rooms Floorplan URL
query getColoredRooms($modelId: ID!){
 model(id: $modelId) {
    assets {
      floorplans(provider: "matterport", flags: [colored_rooms]) {
        provider
        format
        flags
        id
        url
      }
    }
  }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "assets": {
        "floorplans": [
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_000.jpg?t=2-45286ff9b37da4d31d06a13b828c497d00343f7c-1679975423-1&download=colorplan_room_000.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_000.jpg"
          },
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_001.jpg?t=2-3377428ace2fcebeb51b5a24d55aff51ad6b85db-1679975423-1&download=colorplan_room_001.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_001.jpg"
          },
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_002.jpg?t=2-878d69a6f66558f17271e17b4c4f5a03b606368f-1679975423-1&download=colorplan_room_002.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_002.jpg"
          },
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_003.jpg?t=2-0dd57e99aa752e228ef2d85b9aff89f8663b826b-1679975423-1&download=colorplan_room_003.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_003.jpg"
          }
        ]
      }
    }
  }
}

Try this query in our interactive console

Export Model Meshes at 50k Quality

Our Developers can use Model API to access a decimated, “50k” quality, model mesh of their space.

This is the version of the model mesh used for mobile users viewing a space with Showcase. Unlike the Matterpak, which is an extremely high quality export, this low quality model mesh can be used to experiment with as a way to evaluate this data before purchasing a Matterpak.

Please note that at this time, we do not provide access to the .mtl file that will map textures to this export.

query getMeshes($modelId: ID!) {
  model(id: $modelId) {
    assets {
      meshes {
        id
        status
        filename
        format
        resolution
        url
        validUntil
      }
      textures {
        id
        status
        filename # does not return data
        format
        url # does not return data
        validUntil
        resolution
        type # does not return data
        quality
        textures
        urlTemplate # \<texture\> -> 000, 001, 002, 003, etc.
      }
    }
  }
}

Sample Response:

{
  "data": {
    "model": {
      "assets": {
        "meshes": [{
          "id": "meshes/k0cbt2rhkzhnm4ekr4p4cqhia",
          "status": "available",
          "filename": "out_res_50k.obj",
          "format": "obj",
          "resolution": "50k",
          "url": "https://cdn-2.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/out_res_50k.obj?t=2-9be6e9c8980e1541613d687ed316ea30b6356c2a-1681839634-1",
          "validUntil": "2023-04-18T17:40:34Z"
        }],
        "textures": [{
            "id": "50k-high",
            "status": "available",
            "format": "jpg",
            "validUntil": "2023-04-18T17:40:34Z",
            "resolution": "50k",
            "quality": "high",
            "urlTemplate": "https://cdn-2.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/~/9fa4913fb6064e79adf33ce70afd7d2a_50k_texture_jpg_high/9fa4913fb6064e79adf33ce70afd7d2a_50k_ &
              lt;texture & gt;.jpg ? t = 2 - d85c089d213be29e8a6bf7d64a63dbb6c8d5e00e - 1681839634 - 0 & k = models % 2 F1a56eedeff7d4a7481b961c009ae9236 % 2 Fassets "
          },
          {
            "id": "50k-low",
            "status": "available",
            "format": "jpg",
            "validUntil": "2023-04-18T17:40:34Z",
            "resolution": "50k",
            "quality": "low",
            "urlTemplate": "https://cdn-2.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/~/9fa4913fb6064e79adf33ce70afd7d2a_50k_texture_jpg_low/9fa4913fb6064e79adf33ce70afd7d2a_50k_&lt;texture&gt;.jpg?t=2-d85c089d213be29e8a6bf7d64a63dbb6c8d5e00e-1681839634-0&k=models%2F1a56eedeff7d4a7481b961c009ae9236%2Fassets"
          }
        ]
      }
    }
  }
}

Try this query in our interactive console

Get Add-On Bundle Download Links
query getBundles($modelId: ID!){
  model(id:$modelId) {
    bundles(availability:unlocked) {
            id
            availability
            assets {
                url
                format
            }

        }
    }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "bundles": [
        {
          "id": "mp:matterpak",
          "availability": "unlocked",
          "assets": [
            {
              "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/bundles/aec.zip?t=2-a03f0704b9b9da393501d4817d1826c193ee0280-1679975256-1&download=matterpak_WeZ1dHwn3ac.zip&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Fbundles%2Faec.zip",
              "format": "zip"
            }
          ]
        },
        {
          "id": "bim:cad",
          "availability": "unlocked",
          "assets": [
            {
              "url": "https://cdn-2.matterport.com/jobs/bim-asset/df598b5a-02d8-47a7-9dd9-a0ade8250d71.zip?t=2-1b59739c853d184dcae3888ca57754e38919b992-1679975256-1&download=bim_WeZ1dHwn3ac.zip&k=jobs%2Fbim-asset%2Fdf598b5a-02d8-47a7-9dd9-a0ade8250d71.zip",
              "format": "zip"
            }
          ]
        },
        {
          "id": "mp:e57",
          "availability": "unlocked",
          "assets": [
            {
              "url": "https://mp-app-prod.s3.amazonaws.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/bundles/cloude57.zip?response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27e57_WeZ1dHwn3ac.zip&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230328T034236Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIA2OYCIXZCYUE7ZVXS%2F20230328%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=b799ce581a4d055b60e6bb72c7fe6416b50d7e58208a100ee5bdc9aea083bda4",
              "format": "zip"
            }
          ]
        },
        {
          "id": "floorplan:schematic",
          "availability": "unlocked",
          "assets": [
            {
              "url": "https://cdn-2.matterport.com/floorplans/WeZ1dHwn3ac/362550b1-d088-4932-b61f-6c3f1f02bc13.zip?t=2-204baf0ca5aa0dfcbe46e1417ddb991822d20553-1680493356-1&download=362550b1-d088-4932-b61f-6c3f1f02bc13.zip&k=floorplans%2FWeZ1dHwn3ac%2F362550b1-d088-4932-b61f-6c3f1f02bc13.zip",
              "format": "zip"
            }
          ]
        }
      ]
    }
  }
}

Try this query in our interactive console

Find the Different Purchase Options for Any Bundle
query getSupportedOptions($modelId: ID!) {
   model(id: $modelId) {
      bundles {
        id
        name
        description
        availability
         supportedOptions {
         measurementUnits
         deliverySpeeds
         }
      }
   }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "bundles": [
        {
          "name": "Matterpak",
          "description": "Order high resolution assets associated with the model.",
          "availability": "unlocked",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Model Geometry",
          "description": "Order the model geometry files.",
          "availability": "unavailable",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Low Resolution Geometry",
          "description": "Order the lower resolution model geometry files.",
          "availability": "unavailable",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Object Detection",
          "description": "Order automated object detection model inferencing.",
          "availability": "unavailable",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Cubicasa Schematic Floorplan",
          "description": "Order an enhanced schematic floorplan",
          "availability": "unlocked",
          "supportedOptions": {
            "measurementUnits": ["imperial", "metric"],
            "deliverySpeeds": []
          }
        },
        {
          "name": "TruePlan™ Schematic",
          "description": "Order a TruePlan™ Schematic",
          "availability": "locked",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Google Street View",
          "description": "Publish to Google Street View",
          "availability": "locked",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Vrbo - HomeAway",
          "description": "Create a 360 Tour for Vrbo and HomeAway",
          "availability": "locked",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Advanced Imagery Pack",
          "description": "Enables access to high resolution panoramic images",
          "availability": "unavailable",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "BIM",
          "description": "Order Building Information Modeling Files",
          "availability": "unlocked",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "e57 Point Cloud",
          "description": "3D Imaging Point Cloud Files",
          "availability": "unlocked",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Schematic Floorplan",
          "description": "Order an enhanced schematic floorplan",
          "availability": "unlocked",
          "supportedOptions": {
            "measurementUnits": ["imperial", "metric"],
            "deliverySpeeds": ["normal", "fast", "urgent"]
          }
        },
        {
          "name": "Standard CAD",
          "description": "Order a Standard CAD",
          "availability": "unavailable",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        },
        {
          "name": "Matterport Stitching",
          "description": "Stitch up to 6 models together",
          "availability": "unavailable",
          "supportedOptions": {
            "measurementUnits": null,
            "deliverySpeeds": null
          }
        }
      ]
    }
  }
}

Try this query in our interactive console

Mutations

Mutations update data via Model API. They can also contain queries that return data after the data has changed. The query can return an ID if new content has been added, or updated information that may have changed due to the patch (update).

Toggle Model Visibility and Get Embed URL
mutation toggleModelVisibility($modelId: ID!, $visibility: ModelVisibility!){
  updateModelVisibility(
    id: $modelId,
    visibility: $visibility  # public or private
  ){
    id
    publication {
      published
      url
      externalUrl
      embed
    }
  }
}

# variables
{
  "modelId" : "",
  "visibility" : "public"
}

Sample Response:

{
  "data": {
    "updateModelVisibility": {
      "id": "WeZ1dHwn3ac",
      "publication": {
        "published": true,
        "url": "https://my.matterport.com/show/?m=WeZ1dHwn3ac",
        "externalUrl": null,
        "embed": "&lt;frame width='853' height='480' src='https://my.matterport.com/show/?m=WeZ1dHwn3ac' frameborder='0' allowfullscreen allow='xr-spatial-tracking'>&lt;/iframe>"
      }
    }
  }
}

Try this query in our interactive console

Toggle Model Activation (archive / activate)
mutation toggleModelActivation($modelId: ID!, $state: ModelStateChange!) {
  updateModelState(id: $modelId, state: $state) {
    id
  }
}

Try this query in our interactive console

Patch Model Details

Model API can be used to change the default settings for a model and all meta information associated with it using the patchModel mutation.

mutation toggleModelVisibility($id: ID!){
  patchModel(id: $id, patch: {
      name: "Model Name",
      description: "Model Description",
      options: {
          # For all following options:
          # default, enabled, disabled
          socialSharingOverride: default,
          vrOverride: default,
          tourButtonsOverride: default,
          tourAutoplayOverride: default,
          dollhouseOverride: default,
          dollhouseLabelsOverride: default,
          floorplanOverride: default,
          labelsOverride: default,
          highlightReelOverride: default,
          unitType: {
              set: metric, # or imperial
              resetToDefault: false
          },
          # Special options:
          measurements: {
            # disabled, measure, measureAndView
            set: measureAndView,
            resetToDefault: false
          },
          backgroundColor: {
              # black, grey, white
              set: white,
              resetToDefault: false
          },
      }
      mls: {
          id: "MLS ID",
          name: "Listing Name"
      },
      publication: {
          contact: {
              name: "Contact Person",
              email: "person@domain.com",
              phoneNumber: "888-888-8888"
          }
          externalUrl: "https://linktomoreinfo.com",
          presentedBy:"Your Company Name",
          summary: "Summary information about this model."
      },

  }) {
    id
    name
    description
    options {
          socialSharingOverride,
          vrOverride,
          tourButtonsOverride,
          tourAutoplayOverride,
          dollhouseOverride,
          dollhouseLabelsOverride,
          floorplanOverride,
          labelsOverride:,
          highlightReelOverride,
          unitType,
          measurements,
          backgroundColor
    }
    mls {
        id
        name
    }
    publication {
          contact {
              name
              email
              phoneNumber
          }
          presentedBy
          externalUrl
          summary
      }
  }
}

# variables
{
    "id" : "FE1FLGnch5h"
}

Sample Response:

{
  "data": {
    "patchModel": {
      "id": "FE1FLGnch5h",
      "name": "Model Name",
      "description": "Model Description",
      "options": {
        "socialSharingOverride": "default",
        "vrOverride": "default",
        "tourButtonsOverride": "default",
        "tourAutoplayOverride": "default",
        "dollhouseOverride": "default",
        "dollhouseLabelsOverride": "default",
        "floorplanOverride": "default",
        "labelsOverride": "default",
        "unitType": "metric",
        "measurements": "measureAndView",
        "backgroundColor": "white"
      },
      "mls": {
        "id": "MLS ID",
        "name": "Listing Name"
      },
      "publication": {
        "contact": {
          "name": "Contact Person",
          "email": "person@domain.com",
          "phoneNumber": "(888) 888-8888"
        },
        "presentedBy": "Your Company Name",
        "externalUrl": "https://linktomoreinfo.com",
        "summary": "Summary information about this model."
      }
    }
  }
}

Try this query in our interactive console

Change Address Visibility

Model API can be used to change the default settings for a model and all meta information associated with it using the patchModel mutation.

mutation changeAddressVisibility($id: ID!){
    updateModelAddress(
      id: $id,
      addressVisibility: none     # full, partial or none
    ) {
        options {
            addressVisibility
        }
    }
  }

# variables
{
    "id" : "FE1FLGnch5h"
}

Sample Response:

{
  "data": {
    "updateModelAddress": {
      "id": "FE1FLGnch5h",
      "name": "Model Name",
      "options": {
        "addressVisibility": "none"
      }
    }
  }
}

Try this query in our interactive console

Add a Mattertag

Adding a Tag requires a valid floorId, which you can get by querying floors

mutation addMattertag(
  $modelId: ID!,
  $floorId: ID!,
  $color: String,
  $description: String,
  $label: String,
  $icon: String,
  $keywords: [String!],
  $enabled: Boolean!,
  $anchorPositionX: Float!,
  $anchorPositionY: Float!,
  $anchorPositionZ: Float!,
  $stemEnabled: Boolean!,
  $stemNormalX: Float!,
  $stemNormalY: Float!,
  $stemNormalZ: Float!,
  $mediaType: MattertagMediaType,
  $mediaUrl: String,
  $stemLength: Float!
){
  addMattertag(
    modelId: $modelId,
    field: id,
    mattertag: {
      floorId: $floorId, # Must be valid
      enabled: $enabled, # required and can be true or false
      color: $color,
      label: $label,
      icon: $icon,
      keywords: $keywords,
      description: $description,
      anchorPosition: { x: $anchorPositionX, y: $anchorPositionY, z: $anchorPositionZ },
      mediaType: $mediaType,
      mediaUrl: $mediaUrl,
      stemEnabled: $stemEnabled,
      stemNormal: { x : $stemNormalX , y: $stemNormalY, z: $stemNormalZ },
      stemLength: $stemLength
    }
  ) {
    id
  }
}

# variables
{
  "modelId" : "",
  "floorId": "pd0i1c4yq9w0y2zsb07ed23sb",
  "color": "#03687d",
  "label": "Updated Tag",
  "icon": "public_symbols_video",
  "keywords" : ["API Tag", "Test Patch Tag"],
  "description": "This Tag was updated!",
  "enabled" : true,
  "anchorPositionX" : 1.20415628,
  "anchorPositionY" : -5.3543434,
  "anchorPositionZ" : 3.1942153,
  "stemNormalX" : 1.0,
  "stemNormalY" : 0.0,
  "stemNormalZ" : 0.0,
  "mediaType" : "video",
  "mediaUrl" : "https://www.youtube.com/watch?v=dAdsl9x_Dyw",
  "stemEnabled" :  true,
  "stemLength" :  0.16459
}

Try this query in our interactive console

Patch a Mattertag

Patching a Tag requires providing the tag Id.

mutation patchMatterTag(
  $modelId: ID!,
  $tagId: ID!
  $floorId: ID!,
  $color: String,
  $description: String,
  $label: String,
  $icon: String,
  $keywords: [String!],
  $enabled: Boolean!,
  $anchorPositionX: Float!,
  $anchorPositionY: Float!,
  $anchorPositionZ: Float!,
  $stemEnabled: Boolean!,
  $stemNormalX: Float!,
  $stemNormalY: Float!,
  $stemNormalZ: Float!,
  $mediaType: MattertagMediaType,
  $mediaUrl: String,
  $stemLength: Float!
){
  patchMattertag(
    modelId: $modelId,
    field: id,
    mattertagId: $tagId,
    patch: {
      floorId: $floorId, # Must be valid
      enabled: $enabled, # required and can be true or false
      color: $color,
      label: $label,
      icon: $icon,
      keywords: $keywords,
      description: $description,
      anchorPosition: { x: $anchorPositionX, y: $anchorPositionY, z: $anchorPositionZ },
      mediaType: $mediaType,
      mediaUrl: $mediaUrl,
      stemEnabled: $stemEnabled,
      stemNormal: { x : $stemNormalX , y: $stemNormalY, z: $stemNormalZ },
      stemLength: $stemLength
    }
  ){
    id # Returns Tag ID
  }
}

# variables
{
  "modelId" : "",
  "tagId" : "ayi201wkujs",
  "floorId": "pd0i1c4yq9w0y2zsb07ed23sb",
  "color": "#03687d",
  "label": "Updated Tag",
  "icon" : "public_symbols_video",
  "keywords" : ["API Tag", "Test Patch Tag"],
  "description": "This Tag was updated!",
  "enabled" : true,
  "anchorPositionX" : 1.20415628,
  "anchorPositionY" : -5.3543434,
  "anchorPositionZ" : 3.1942153,
  "stemNormalX" : 1.0,
  "stemNormalY" : 0.0,
  "stemNormalZ" : 0.0,
  "mediaType" : "video",
  "mediaUrl" : "https://www.youtube.com/watch?v=dAdsl9x_Dyw",
  "stemEnabled" :  true,
  "stemLength" :  0.16459
}

Try this query in our interactive console

Buy a Matterpak

Use the timed URL from the response to download the MatterPak

mutation buyMatterpak($modelId: ID!){
  unlockModelBundle(
    id: $modelId,
    bundleId: "mp:matterpak"
  ) {
    id
  name
  description
  availability
  assets { url }
  }
}

# variables

{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "unlockModelBundle": {
      "id": "mp:matterpak",
      "name": "Matterpak",
      "description": "Order high resolution assets associated with the model.",
      "availability": "unlocked",
      "assets": [
        {
          "url": "https://qa-cdn-1.matterport.com/models/group_77/job_62927cc2-7552-4aad-8330-3904c5198354/wf_39d3f0f8baae4fc9aaeb6326edf55d8f/mesh/1.1.466.14860/2016-11-09_0240.05/62927cc275524aad83303904c5198354.zip?t=2-b3da2c89760c80f1671bc260d678d949f29bd8a8-1573485841-1"
        }
      ]
    }
  }
}

Try this query in our interactive console

Ordering Add-On Bundles - Workflow

Query: Find the Asset Ids and Delivery Speeds by Looking through all Bundles

The following query returns all asset bundles that can be purchased, including optional delivery speeds if applicable (schematic floorplans).

fragment asset on Asset{
  id
  url
  validUntil
  format
  filename
  status
}

query getBundleAssets($modelId: ID!){
  model(id: $modelId) {
    bundles {
      id
      availability
      name
      description
      assets { ...asset }
      supportedOptions {
        deliverySpeeds
      }
    }
  }
}

# variables
{
  "modelId" : ""
}

Try this query in our interactive console

Mutation: Ordering and Retrieving a Schematic Floor Plans

We are taking the bundleId from the previous query that we’d like to order and now performing a mutation to buy it.

Note - Assets will not be immediately available. Schematic Floorplans won’t be available until our floor plan team returns it (normal speed is about 2 days).

mutation buyAddOn($modelId: ID!){
  unlockModelBundle(    id: $modelId,
    bundleId: "cubicasa:floorplan",
    options: { deliverySpeed: normal }
  ){
    id
    name
    description
    availability
    assets { url }
  }
}

# variables
{
  "modelId" : ""
}

Try this query in our interactive console

Query: Retrieve the Purchased Add-On
query getAddOn($modelId: ID!) {
  model(id: $modelId) {
    bundle(id: "floorplan:schematic") {
      assets { url }
    }
  }
}
# variables
{
  "modelId" : ""
}

Try this query in our interactive console