Formato de respuesta

Descripción general

Los endpoints de informes (/v1/reports/*) usan un formato de respuesta especializado basado en arrays para optimizar el rendimiento y reducir el tamaño del payload. Esta guía explica cómo interpretar estas respuestas.

Otros endpoints como /v1/org/* y /v1/prompts/* usan estructuras de objetos JSON estándar que están documentadas en la referencia de OpenAPI.

Estructura de la respuesta de los informes

Todos los endpoints de informes devuelven los datos en este formato optimizado:

{
  "data": [
    {
      "dimensions": ["example.com", "/some/path", "2023-10-01"],
      "metrics": [10, 0.05]
    },
    {
      "dimensions": ["another-site.com", "/different/path", "2023-10-02"],
      "metrics": [15, 0.08]
    }
  ],
  "info": {
    "query": {
      "date_interval": "day",
      "dimensions": ["hostname", "path", "date"],
      "filters": [
        {
          "field": "hostname",
          "operator": "in",
          "value": ["example.com", "another-site.com"]
        }
      ],
      "metrics": ["count", "share_of_voice"]
    },
    "total_rows": 200
  }
}

Interpretar los datos de los informes

Correspondencia de posiciones en los arrays

La clave para entender las respuestas de los informes es que las posiciones de los arrays corresponden exactamente a los parámetros de tu solicitud:

Array de dimensiones

Los valores corresponden al orden de las dimensiones en tu solicitud:

dimensions[0] → Primera dimensión solicitada (hostname)
dimensions[1] → Segunda dimensión solicitada (path)
dimensions[2] → Tercera dimensión solicitada (date)

Array de métricas

Los valores corresponden al orden de las métricas en tu solicitud:

metrics[0] → Primera métrica solicitada (count)
metrics[1] → Segunda métrica solicitada (share_of_voice)

Ejemplo de correspondencia

Para el primer objeto de resultado anterior:

Nombre de host: dimensions[0] = “example.com”
Ruta: dimensions[1] = “/some/path”
Fecha: dimensions[2] = “2023-10-01”
Recuento: metrics[0] = 10
Share of Voice: metrics[1] = 0.05

Objeto info

El objeto info proporciona metadatos sobre tu consulta:

Campo	Descripción
`query`	Los parámetros exactos de tu solicitud devueltos tal cual
`total_rows`	Número total de resultados disponibles (útil para la paginación)

Trabajar con las respuestas de los informes

Procesar los datos

Ejemplo de conversión del formato de arrays a una estructura de objetos más tradicional:

// Process report response
const processReportData = (response) => {
  const { dimensions: dimNames, metrics: metricNames } = response.info.query;
  
  return response.data.map(row => {
    const result = {};
    
    // Map dimensions
    dimNames.forEach((name, index) => {
      result[name] = row.dimensions[index];
    });
    
    // Map metrics
    metricNames.forEach((name, index) => {
      result[name] = row.metrics[index];
    });
    
    return result;
  });
};

// Usage
const processedData = processReportData(apiResponse);
// Result: [{ hostname: "example.com", path: "/some/path", date: "2023-10-01", count: 10, share_of_voice: 0.05 }]

def process_report_data(response):
    """Convert array-based response to dict format"""
    query_info = response['info']['query']
    dim_names = query_info['dimensions']
    metric_names = query_info['metrics']

    results = []
    for row in response['data']:
        result = {}

        # Map dimensions
        for i, name in enumerate(dim_names):
            result[name] = row['dimensions'][i]

        # Map metrics
        for i, name in enumerate(metric_names):
            result[name] = row['metrics'][i]

        results.append(result)

    return results

# Usage
processed_data = process_report_data(api_response)
# Result: [{"hostname": "example.com", "path": "/some/path", "date": "2023-10-01", "count": 10, "share_of_voice": 0.05}]

function processReportData($response) {
    $queryInfo = $response['info']['query'];
    $dimNames = $queryInfo['dimensions'];
    $metricNames = $queryInfo['metrics'];

    $results = [];
    foreach ($response['data'] as $row) {
        $result = [];

        // Map dimensions
        foreach ($dimNames as $index => $name) {
            $result[$name] = $row['dimensions'][$index];
        }

        // Map metrics
        foreach ($metricNames as $index => $name) {
            $result[$name] = $row['metrics'][$index];
        }

        $results[] = $result;
    }

    return $results;
}

Prácticas recomendadas

Usa siempre el objeto info.query para entender la estructura de los datos de tu respuesta
Procesa las respuestas mediante programación usando los ejemplos de correspondencia anteriores en lugar de codificar de forma fija las posiciones de los arrays
Gestiona la paginación usando el campo total_rows para determinar si hay más datos disponibles
Supervisa los encabezados de límite de solicitudes para evitar alcanzar los límites de la API
Valida que los parámetros de tu solicitud coincidan con las dimensiones y métricas esperadas para tu caso de uso

¿Necesitas ayuda?

Si encuentras formatos de respuesta inesperados o necesitas aclaraciones sobre respuestas de informes específicos, contacta con nuestro equipo de soporte para obtener ayuda.

Descripción general

SDKs

Integraciones

Agentes

Organización

Categorías

Prompts

Bases de conocimiento

OpenAI Ads

Respuestas

Volúmenes de prompts

Informes

Optimización de contenido

Formato de respuesta

Descripción general

Estructura de la respuesta de los informes

Interpretar los datos de los informes

Correspondencia de posiciones en los arrays

Array de dimensiones

Array de métricas

Ejemplo de correspondencia

Objeto info

Trabajar con las respuestas de los informes

Procesar los datos

Prácticas recomendadas

¿Necesitas ayuda?

​Descripción general

​Estructura de la respuesta de los informes

​Interpretar los datos de los informes

​Correspondencia de posiciones en los arrays

​Array de dimensiones

​Array de métricas

​Ejemplo de correspondencia

​Objeto info

​Trabajar con las respuestas de los informes

​Procesar los datos

​Prácticas recomendadas

​¿Necesitas ayuda?

Descripción general

Estructura de la respuesta de los informes

Interpretar los datos de los informes

Correspondencia de posiciones en los arrays

Array de dimensiones

Array de métricas

Ejemplo de correspondencia

Objeto info

Trabajar con las respuestas de los informes

Procesar los datos

Prácticas recomendadas

¿Necesitas ayuda?