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: 

http://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 -H "Authorization: Basic <base 64 encoded [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: 

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

3. 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.

4. 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)

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

 

5. 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. 

6. How do I check the status of all the models in my account?

The ModelSearchResult object doesn't contain the state. For now, you may need to query for all the ids, and then query for each id to get the Model object, which contains the state field.

Have more questions? Submit a request