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": ""
}
]
}
}
}
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
}
}
}
Search for archived models
query archivedModels {
models(query: "state:inactive", include: inactive) {
results {
name
state
id
}
nextOffset
totalResults
}
}
Search for Models with x # of Floors
query {
models(query: "floors.count: 20") {
results {
id
name
}
nextOffset
totalResults
}
}
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"
]
}
}]
}, ...
}]
}
}
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
}
}, …]
}
}
}
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"
}
}
]
}
}
}
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"
}
]
}
}
}
}
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_<texture>.jpg?t=2-d85c089d213be29e8a6bf7d64a63dbb6c8d5e00e-1681839634-0&k=models%2F1a56eedeff7d4a7481b961c009ae9236%2Fassets"
}
]
}
}
}
}
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"
}
]
}
]
}
}
}
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
}
}
]
}
}
}
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": "<frame width='853' height='480' src='https://my.matterport.com/show/?m=WeZ1dHwn3ac' frameborder='0' allowfullscreen allow='xr-spatial-tracking'></iframe>"
}
}
}
}
Toggle Model Activation (archive / activate)
mutation toggleModelActivation($modelId: ID!, $state: ModelStateChange!) {
updateModelState(id: $modelId, state: $state) {
id
}
}
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."
}
}
}
}
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"
}
}
}
}
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
}
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
}
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"
}
]
}
}
}
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" : ""
}
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" : ""
}
Query: Retrieve the Purchased Add-On
query getAddOn($modelId: ID!) {
model(id: $modelId) {
bundle(id: "floorplan:schematic") {
assets { url }
}
}
}
# variables
{
"modelId" : ""
}