API FAQs

1. How do I connect and authenticate with my API token? 

How you write your query depends on the HTTP method and content-type you specify. Per the GraphQL spec, the request can be sent as either GET or Post. 

If you send a GET request:

The parameters must be properly escaped in the query string. 

If you send a POST request: 

This should include a JSON-encoded body, illustrated in this article.

Use this URL in your GET and POST requests: 

https://api.matterport.com/api/models/graph

Sample HTTP GET request (using the URL above): 

https://api.matterport.com/api/models/graph?query=query{%20models{%20totalResults%20results%20{%20id%20name%20created%20modified%20visibility%20}}}

Authorization: Basic <api credentials> 

Sample cURL request: 

curl \
--user [apiKey]:[apiSecret] \
-v 'https://api.matterport.com/api/models/graph?query=\{models\{totalResults%20results\{id%20created%20modified%20visibility\}\}\}'

Notice the symbols above taken from the cURL request - these are escaping for bash. The cURL will not automatically URL encode whitespace, which is why the %20 is added. 

2. How do I retrieve panoramic images? 

Panoramic images are currently only available as skyboxes. 

What's a skybox?  

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 rendered in 4K and come bundled with position and rotation data. 

How to retrieve skybox images  

Use the query below: 

query {
model(id:"$modelId") {
assets {
panos {
perspective {
options {
format
resolutions
}
skybox(resolution: "4k") {
id
status
format
children
}
position {x,y,z}
rotation {x,y,z,w}
}
}
}
}
}

3. The Showcase SDK and Model API coordinates don't seem to match - how do I use both? 

This is a bit confusing, but is expected behavior. The Showcase SDK is designed to work from the perspective of the camera, so its coordinate system rotates to determine the Y axis (height) and Z axis (depth). If you were to download a Matterpak, you would find all of the coordinate information with Z-up. The SDK hides this by only exposing certain pieces of information. 

right.png

The psuedo-code for doing the translation is as follows: 

def fromSdkToApi(x, y, z) = { -x, -z, y }

def fromApiToSdk(x, y, z) = { -x, z, -y }

Note that the translation above may seem odd because the Z and Y coordinates are both flipped, and one is inverted. 

4. I can't see the changes I am doing with the Model API right away - what should I do? 

This happens because of caching in our CDM. An edit/publish flow will fully flush the CDN cache, though we don't currently do that for every edit at the API layer. 

One way to verify that you're experiencing a CDN cache issue is to look at the model in a private or incognito window. Authenticated users will bypass the cache but anonymous viewers will not. If this is the case, changes should be visible to everyone within an hour. 

5. Can I manipulate a 3D mesh of a model with the API?

No, the API can only currently get and set model details, assets, Mattertags, labels, and bundles.

6. How do I query all models with Python using requests? 

Use the query below: 

import requests 

token = 'Your API token'
secret = 'Your secret API token'
endpoint = 'https://api.matterport.com/api/models/graph'
query = { 'query' :
'''
query {
models(query: "*"){
totalResults
results{ id }
}
}
'''
}
auth = (token, secret)
headers = {'content-type': 'application/json', 'accept':'gzip'}
r = requests.post(endpoint, json=query, auth=auth, headers=headers)

if(r.ok):
print(r.json())
else:
print(r.status_code)

 

7. I'm a collaborator with Admin editing privileges for an organization - why can't I query any models on the account? 

If you are set as a collaborator (as opposed to an admin), you cannot access models through the API. If you need access, you have two options: 

  1. Request that an account admin transfers the space to you
  2. Have the admin of the account share their API tokens with you
    • An API token will give you access to every model that belongs to the admins' account. 
Have more questions? Submit a request