Cómo utilizar la API de Matterport

Nuestra comunidad de desarrolladores está llena de profesionales de la industria que quieren integrar Matterport en sus flujos de trabajo diarios: estamos comprometidos a hacer frente a este desafío, y eso empieza con la apertura de nuestra API a arquitectos, ingenieros y cualquier otro profesional que quiera sumergirse en nuestra plataforma

Ahora ofrecemos un conjunto de herramientas para desarrolladores que permitirá a los desarrolladores conectarse directamente con el almacén de datos back-end de Matterport, a la vez que permite a los clientes actuar sobre sus modelos mediante programación. Desde el acceso directo a los datos, hasta la modificación del contenido, pasando por la gestión del estado de un modelo o la compra de servicios de valor añadido, queremos que nuestros desarrolladores tengan un control total.

Documentación

Puedes obtener más información sobre nuestras capacidades actuales de GraphQL API en nuestra guía de referencia: esto también te concederá acceso a nuestra consola interactiva, donde puedes experimentar con GraphQL API de forma limitada. 

Para acceder a la consola interactiva, deberás iniciar sesión en Matterport Cloud (my.matterport.com) con credenciales de administrador.

Instrucciones

Generar claves de API

  1. Ve a Matterport Cloud (my.matterport.com)
  2. Haz clic en el menú desplegable "Cuenta" (Account) a la derecha
  3. Selecciona "Herramientas para desarrolladores" (Developer Tools)
  4. Desplázate hasta la sección titulada "Api Token Management" (API Token Management)
    • Aquí puedes solicitar y revocar claves de API.

Deberás generar una clave de API que te permita conectarte a nuestro punto de conexión de API. Recuerda que puedes generar hasta cinco claves para su uso en las distintas aplicaciones que deseas crear. Al crear una nueva clave, verás lo siguiente:

  1. Secreto de token
    • Esto solo se presenta una vez: asegúrate de copiarlo y guardarlo de forma segura. 
  2. Id. de token
    • Esto se mostrará en la página de ajustes

Las claves de API son claves "admin" o "all-access". Esto significa que conceden a los usuarios credenciales administrativas a la cuenta de cliente. Si utilizan la API con la clave de API generada, los desarrolladores pueden realizar todas las funciones administrativas mediante la API, incluidos los modelos de archivado y la compra de planos de planta y MatterPaks. Es importante recordar esto al compartir las claves de API: te recomendamos encarecidamente que no compartas las claves de API con empresas o desarrolladores de terceros.

Ten en cuenta que las cuentas solo tienen habilitado el modo Sandbox de forma predeterminada. Para obtener más información sobre el modo Sandbox, consulta nuestra Disponibilidad y precios de herramientas para desarrolladores.

Conéctate al punto de conexión

  1. Accede al punto de conexión de API: https://api.matterport.com/api/models/graph 
  2. Utiliza el Id. de token como el nombre de usuario
  3. Utiliza el token secreto como contraseña
    • Ejemplo: Autorización: Básica <base64_encode(<Token ID>:<Token Secret) 

Todas las bibliotecas http estándar deben admitir este proceso, pero asegúrate de establecer tu autorización preventiva en "true".   

Códigos de error

Todos los errores a nivel de aplicación tendrán "códigos" (codes) en sus extensiones de error: utiliza la siguiente guía para reconocer y solucionar problemas de códigos de error comunes.

   1. request.unauthenticated

No hay ningún token de autorización presente o el token de autorización ha caducado.

   2. request.unauthorized 

El usuario intentó acceder a una operación o campo que no tiene permitido.

   3. request.invalid 

No se pudo procesar la consulta gráfica.

   4. error.internal 

El servidor no pudo procesar la solicitud.

   5. not.found 

El objeto solicitado no existe: verás este error al usar el campo de id. específico en la operación asociada.

   6. not.unique 

Se intentó recuperar un único registro de un índice secundario, pero hay varios registros que coinciden con la consulta enviada. Esto ocurre a menudo cuando varios modelos tienen el mismo id. interno.

   7. quota.exceeded 

Mutaciones limitadas de recursos: por ejemplo, intentar activar más modelos de los permitidos debido a limitaciones de suscripción.

Ejemplos de fragmento de código

Para empezar, consutla estos ejemplos de fragmento de código

Preguntas frecuentes

1. ¿Qué es una API?

