Guía de gestión de claves API de TMAS

La API web de TMAS permite a los usuarios acceder y exportar datos de tráfico sin problemas, integrándose con herramientas y aplicaciones de terceros. Esta guía proporciona instrucciones para crear, administrar y usar claves API de forma eficaz.

Limitaciones de las llamadas API

• El rango de fechas no puede exceder un mes.
• La API web de TMAS tiene un límite de velocidad de una llamada cada dos segundos.
• Para acceder a los datos de tráfico en intervalos de un minuto o menos, se debe activar el push rápido en la cadena y configurar el dispositivo contador en configuración activada . Nota: Esto SÓLO está disponible con la suscripción TMAS en tiempo real.

Recomendaciones de llamadas API

Llamadas de datos por hora

• Limitación: si su aplicación requiere actualizaciones de datos cada hora, tenga en cuenta el uso justo.
• Optimización: Al actualizar datos de varias ubicaciones (p. ej., más de 40), limite las llamadas a la API para recuperar solo los datos de las últimas tres horas. Este enfoque ayuda a gestionar el volumen de datos y garantiza un uso eficiente.

Actualizaciones de datos históricos

• Práctica recomendada: para actualizaciones sobre datos de tráfico o métricas similares que abarquen varios días:
  • Rango de datos: restrinja las actualizaciones para que no cubran más de 2 a 3 días de datos históricos.
  • Programación: Realice estas actualizaciones fuera de las horas punta, idealmente entre las 22:00 y las 6:00, hora estándar del este (EST). Esto minimiza el impacto en la carga del servidor y el ancho de banda durante el horario laboral habitual.

Ejemplo de uso excesivo (Evitar)

• Práctica inaceptable: un ejemplo de uso excesivo es realizar llamadas API cada 15 minutos para obtener datos de más de 40 ubicaciones, donde cada llamada recupera dos semanas de datos.
• Problema clave: Esta práctica es ineficiente ya que implica la recuperación redundante de grandes conjuntos de datos, la mayoría de los cuales no es información recién generada.

Creación de una clave API

Iniciar sesión en TMAS Seleccione la ubicación de la cadena en las opciones de ubicación Expandir Configurar Seleccione Administrar ubicaciones Seleccionar clave(s) API Seleccione Agregar clave Nombre de la clave API de entrada Marque la API WEB de Tráfico Desactivado en los permisos Haga clic en Agregar : la clave ahora aparecerá en la lista de claves.

Cómo localizar el ID de ubicación para la cadena y las ubicaciones

Para encontrar el ID de ubicación de una cadena o ubicaciones individuales: Inicie sesión en TMAS. Vaya a : Administración > Administrar ubicaciones . Se mostrará la lista de ubicaciones, incluidos los distritos, las regiones y las ubicaciones . El ID de ubicación se encuentra en la columna correspondiente junto a cada nombre de ubicación. Utilice el ID de ubicación apropiado en sus solicitudes de API.

Obtener un ID de grupo (opcional)

Para crear un grupo y recuperar su ID de grupo: Encuentra la sección de Gestión de Grupos En TMAS, la sección de Gestión de Grupos se encuentra en el menú del lado izquierdo y selecciona el grupo deseado en el menú desplegable . Editar el grupo Haga clic en el icono de edición (lápiz) junto al grupo seleccionado. Encuentra el ID del grupo El ID de grupo se muestra junto a la etiqueta de ID en la sección "Importar datos de un grupo existente" . Copie este ID de grupo para usarlo en las solicitudes de API. Este ID de grupo se puede utilizar en llamadas API para filtrar datos de ubicaciones dentro del grupo seleccionado.

Visualización de claves API

• Sólo el usuario que creó una clave API puede verla y copiarla.
• Otros usuarios verán la clave API enmascarada con asteriscos ( * ) y no podrán acceder a ella ni copiarla.
• La columna Creado por el usuario muestra el nombre del usuario que generó la clave.

Modificar o eliminar una clave API

• Para editar una clave API, haga clic en el ícono de lápiz (editar) .
• Para deshabilitar una clave API, desmarque sus permisos.
• Para eliminar una clave API, haga clic en el icono de la papelera . Nota: Las claves eliminadas no se pueden restaurar.

Eliminación de usuarios y manejo de claves API

• Si se elimina un usuario de TMAS , aparecerá un mensaje para los administradores de cadena y de usuarios .
• El mensaje ofrece dos opciones:
  1. Deshabilitar la cuenta de usuario pero mantener la clave API activa : esto permite que la clave API continúe funcionando mientras evita que el usuario inicie sesión.
  2. Eliminar la cuenta de usuario y revocar la clave API : esto elimina tanto el usuario como la clave API.

Esto garantiza que el acceso a la API permanezca controlado incluso cuando se eliminan las cuentas de usuario.

Uso de claves API para solicitudes de datos de tráfico

Las llamadas API siguen un formato de URL estandarizado, personalizable según parámetros como la empresa, la ubicación, el rango de fechas y el intervalo de datos.

Estructura de URL de API:

https://www.smssoftware.net/tmas/manTrafExp?fromDate=[1]&toDate=[2]&interval=[3]&hours=[4]&reqType=[5]&apiKey=[6]&locationId=[7]&groupId=[8]

Desglose de parámetros:

1. fromDate : Fecha de inicio ( MM/dd/YYYY-HH|mm ). La hora es opcional. Añadir "i" devuelve los datos de los días incompletos.
2. toDate : Fecha de finalización ( MM/dd/YYYY-HH|mm ).
3. intervalo : Nivel de agregación de datos:
   • 0 = Tráfico sin procesar
   • 15 = 15 minutos
   • 30 = 30 minutos
   • 60 = Por hora
   • 1440 = Diario
   • 10080 = Semanal
   • 32767 = Información del panel de ocupación
