Start Using the Matterport API Today

Our developer community is full of industry professionals who want to integrate Matterport into their every-day workflows - we're committed to face this challenge, and that starts with opening up our API to architects, engineers, and any other professionals who want to dive deeper into our platform

We're in the process of developing a toolset that will allow devs to directly connect to Matterport's back-end and datastore, while also allowing customers to act on their models programmatically. From directly accessing data, to modifying content, to managing a model's status, to purchasing value-added services - we want our developers to have full control. 

This is what's known as a multi-quarters initiative - our GraphQLAPI program is currently in beta with limited capabilities. You can learn more about the tools that are currently available here. 

If this is of conceptual interest, check out the article below to learn more about joining our API beta program. 

Joining 

Our API program is currently in beta, meaning it doesn't cover all of the use cases discussed above yet. There are still various limitations, and this is why we want to open a direct line of communication with customers interested in the program - we want to ensure our goals are aligned, and that each unique customers' desires are in-line with the capabilities we currently offer in the beta. 

Interested? We want to hear from you - contact us at beta-platform@matterport.com to begin the qualification process. If you're already signed up, continue reading to learn how to get started with Matterport's API beta. 

Before you begin 

Documentation 

You can learn more about our current GraphQLAPI capabilities in our reference guide - this will also grant you access to our interactive console, where you can experiment with the GraphQL API on a limited basis. 

In order to access the interactive console, you'll need to be logged into Matterport Cloud (my.matterport.com) with admin credentials. 

Instructions 

Generate API keys

  1. Go to Matterport Cloud (my.matterport.com)
  2. Click the "Account" dropdown to the right 
  3. Select "Manage" 
  4. Scroll to the section titled "API Token Management" 
    • Here, you can request and revoke API keys. 

As soon as your account has been enabled for AI use, you will need to generate an API key that will allow you to connect to our API endpoint. Keep in mind, you can generate up to five keys for use across the different applications you want to build. When you create a new key, you will be presented with the following: 

  1. Token Secret 
    • This is only presented once - make sure to copy and save it securely. 
  2. Token ID 
    • This will be displayed on the settings page

API keys are "admin" or "all-access" keys. This means they grant users administrative credentials to the customer account. Using the API with the generated API key, developers can perform all administrative functions using the API, including archiving models, and purchasing floorplans and MatterPaks. It's important to remember this when sharing your API keys - we highly advise that you don't share your API keys with third party companies or developers. 

Connect to the endpoint 

  1. Access the API endpoint at: https://api.matterport.com/api/models/graph 
  2. Use the Token ID as the username
  3. Use the Token Secret as the password
    • Example: Authorization: Basic <base64_encode(<Token ID>:<Token Secret) 

All standard http libraries should support this process, but make sure to set your preemptive authorization to "true".   

Error codes 

All application-level errors will have "codes" in their error extensions - use the guide below to recognize and troubleshoot common error codes. 

   1. request.unauthenticated 

No authorization token is present, or the authorization token has expired. 

   2. request.unauthorized 

User attempted to access an operation or field that is not allowed. 

   3. request.invalid 

The graph query could not be processed. 

   4. error.internal 

The server was unable to process the request. 

   5. not.found 

The requested object doesn't exist - you will see this error when using the specific ID field in the associated operation. 

   6. not.unique 

An attempt was made to retrieve a single record from a secondary index, but multiple records matched the submitted query. This often happens when multiple models have the same internal ID. 

   7. quota.exceeded 

Resource limited mutations - for example, attempting to activate more models than allowed due to subscription limitations. 

Code snippet examples 

To get started, refer to these code snippet examples

FAQs 

1. What is an API? 

API is short for "application programming interface" - this is a communications protocol between different parts of a computer program. The main intention of an API is to simplify the implementation and maintenance of software. 

Matterport APIs allow developers (or customers) to programmatically connect their systems or applications directly to the Matterport system in order to access and modify data. 

2. Matterport also offers an "SDK" - what's the difference? 

Prior to the Matterport API beta, Matterport developers primarily utilized the Showcase SDK (software development kit). The API beta is a supplemental feature - let's go over the differences below.. 

Showcase SDK 

The Showcase SDK is a set of programming commands that can be used by developers to extend Showcase capabilities, even if the Showcase is directly imbedded on another site or platform. Think of it as a thin, invisible layer that sits on top of the Showcase iFrame, only on the developer page. With that in mind, the SDK only affects the experience on one developer page per-use. As such, models that have been shared on multiple sites are only affected on the developer's page where the SDK has been applied. 

API

Opposed to the SDK, the API connects directly to the Matterport back-end. This allows developers to perform a variety of commands, like searching, reading data, changing data, and placing orders. The Matterport API allows devs to programmatically perform actions that customers take on our site. 

3. What is the Model API, and what other APIs are being considered?

The world of APIs is immense - for now, Matterport is grouping the different commands we're making available to developers into sub-categories: 

Model API commands

These commands search, read, and/or change model data. What's constitutes model data? Model details (like the name and address of the space), sharing URLs, images, videos, position data, the OBJ mesh file, the point cloud file, panoramic imagery, position points and Mattertags. 

Ingest API commands 

These commands send a collection of panoramic images directly into the Matterport vision pipeline - all an in effort to attempt a 3D reconstruction. Along with panoramic images, developers can send additional metadata, like a panos sequence, a panos of the floor, and other position data. Essentially, the more metadata provided, the higher the chances of a successful 3D reconstruction. 

As this solution matures, we hope to support customers who have taken a collection of panoramic images using different 360° cameras that were previously incompatible with our platform. 

Account API commands 

These commands manage users and folders, including provisioning and setting up permissions. 

Service API commands 

These commands allow developers to programmatically discover, place orders, and access the value-added services we offer in addition to Matterport models (like MatterPaks and floorplans). 

Publish API commands 

These commands let developers programmatically discover and use all of the publishing platforms Matterport supports today. These include Google Street View, Vrbo, realtor.com, and homes.com. We will be adding additional parters in the second half of 2020. 

4. What accounts can I access using the API? 

We recommend only using the API to access the customer's account and models. Keep in mind, the API token is essentially a set of administrative credentials, and provides full access to the account (even to make purchases via API). 

In the second half of 2020 we will support multiple levels of permissions, including restricted access to other people's models and accounts, so long as they are properly accepted by the account owners. 

5. How do I get started? 

You'll need to request an API token - follow the short instructions below. 

  1. Go to Matterport Cloud (my.matterport.com)
  2. Click the "Account" dropdown to the right 
  3. Select "Manage" 
  4. Scroll to the section titled "API Token Management" 
    • Here, you can request and revoke API keys. 
Have more questions? Submit a request