Formatos de datos

En este documento se explica cómo enviar los datos de tus gráficos a la API de Google Chart.

Índice

1. Descripción general
2. Formato de texto básico
3. Formato de texto con ajuste de escala automático
4. Formato de texto con escalamiento personalizado
5. Formato de codificación simple
6. Formato de codificación extendido
7. Escalamiento de datos y escalamiento de ejes
8. Secuencia de comandos de codificación de JavaScript

Descripción general

Los datos de casi todos los gráficos se envían con el parámetro chd. Los datos deben enviarse en uno de los siguientes formatos:

• El formato de texto básico es básicamente números de punto flotante simples del 0 al 100 inclusive. Este formato es fácil de leer y escribir a mano.
• El formato de texto con ajuste de escala automático ajusta la escala del gráfico para que se ajuste a tus datos.
• El formato de texto con escalamiento personalizado es similar al formato de texto básico, pero te permite especificar un rango personalizado mediante un segundo parámetro de URL.
• El formato de codificación simple te permite especificar valores de números enteros de 0 a 61, inclusive, codificados por un solo carácter alfanumérico. Esta codificación da como resultado la string de datos más corta de cualquiera de los formatos de datos (si algún valor es mayor que 9).
• El formato de codificación extendido te permite especificar valores enteros de 0 a 4, 095 inclusive, codificados por dos caracteres alfanuméricos. La codificación extendida es más adecuada para un gráfico con muchos datos y un gran rango de datos.

Los valores de datos se escalan para adaptarse al formato utilizado; consulta Escalamiento de datos y escalamiento de ejes para obtener una explicación de cómo se manipulan los datos a fin de que se ajusten al gráfico.

Proporcionamos un fragmento de JavaScript para codificar datos en formatos de codificación simple o de codificación extendida. Como alternativa, varios miembros del grupo de Google Charts aportaron otras bibliotecas para ayudar con el formato: busca en los archivos para encontrarlos.

Formato de texto básico

Los datos básicos con formato de texto te permiten especificar valores de punto flotante de 0 a 100, inclusive, como números. Los valores inferiores a cero se marcan como faltantes; los valores superiores a 100 se truncan como 100. La ventaja del formato de texto básico es que los valores son fáciles de leer y comprender en la URL, y las etiquetas predeterminadas del eje muestran los valores de los datos con precisión. Sin embargo, el formato de texto (ya sea simple o con parámetros personalizados) da como resultado la string de datos más larga de todos los formatos.

Si tus datos incluyen valores fuera del rango especificado para el formato de texto, puedes escalar los datos convirtiéndolos en porcentajes del valor más alto de tus datos. Como alternativa, puedes usar formato de texto con escalamiento personalizado para controlar el escalamiento por ti.

Sintaxis:

chd=t:val,val,val|val,val,val...

<data>

Cada serie consta de uno o más valores separados por comas. Separa varias series con un carácter de barra vertical (|). Los valores son números de punto flotante del 0 al 100 inclusive. Los valores menores que cero o el carácter de guion bajo ( _) se consideran valores nulos. Los valores superiores a 100 se truncan a 100.

 

Ejemplo:

Una tabla con cinco valores. El guion bajo se considera un valor nulo, el valor -30 es inferior al valor mínimo, por lo que se descarta y el valor 200 se trunca a 100.

chd=t:_,30,-30,50,80,200

Volver al principio

Formato de texto con ajuste de escala automático

Puede configurar algunos gráficos para que escalen automáticamente y se ajusten a sus datos. El gráfico se escalará de modo que el valor más grande esté en la parte superior del gráfico y el más pequeño (o cero, si todos los valores son mayores que cero) esté en la parte inferior.

Todos los valores de marcador que se muestran en el gráfico muestran sus valores reales, no sus valores ajustados.

Esta función solo está disponible con valores con formato de texto y no es compatible con todos los tipos de gráficos. Experimente con su tipo de gráfico para ver si es compatible.

Sintaxis

cht=t:val,val,val...
chds=a

Ejemplos:

chd=t:5,30,50,80,200 chds=a Ten en cuenta que no debes usar valores < 0 para los gráficos circulares.

chd=t:-5,30,-30,50,80,200 chds=a

Volver al principio

Formato de texto con escalamiento personalizado

