We’re beavering away on the next version of Typeform. If you’re a v2 Beta Tester, use the tabs below to switch articles. Learn more about v2.

?

We’re beavering away on the next version of Typeform. If you’re a v2 Beta Tester, use the tabs on the left to switch articles.

API de datos de Typeform

La API de datos de Typeform te ofrece una alternativa más directa para acceder a tus resultados. En vez de acceder a tus resultados a través del panel de Typeform.com, la API te permite acceder a los datos, bajo petición y sin esfuerzos adicionales para así poder usarlos en tu propia aplicación.

¿Por qué es útil la API de datos?

Typeform ya ofrece la posibilidad de acceder a estos datos desde la plataforma mediante la exploración de la tabla de resultados y la exportación de los mismos (en formato .csv o .xls).

Pero si deseas conseguir regularmente los datos de tus resultados en tu propia aplicación u otros lugares en la web, no querrás estar haciéndolo a mano cada vez; mejor escribir código que lo haga por ti.

Con la API de datos de Typeform es posible automatizar el acceso a datos, así como la integración con cualquier otra plataforma o aplicación sin tener que entrar en tu cuenta de usuario en la plataforma.

¿Cómo utilizar la API de datos?

Para utilizar la API de datos necesitarás:

  • Tu clave de API – única y privada a ti.
  • el UID (identificador único) del typeform.

¿Cuál es mi clave de API?

Tu clave de API es una cadena aleatoria de caracteres totalmente única, algo así: 943af478d3ff3d4d760020c11af102b79c440513

Se trata de una clave que nos permite identificar que eres tú quien está accediendo a los datos, pero sin necesidad de utilizar tu login y password. Cuando envies una petición a la API de datos, esta clave básicamente nos dice que eres tú.

¿Cómo conseguir tu clave de API?

Una vez has accedido a tu panel de Typeform, visita “Mi cuenta”. En la parte inferior de la página podrás conseguir tu clave API, así como un botón para regenerarla si es necesario.

API Key [ES]

Cómo conseguir el UID de un typeform

Muy sencillo, cada vez que creas un typeform se genera una URL para identificarlo. El UID es el código que aparece en la parte final del dicha URL. Por ejemplo, para este typeform:

https://admin.typeform.com/to/AcFQ3B … El UID sería: AcFQ3B

Acceso

Ahora que ya tenemos nuestra clave de API y el UID del typeform, ya puedes crear la URL para acceder a los datos. La URL sigue esta estructura:

https://api.typeform.com/v1/form/[typeform_UID]?key=[your_API_key]
sustituir [UID] por el UID del typeform y [APIkey] por el API key

Por ejemplo:

https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd

Con esta URL ya es posible acceder a los resultados del formulario con UID Ab12C3, siempre que la API key sea válida.

Resumen del código de estado HTTP


200 – OK
Respuesta estándar para peticiones correctas.

400 – Bad Request
La solicitud contiene sintaxis errónea y no debería repetirse.

403 – Forbidden
La solicitud fue legal, pero el servidor rehúsa responderla dado que el cliente no tiene los privilegios para hacerla. En contraste a una respuesta 401 No autorizado, la autenticación no haría la diferencia.

404 – Not Found
Recurso no encontrado. Se utiliza cuando el servidor web no encuentra la página o recurso solicitado.

429 – Too Many Requests
Hay muchas conexiones desde esta dirección de internet.


Los resultados filtrados no se muestran correctamente


Comportamiento – Razón

Los resultados se muestran sin filtrar – Parámetro de filtro inválido

Formato de fecha invalido, “status”: 400 – Query con fecha inválida

Los resultados se muestran sin aplicar “offset” – Offset inválido

Sin resultados – Límite inválido

Proporciona un token válido, “status”400 – Token de resultados inválido


Filtrando parámetros de Resultados/Requests


Se muestran resultados sin filtros aplicados – Valor order_by inválido

Se muestran resultados con array incluído – Omite array en la URL con múltiples valores


Ahora podemos ver cómo refinar y ordenar tus búsquedas añadiendo parámetros a la URL de tus llamadas a la API.

Filtrar