API es la abreviación en inglés de "interfaz de programación de aplicaciones": este es un protocolo de comunicaciones entre diferentes partes de un programa informático. La intención principal de una API es simplificar la implementación y el mantenimiento del software.

Las API de Matterport permiten a los desarrolladores (o clientes) conectar mediante programación sus sistemas o aplicaciones directamente al sistema de Matterport para acceder y modificar datos.

2. Matterport también ofrece un "SDK": ¿cuál es la diferencia?

Antes de la versión beta de la API de Matterport, los desarrolladores de Matterport utilizaron principalmente el SDK de Showcase (kit de desarrollo de software). La beta de API es una función suplementaria: repasemos las diferencias a continuación.

SDK de Showcase

El SDK de Showcase es un conjunto de comandos de programación que pueden usar los desarrolladores para ampliar las capacidades de Showcase, incluso si Showcase está directamente insertado en otro sitio o plataforma. Considéralo como una capa delgada e invisible que se encuentra en la parte superior del Showcase iFrame, solo en la página para desarrolladores. Teniendo esto en cuenta, el SDK solo afecta a la experiencia de una página de desarrollador por uso. Como tal, los modelos que se han compartido en varios sitios solo se ven afectados en la página del desarrollador donde se ha aplicado el SDK.

API

Al contrario del SDK, la API se conecta directamente al back-end de Matterport. Esto permite a los desarrolladores realizar diversos comandos, como buscar, leer datos, cambiar datos y realizar pedidos. La API Matterport permite a los desarrolladores llevar a cabo acciones mediante programación que los clientes realizan en nuestro sitio. 

3. ¿Qué es la API de modelo y qué otras API se están considerando?

El mundo de las API es inmenso: por ahora, Matterport está agrupando los diferentes comandos que estamos poniendo a disposición de los desarrolladores en subcategorías:

Comandos de API de modelo

Estos comandos buscan, leen y/o cambian los datos del modelo. ¿Qué constituyen los datos del modelo? Detalles del modelo (como el nombre y la dirección del espacio), el uso compartido de direcciones URL, imágenes, vídeos, datos de posición, el archivo de malla OBJ, el archivo de nube de puntos, imágenes panorámicas, puntos de posición y Mattertags.

Introducir comando de API

Estos comandos envían una colección de imágenes panorámicas directamente a la canalización de visión Matterport, todo un esfuerzo por intentar una reconstrucción en 3D. Junto con las imágenes panorámicas, los desarrolladores pueden enviar metadatos adicionales, como una secuencia de panorámicas, una panorámica del suelo y otros datos de posición. Básicamente, cuantos más metadatos se proporcionen, mayores serán las posibilidades de una reconstrucción 3D correcta. 

A medida que esta solución vaya madurando, esperamos apoyar a los clientes que han tomado una colección de imágenes panorámicas utilizando diferentes cámaras de 360° que antes eran incompatibles con nuestra plataforma.

Comandos de API de cuenta

Estos comandos administran usuarios y carpetas, incluido el aprovisionamiento y la configuración de permisos.

Comandos de API de servicio

Estos comandos permiten a los desarrolladores descubrir, realizar pedidos y acceder mediante programación a los servicios de valor añadido que ofrecemos, además de los modelos de Matterport (como MatterPaks y planos de planta).

Publicar comandos de API

Estos comandos permiten a los desarrolladores descubrir y utilizar mediante programación todas las actuales plataformas de publicación compatibles con Matterport. Estas plataformas incluyen Google Street View, Vrbo, realtor.com y homes.com.

4. ¿A qué cuentas puedo acceder mediante la API?

Se recomienda usar solo la API para acceder a la cuenta y los modelos del cliente. Ten en cuenta que el token de API es, básicamente, un conjunto de credenciales administrativas y ofrece acceso completo a la cuenta (incluso para realizar compras a través de la API). 

5. ¿Cómo puedo empezar? 

Tendrás que solicitar un token de API: sigue las breves instrucciones que se indican a continuación. 

  1. Ve a Matterport Cloud (my.matterport.com)
  2. Haz clic en el menú desplegable "Cuenta" (Account) a la derecha
  3. Selecciona "Herramientas para desarrolladores" (Developer tools)
  4. Desplázate hasta la sección titulada "Api Token Management" (API Token Management)
    • Aquí puedes solicitar y revocar claves de API.

6.  ¿Tienes más preguntas? 

Consulta nuestras ampliadas Preguntas frecuentes de la API del modelo.

¿Tiene más preguntas? Enviar una solicitud