El formato de texto con escalamiento personalizado te permite especificar números de punto flotante arbitrarios positivos o negativos, en combinación con un parámetro de escalamiento que te permite especificar un rango personalizado para tu gráfico. Este gráfico es útil cuando no deseas preocuparte por limitar los datos a un rango específico o no quieres escalar los datos de forma manual para que se ajusten bien al gráfico. Este formato ajustará la línea de cero según sea necesario. El formato de los datos es el mismo que el formato de texto básico.

Para el ajuste de escala automático, especifica chds=a.

El formato de texto (ya sea simple o con parámetros personalizados) da como resultado la string de datos más larga de todos los formatos.

Sintaxis:

El formato de texto con escalamiento personalizado requiere dos parámetros:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>

chd=t:<data>

Igual que el formato de datos sin formato: uno o más valores separados por comas por serie, varias series separadas por un carácter de barra vertical (|). El rango de valores permitidos en cada serie se especifica mediante el parámetro chds.

CHD

Un conjunto de uno o más valores mínimos y máximos permitidos para cada serie de datos, separados por comas. Debes proporcionar un máximo y un mínimo. Si proporcionas menos pares que series de datos, el último par se aplica a todas las series de datos restantes. Ten en cuenta que esto no cambia el rango del eje. Para cambiarlo, debes configurar el parámetro chxr. El rango de valores válidos es de (+/-)9.999e(+/-)199. Puedes especificar valores en estándar o en notación E.

<series_1_min>

El valor mínimo permitido en la primera serie. Los valores más bajos se marcan como faltantes.

<series_1_max>

Valor máximo permitido en la primera serie. Los valores más altos se truncan a este valor.

 

Ejemplo:

Un gráfico de barras con una escala mínima y máxima de -80 a 140. Los valores 30, -60, 50, 140 y 80 están dentro de la escala, por lo que no se truncan. Ten en cuenta que la línea cero se ajusta automáticamente, 80/(140 + 80) = 0.36 del eje Y ascendente. También ten en cuenta que el rango predeterminado del eje Y sigue siendo de 0 a 100, a pesar del parámetro chds, por lo que los valores de las etiquetas no reflejan los valores de datos reales.

chd=t:30,-60,50,140,80,-90 chds=-80,140

Volver al principio

Formato de codificación simple

El formato de codificación simple te permite especificar valores de números enteros de 0 a 61, inclusive, codificados por un solo carácter alfanumérico. Esto da como resultado la URL de string de datos más corta de todos los formatos de datos. Sin embargo, si tienes un gráfico de líneas o barras de más de 100 píxeles en el eje de datos, es posible que desees usar otro formato. Esto se debe a que, con solo 62 valores de datos admitidos, el nivel de detalle de los datos es mucho mayor que el nivel de detalle de la pantalla, y los valores estarán levemente desactivados (no mucho, pero visibles en gráficos más grandes).

Ten en cuenta que, si usas el parámetro chds con codificación simple, el tamaño del elemento de datos del gráfico no se verá afectado, pero sí los valores de los marcadores de puntos de datos.

Sintaxis:

chd=s:
  <series_1>
    ,...,
  <series_n>

<series_1>

Una string en la que cada carácter es un único dato y las series están delimitadas por una coma. Los valores individuales dentro de una serie no están delimitados. A continuación, se indican los caracteres de datos admitidos y sus valores correspondientes:

• A—Z, donde A = 0, B = 1, y así sucesivamente, a Z = 25
• a—z, donde a = 26, b = 27, y así sucesivamente, hasta z = 51
• 0(zero)—9, en el que 0 = 52 y 9 = 61
• El carácter de guion bajo (_) indica que falta un valor

Puedes usar la siguiente herramienta para codificar un solo valor o el código JavaScript para escalar y codificar una string de URL completa.

Ejemplo:

Equivale a la string codificada en texto chd=t:1,19,27,53,61,-1|12,39,57,45,51,27

<title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="Gráfico de barras apiladas con dos series y seis valores cada uno, codificación simple." src="/static/chart/chart7s. chd=s:BTb19_,Mn5tzb

Volver al principio

Formato de codificación extendido

El formato de codificación extendido te permite especificar valores enteros de 0 a 4, 095 inclusive, codificados por dos caracteres alfanuméricos. Usa una sintaxis un poco diferente a la codificación simple.