Los parámetros que puedes utilizar para filtrar la respuesta son:

  • completed: booleano (true/false).
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&completed=true
    • Buscar por resultados completos (=true) o incompletos (=false)
    • importante: un resultado incompleto solo registrará información del dispositivo y ubicación, así como cualquier Campo Oculto que hayas utilizado. No registramos resultados parciales de typeforms.
    • Si el parámetro no tiene argumento, se obtendrán ambos tipos de respuestas, completas e incompletas.
  • since: número (tiempo Unix/Timestamp).
    • ejemplo: 
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&since=1441703930
    • Pedir resultados a partir de una fecha y hora en específico.
    • Las respuestas se muestran en orden de más antiguo a más reciente.
  • until: número (tiempo Unix/Timestamp).
    • ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&until=144170392930
    • Pedir resultados antes de una fecha y hora en específico.
    • Las respuestas se muestran en orden de más antiguo a más reciente.
  • offset: número.
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&offset=20
    • Por ejemplo, muestra los resultados exceptuando los primeros 20. Es decir, mostrar desde el #21 en adelante.
    • Especialmente útil para paginación.
  • limit: número.
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&offset=20&limit=20
    • Mostrar solo 20 results (empezando desde el resultado #21 (&offset=20)).
    • Especialmente útil para paginación.
  • token: respuesta token (string).
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&token=31f62937ba8723aa2a6198331d2ef11d
    • Identifica un resultado concreto por su token.

Ordenar

Puedes utilizar este parámetro en combinación con tus filtros (como explicamos arriba) para ordenar las respuestas usando un criterio personalizado, puedes utilizar el siguiente parámetro:

?order_by=value

Donde “value” puedes ser cualquiera de estos criterios:

  • completed:
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by=completed
    • muestra la lista de respuestas no enviadas primero, y después aquellas que sí se llegaron a enviar.
  • date_land
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by=date_land
    • Ordena resultados según fueron abiertos (acceso al typeform) por el encuestado.
    • Orden por defecto = fecha ascendente (más antigua a más nueva). Puede ser cambiado a order descendente como explicaremos más adelante.
  • date_submit
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by=date_submit
    • Ordena results según fueron enviados por el encuestado.
    • Orden por defecto = fecha ascendente (más antigua a más nueva). Puede ser cambiado a order descendente como explicaremos más adelante.

Para ordenar por fecha de acceso o de envío (date_land o date_submit) en orden descendente, tendrás que cambiar el parámetro order_by= a order_by[]= porque requerirá 2 valores.

  • date_land,desc
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by[]=date_land,desc
  • date_submit,desc
    • Ejemplo:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by[]=date_submit,desc
https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by[]=completed&order_by[]=date_submit,desc

Ejemplo de URL con varios filtros/orden:

Imagina que nuestro typeform tiene la URL http://username.typeform.com/to/AbCd99. Y vamos a pedir solamente las últimas 10 respuestas completadas.

  • Solamente queremos resultados completados, así que añadimos el parámetro completed=true.
  • Los resultados tienen que estar ordenados de más reciente a más antiguo, así que añadimos el parámetro order_by[]=date_submit,desc.
  • Solo queremos máximo 10 resultados, entonces añadimos el parámetro limit=10.
  • Y solo necesitamos añadir nuestra clave de API para que Typeform reconozca que somos nosotros haciendo la llamada. Supongamos que nuestra clave API es 1z2y3x4w5v6u7t8s9r10q11p12o13n14m15l

La URL de nuestra request a la API se verá así:

https://api.typeform.com/v1/form/AbCd99?key=1z2y3x4w5v6u7t8s9r10q11p12o13n14m15l&completed=true&order_by[]=date_submit,desc&limit=10

Recuerda: los parámetros que hemos añadido no tienen que estar en un orden particular.

Consultar una lista de todos tus Typeforms

Puedes consultar una lista de tus typeforms y sus UIDs haciendo una llamada a la siguiente URL, utilizando tu clave API privada:

https://api.typeform.com/v1/forms?key=YOUR_API_KEY

Payload de ejemplo


{

“http_status”:200,

“stats”:{

“responses”:{

“showing”:5,

“total”:5,

“completed”:2

}

},

“questions”:[

{

“id”:”textfield_37671344″,

“question”:”What is your name?”,

“field_id”:37671344

},

{

“id”:”date_37962697″,

“question”:”What date were you born?”,

“field_id”:37962697

},

{

“id”:”email_37962684″,

“question”:”What’s your email address?”,

“field_id”:37962684

},

{

“id”:”textarea_37671420″,

“question”:”Please tell us a little about yourself.”,

“field_id”:37671420

},

{

“id”:”website_37962927″,

“question”:”Please add your website URL:”,

“field_id”:37962927

},

{

“id”:”statement_37671505″,

“question”:”Thanks !”,

“field_id”:37671505

},

{

“id”:”yesno_37977952″,

“question”:”Are you a Game of Thrones fan?”,

“field_id”:37977952

},

{

“id”:”terms_37962909″,

“question”:”Please read and confirm you accept our terms and conditions:”,

“field_id”:37962909

},

{

“id”:”dropdown_37671567″,

“question”:”Who’s your favourite Game of Thrones character?”,

“field_id”:37671567

},

{

“id”:”listimage_37967229_choice”,

“question”:”Which of these characters annoys you the most?”,

“field_id”:37967229

},

{

“id”:”group_37977292″,

“question”:”Rate the deviousness of these Game of Thrones characters:”,

“field_id”:37977292

},

{

“id”:”rating_37977395″,

“question”:”Tyrion Lannister”,

“field_id”:37977395,

“group”:”group_37977292″

},

{

“id”:”rating_37977403″,

“question”:”Littlefinger”,

“field_id”:37977403,

“group”:”group_37977292″

},

{

“id”:”rating_37977401″,

“question”:”Walder Frey”,

“field_id”:37977401,

“group”:”group_37977292″

},

{

“id”:”rating_37977400″,

“question”:”Margaery Tyrell”,

“field_id”:37977400,

“group”:”group_37977292″

},

{

“id”:”list_37963973_choice”,

“question”:”Who is going to sit on the Iron Throne at the end of the series?”,

“field_id”:37963973

},

{

“id”:”list_37963973_other”,

“question”:”Who is going to sit on the Iron Throne at the end of the series?”,

“field_id”:37963973

},

{

“id”:”opinionscale_37979723″,

“question”:”How much better would the series be without the Dragons?”,

“field_id”:37979723

},

{

“id”:”fileupload_37980234″,

“question”:”Please upload a file here:”,

“field_id”:37980234

},

{

“id”:”number_37980157″,

“question”:”How many major characters do you think have died in Game of Thrones?”,

“field_id”:37980157

},

{

“id”:”payment_37962979_price”,

“question”:”The total price is: “,

“field_id”:37962979

},

{

“id”:”payment_37962979_last4″,

“question”:”The total price is: “,

“field_id”:37962979

},

{

“id”:”payment_37962979_name”,

“question”:”The total price is: “,

“field_id”:37962979

},

{

“id”:”payment_37962979_success”,

“question”:”The total price is: “,

“field_id”:37962979

}

],

“responses”:[

{

“completed”:”0″,

“token”:”bbf6b7a9eaf65804f94c05d4568fc62f”,

“metadata”:{

“browser”:”default”,

“platform”:”other”,

“date_land”:”2016-11-29 16:36:11″,

“date_submit”:”0000-00-00 00:00:00″,

“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,

“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,

“network_id”:”7d19966666″

},

“hidden”:[

],

“answers”:{

}

},

{

“completed”:”1″,

“token”:”c0d44787a6bc86de34adf81976a624fb”,

“metadata”:{

“browser”:”default”,

“platform”:”other”,

“date_land”:”2016-11-29 16:59:16″,

“date_submit”:”2016-11-29 16:59:51″,

“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,

“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,

“network_id”:”7d19966666″

},

“hidden”:[

],

“answers”:{

“textfield_37671344”:”https:\/\/ssl.solutions.six.se\/fsb.public\/site\/public\/fondtorg\/funddetail_bank.page?magic=(cc(idAGL)) “,

“textarea_37671420”:”https:\/\/ssl.solutions.six.se\/fsb.public\/site\/public\/fondtorg\/funddetail_bank.page?magic=(cc(idAGL)) “,

“dropdown_37671567″:”Dropdown 1”

}

},

{

“completed”:”1″,

“token”:”7bac73ad0818db745da00479c12de987″,

“metadata”:{

“browser”:”default”,

“platform”:”other”,

“date_land”:”2016-12-05 09:59:01″,

“date_submit”:”2016-12-05 10:01:31″,

“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,

“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,

“network_id”:”7d19966666″

},

“hidden”:[

],

“answers”:{

“textfield_37671344″:”Sean”,

“date_37962697″:”2000-01-01”,

“email_37962684″:”test@typeform.com”,

“textarea_37671420″:”Here’s some information about me!”,

“website_37962927″:”http:\/\/test.com”,

“yesno_37977952″:”1”,

“terms_37962909″:”1”,

“dropdown_37671567″:”Sandor Clegane”,

“listimage_37967229_choice”:”Jon Snow”,

“rating_37977395″:”10”,

“rating_37977403″:”10”,

“rating_37977401″:”9”,

“rating_37977400″:”9”,

“list_37963973_choice”:”Daenerys Targaryen”,

“opinionscale_37979723″:”6”,

“fileupload_37980234″:”https:\/\/api.typeform.com\/v0\/form\/A8TcDI\/fields\/37980234\/blob\/c82215948b78-Cersei.jpg?key=664527c4c8bf2c6be6484b813e23e4f8ae066666”,

“number_37980157″:”37”,

“payment_37962979_price”:”0″

}

},

{

“completed”:”0″,

“token”:”b86db5dc48f6d021ee751e8f68595063″,

“metadata”:{

“browser”:”default”,

“platform”:”other”,

“date_land”:”2016-12-05 10:01:38″,

“date_submit”:”0000-00-00 00:00:00″,

“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,

“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,

“network_id”:”7d19966666″

},

“hidden”:[

],

“answers”:{

}

},

{

“completed”:”0″,

“token”:”5df20a5aebea4e0edfb4d2d8670b4a4b”,

“metadata”:{

“browser”:”default”,

“platform”:”other”,

“date_land”:”2016-12-05 10:13:40″

}

¿Te pareció útil este artículo?
¡Gracias!