4. horas : Filtrado de horario comercial:
   • 0 = Utilizar horario comercial predefinido
   • 1 = Usar horas en fromDate
   • 2 = Horas personalizadas que abarcan varios días
5. reqType : Tipo de exportación de datos:
   • td = Datos de tráfico resumidos
   • tdd = Datos de tráfico recursivos por ubicación
   • tdl = Datos de tráfico por dispositivo (intervalo ≥ 15)
   • tds = Datos de tráfico por sensor (intervalo ≥ 15)
   • tdv = Datos de tráfico por sensor (intervalo ≥ 15): solo muestra lo que está marcado como visible en el inventario de equipos TMAS
   • tdo = Información del panel de ocupación (intervalo = 32767)
   • tdor = Datos brutos de ocupación (intervalo = 32767)
6. apiKey : su clave API única.
7. locationId : el ID de ubicación de TMAS (nivel de cadena, región, distrito o ubicación).
8. groupId (opcional): filtra datos de ubicaciones dentro de un grupo específico.

Límites de llamadas API y mejores prácticas

• Límite de rango de fechas : no puede exceder un mes.
• Límite de velocidad : una llamada cada dos segundos .
• Datos a nivel de minuto : requiere configuración Fast Push (paquete DATOS EN VIVO).

Consejos de optimización:

• Actualizaciones de datos cada hora : limite las llamadas API a las últimas tres horas para reducir la carga del sistema.
• Consultas de datos históricos : al obtener datos de varios días, limite las solicitudes a 2 o 3 días y prográmelas durante horas de menor actividad (de 10:00 p. m. a 6:00 a. m., hora estándar del este de Estados Unidos).

Ejemplos en vivo (enlace de demostración)

Preguntas frecuentes

P: ¿Puedo recuperar datos de ocupación sin especificar un rango de fechas?

• Sí, para reqType=tdo o tdor , el campo occDate devuelve la hora de la llamada.

P: ¿Cómo afecta el parámetro “horas” a las llamadas de ocupación?

• Los contadores informan continuamente, pero al aplicar el horario comercial se filtran los periodos no operativos.

P: ¿Qué significan los parámetros del nivel de ocupación?

• occLevelNow : Ocupación actual.
• occLevel-1 a occLevel-4 : Ocupación en intervalos anteriores.
• occLevelMax : Umbral de ocupación máxima.
• occLevelPct : Porcentaje de ocupación relativo al máximo.

Solución de problemas de API

Problema: la clave API no funciona

• Asegúrese de que se utilice la clave API correcta y que no haya sido revocada.
• Verifique que la clave API tenga asignados los permisos correctos.

Problema: Recepción de la respuesta "No autorizado" o "Prohibido"

• Verifique que la clave API esté asociada con la ubicación de la cadena correcta.
• Confirme que la clave API no esté vencida o deshabilitada.

Problema: Problemas de recuperación de datos

• Verifique que el rango de fechas no exceda el límite de un mes.
• Asegúrese de que el parámetro de intervalo coincida con el formato requerido.
• Si se obtienen datos en tiempo real, confirme que Fast Push esté habilitado y que exista un plan de suscripción en tiempo real válido y activo. El contador también debe tener una licencia de tiempo real asignada.

Problema: Se excedió el límite de velocidad de la API

• Las llamadas a la API deben tener una separación de al menos dos segundos .
• Reduzca la frecuencia de las llamadas a la API agrupando las solicitudes de datos.

Problema: Respuesta vacía inesperada

• Verifique nuevamente los parámetros de ID de ubicación e ID de grupo.
• Asegúrese de que haya datos disponibles para el rango de tiempo especificado.

Problema: Los datos de tráfico muestran valores de -1,0

•  -1.0 Los datos de tráfico devueltos indican que el contador no informó tráfico para este intervalo de tiempo.
• Verificar la fecha/hora solicitada y/o
• Verifique si el hardware del contador funcionaba correctamente durante este tiempo y siga el proceso de solución de problemas adecuado.

Problema: Mensaje de error: “Los parámetros de fecha proporcionados en (RANGO DE FECHAS) tienen un formato erróneo, son futuros o no tienen sentido para el sistema”.

• ✓ Asegúrate de haber ingresado una fecha válida y que el último intervalo no sea en un momento futuro.
• ✓ Asegúrese de que el rango de fechas no exceda un mes

Problema: Mensaje de error: “Los parámetros ( intervalo y/o horas) proporcionados no respetan los valores autorizados ”

• Asegúrese de que el intervalo sea válido, como se explica en la sección Uso

Problema: Mensaje de error: "Un problema subyacente de la base de datos impide que el servidor muestre datos. Comuníquese con el administrador de su base de datos".

• Verifique que el formato de su rango de fechas (DESDE Y HASTA) sea MM/DD/AAAA en la URL de llamada API
  • Incorrecto: &fromDate=6/12/18&toDate=6/12/18
  • Correcto: &fromDate=12/6/2018&toDate=12/6/2018

Problema: Mensaje de error: “La ubicación indicada no tiene ninguna cola”.

• Asegúrese de que la ubicación que ingrese esté configurada con funciones de ocupación

Esta guía ofrece una descripción general completa de la gestión de claves API en TMAS. Para obtener más ayuda, contacte con el soporte a través del chat en help.storetraffic.com . Para obtener ayuda directamente de TMAS.