Ten en cuenta que, si usas el parámetro chds con codificación simple, el tamaño del elemento de datos del gráfico no se verá afectado, pero sí los valores de los marcadores de puntos de datos.

Sintaxis:

chd=e:
  <series_1>
    ,...,
  <series_n>

<series_1>

Una string en la que cada dos caracteres es un único dato y las series están delimitadas por una coma. Los valores individuales de una serie no están delimitados. Estos son los caracteres de codificación compatibles:

• A—Z
• a—z
• 0—9
• período (.)
• guion (-)
• Los valores faltantes se indican con un guion bajo doble (__).

A continuación, se muestra una descripción abreviada de los valores codificados:

• AA = 0, AB = 1, y así sucesivamente hasta AZ = 25
• Aa = 26, Ab = 27, y así sucesivamente hasta Az = 51
• A0 = 52, A1 = 53, y así sucesivamente hasta A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65, y así sucesivamente hasta BZ = 89
• Ba = 90, Bb = 91, y así sucesivamente hasta Bz = 115
• B0 = 116, B1 = 117, y así sucesivamente hasta B9 = 125
• B- = 126, B. = 127
• 9A = 3,904, 9B = 3,905, y así sucesivamente hasta 9Z = 3929
• 9a = 3930, 9b = 3931, y así sucesivamente hasta 9z = 3955
• 90 = 3956, 91 = 3957, y así sucesivamente hasta 99 = 3965
• 9- = 3,966, 9. = 3,967
• -A = 3968, -B = 3969, y así sucesivamente hasta -Z = 3993
• -a = 3,994, -b = 3,995, y así sucesivamente hasta -z = 4,019
• -0 = 4,020, -1 = 4,021, y así sucesivamente, con -9 = 4,029
• -- = 4,030, -. = 4,031
• .A = 4032, .B = 4033, y así sucesivamente hasta .Z = 4057
• .a = 4,058, .b = 4,059, y así sucesivamente hasta .z = 4,083
• .0 = 4,084, .1 = 4,085, y así sucesivamente hasta .9 = 4,093
• .- = 4,094, .. = 4,095

Puedes usar la siguiente herramienta para codificar un solo valor o el código JavaScript para escalar y codificar una string de URL completa.

Ejemplo:

Equivale a la string codificada en texto chd=t:90,1000,2700,3500|3968,-1,1100,250

chd=e:BaPoqM2s,-A__RMD6

Volver al principio

Escalamiento de datos y escalamiento de ejes

Los datos se escalan para adaptarse a tu gráfico, ya sea de forma explícita (cuando se usa el formato de texto con escalamiento personalizado) o implícita (todos los demás tipos). Esto significa que cada gráfico se escala para adaptarse al rango disponible del formato, no al rango real de los datos que proporcionas.

Te recomendamos escalar tus datos para que abarquen el rango completo de valores que permite tu formato y que las diferencias sean más evidentes. Para escalar tus datos, puedes escalarlos a fin de que se adapten al formato que usas o especificar explícitamente el rango de datos (es decir, usar el formato de texto con escalamiento personalizado).

Ten en cuenta que los valores de las etiquetas de los ejes se calculan en una escala completamente independiente y no tienen nada que ver con los valores de los datos, pero usan el rango predeterminado de 0 a 100. Sin embargo, puedes cambiar ese rango.

En esta sección, se describen ambos problemas.

Los datos se escalan para adaptarse al rango de formato [Todos los gráficos excepto los circulares y Venn]

Los diferentes formatos admiten diferentes rangos de valores. Tus datos se ajustan al rango de formato, de manera que el valor máximo admitido por tu formato se renderiza en la parte superior de ese eje y el valor mínimo de tu formato, en la parte inferior. En los siguientes ejemplos, se muestra el mismo valor (100) con formato de texto básico (rango de 0 a 100), texto con escalamiento personalizado (rango personalizado de 0 a 200) y formato de codificación extendido (rango 0-4,095).

Formato de texto básico	Formato de texto con escalamiento personalizado	Formato de codificación extendido
Valor: 100 (chd=t:100) Rango de formato: 0-100 El número 100 se representa como 100/100 en la escala.	Valor 100 (chd=t:100, chds=0,200) Rango de formato: 0-200 El número 100 se representa con un valor de 100/200 en la escala.	Valor: 100 (chd=e:Bk) Rango de formato: 0 a 4,095 El número 100 se representa como 100/4095 en mayor escala.

Una forma fácil de escalar tus datos para que se ajusten al gráfico es usar el formato de texto con escalamiento. Un método más complejo consiste en escalar manualmente los datos para que se ajusten al rango admitido por tu formato.

Gráficos circulares y de Venn: Con los gráficos circulares y de Venn, todos los valores son relativos entre sí, no con la escala total del gráfico.

chd=e:BkDIEs	chd=t:100,200,300 chds=0,300

El rango de etiquetas de ejes se calcula de forma independiente [barra, línea, radar, dispersión y vela]

Puedes elegir mostrar los valores de los ejes mediante el parámetro chxt. Sin embargo, es importante tener en cuenta que las etiquetas de los ejes no se calculan para reflejar los datos del gráfico, sino que la API las calcula de forma independiente o las especificas de forma explícita.

El rango predeterminado del eje es de 0 a 100, independientemente de los valores o el escalamiento de los datos. Entonces, por ejemplo, si muestras el eje y mediante etiquetas de eje predeterminadas en un gráfico que usa codificación extendida (rango 0 a 4,095), las etiquetas del eje Y leerán de 0 a 100 a menos que cambies eso explícitamente, como se explica a continuación. A continuación, te mostramos un ejemplo que muestra las etiquetas predeterminadas del eje Y en un gráfico de barras de codificación extendida con un valor de datos de 100:

chd=e:Bk (equivalente a chd=t:100)

Sin embargo, puedes especificar el rango del eje con el parámetro chxr. Si quieres que los valores de los ejes reflejen los valores de datos reales, debes especificar los valores mínimos y máximos de los ejes que coincidan con tu rango de formato. Ten en cuenta que el formato de texto básico ya tiene una escala de 0 a 100, por lo que, si usas el formato de texto básico (sin escalamiento personalizado), los valores de los ejes coincidirán con los valores de los datos de forma predeterminada. Ilustremos esto con algunos ejemplos. A continuación, se muestran tres gráficos con los mismos datos (15, 26, 51, 61), pero con diferentes formatos y distintas escalas de ejes:

Codificación simple, sin escalamiento de ejes	Codificación simple, eje ajustado	Texto básico, sin escalamiento de ejes
chd=s:Paz9   Rango de valores de codificación simple: 0-61 Rango predeterminado del eje (0-100) El rango de codificación es menor que el rango del eje de la etiqueta, por lo que las barras no corresponden al valor real en la etiqueta del eje. Sin embargo, las barras están proporcionadas entre sí de manera correcta.	chd=s:Paz9     chxr=0,0,61,10 Rango de valores de codificación simple: 0-61 Rango del eje configurado explícitamente en 0-61 El rango de codificación y el rango de ejes son iguales, por lo que las barras corresponden a su valor correcto en el eje.	chd=t:15,26,51,61   Rango de valores de formato de texto básico: 0-100 Rango predeterminado del eje (0-100) El rango de codificación y el rango de ejes son nuevamente iguales, por lo que los valores de datos precisos se muestran en el eje de forma predeterminada. Debido a que el rango de formato de texto es mayor que el rango de formato de codificación simple (100 unidades frente a 61 unidades), las barras son más pequeñas aquí que en los otros gráficos, pero todos los gráficos siguen en proporción entre sí.

Volver al principio

Secuencia de comandos de codificación JavaScript

Para usarla en la vida real, probablemente sea más fácil codificar datos de manera programática que de forma manual.

En el siguiente fragmento de JavaScript, se codifica una sola serie en codificación simple o extended y se escalan los valores de datos para que se ajusten al rango completo de esa codificación. Los datos se deben proporcionar como un array de números positivos. Cualquier valor proporcionado que no sea un número positivo se codifica como un valor faltante mediante el carácter de guion bajo (_).

var simpleEncoding =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
    }
  }

  return chartData;
}

Para codificar datos, llama a la función simpleEncode o extendedEncode y pasa el array que contiene tus datos (valueArray) y el valor máximo de tus datos (maxValue). Para crear espacio entre el valor más alto y la parte superior del gráfico, configura maxValue para que sea mayor que el número más grande del array de datos, de la siguiente manera:

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

Volver al principio