Info ío - API - Documentación


Introducción


Info ío – API permite el acceso a la información sobre inversión publicitaria a través de un servicio web REST, utilizando por defecto peticiones y respuestas en formato JSON


El punto de acceso base del servicio es http://infoio.infoadex.es/infoioapi/v{version}, donde {version} se refiere a la versión del API a la que se desea acceder.


En la documentación del API se incluyen las características particulares de cada recurso del servicio para cada versión, así como un listado con los cambios incluidos en cada versión. Actualmente sólo se encuentra publicada la versión v1_0 del API como versión inicial.


Autenticación


Info ío – API utiliza el framework OAuth2 para la autenticación.


Para acceder desde su aplicación al API de Info ío lo primero que deberá contar es con una clave de acceso al API para su aplicación, además de un usuario y contraseña válidos para el acceso a Info ío. El usuario y contraseña puede ser un usuario existente para el acceso a la versión de escritorio de Info ío. Si desea más información de cómo obtener estos datos póngase en contacto con nosotros.


Para iniciar el proceso de autenticación deberá realizar un POST al punto de acceso /Users/getAuthToken con los siguientes parámetros:


Parámetro Tipo Descripción
ApiKey String Clave de acceso al API proporcionada para su aplicación
UserName String El nombre de usuario que va a acceder al servicio
PassWord String Contraseña del usuario. La contraseña deberá ser codificada en Base64
        
                {
                    "ApiKey": “a-p-i-k-e-y",
                    "UserName": "u-s-e-r-n-a-m-e",
                    "PassWord": "b-a-s-e-6-4-e-n-c-o-d-e-d-p-a-s-s-w-o-r-d"
                }
            
        

La respuesta del servidor será similar a la que se indica a continuación:

        
                {
                    "Token": "oncywUdqa+GIMgnVFZQ3IZuKEfcYivywurxtc7nKkkzhOFL71bKpwXcMVzxyohtW",
                    "Expires": "2019/04/17 11:18:25",
                    "Exception": null
                }
                
        

Una vez que obtenga la respuesta deberá conservar el token de acceso para incluirlo en el Authorization Header en las peticiones que vaya a realizar al servicio.


En aquellas peticiones en las que no se haya incluido un token de acceso válido, o éste haya expirado, se obtendrá un código de respuesta HTTP 401 – Unauthorized


Errores


En aquellas peticiones en las que no se haya incluido un token de acceso válido, o éste haya expirado, se obtendrá un código de respuesta HTTP 401 - Unauthorized


Para el resto de errores, todas las funciones del servicio web incluyen una estructura de datos <Exception>, que en caso de error, contendrán la información de la excepción y el origen de ésta.


        
                {
                    "Token": null,
                    "Expires": null,
                    "Exception": {
                        "Source": "Users/getAuthToken",
                        "Message": "Not found"
                    }
                }
            
        

Es recomendable que el código de la aplicación que acceda al API maneje adecuadamente todas las posibles excepciones que puedan producirse en la comunicación con el servicio.


Recursos


Recurso Petición Descripción
/Query/execute POST Ejecuta una consulta en Info ío con las variables, fechas y valores de filtro indicados en la petición
/Query/getFilterValues POST Realiza un filtro dentro para la variable y cadena buscada, devolviendo los valores coincidentes
/Query/getPonderations POST Devuelve la lista de ponderaciones existentes para el usuario que está conectado al servicio
/Query/getQuery POST Devuelve el diseño guardado de una consulta, selección de registros, o informe periódico guardado relacionado con el usuario conectado al servicio
/Query/getVariables POST Devuelve el listado de variables disponibles en el sistema que pueden ser utilizadas para la selección de registros y consultas a los datos de inversión

A continuación se detallan las estructuras de datos utiizadas en las peticiones y respuestas a los distintos recursos del API. Para evitar la repetición innecesaria de información en la documentación, la definición de las estructuras utilizadas en varios recursos puede encontrarse en el apartado Estructuras de datos comunes


/Query/execute


Ejecuta una consulta en Info ío con las variables, fechas y valores de filtro indicados en la petición.


Request

La petición requiere un único argumento obligatorio con los siguientes atributos:


Atributo Descripción
Name String opcional con el nombre de la consulta
Options Estructura de datos con las opciones generales de configuración de la consulta (ver definición)
Columns Array opcional con las variables a incluir como columnas en la consulta. Cada columna estará representada por una estructura de datos de tipo <Variable> (ver definición)
Rows Array con las variables a incluir como filas de la consulta. Cada fila estará representada por una estructura de datos de tipo <Variable> (ver definición)
Filter Array opcional con las variables y valores de filtro que deberán utilizarse para restringir el resultado de la consulta. Cada elemento del filtro estará representado por una estructura de datos de tipo <Filter> (ver definición). Para obtener un listado de valores de filtro válidos puede ser necesario hacer uso primero de la función /Query/getFilterValues

Response

La petición devuelve el contenido de la consulta realizada a Info ío en una estructura de datos con los siguientes atributos:


Atributo Descripción
Columns Array con el listado de columnas devueltas por la consulta. El listado de columnas permite reducir el tamaño de la respuesta asignando una clave a cada columna, de manera que pueda ser posteriormente traducido el nombre de cada columna con el encabezado oportuno según cada variable utilizada. Cada elemento del array estará representado por una estructura de tipo <ColumnInfo> con los siguientes atributos hijos:
Atributo Descripción
ColumnName Clave asignada a la columna
ColumnHeader Encabezado de la columna correspondiente con la variable utilizada en la consulta
Data Array de datos en formato tabla con el listado de columnas y valores para cada registro devuelto por la consulta. En función del diseño utilizado en la consulta, cada registro de datos contendrá un número de columnas acorde con el diseño. Para cada columna, se devolverán dos valores: uno para la clave asignada a la columna (ver atributo Columns más arriba) y el valor devuelto para la fila/columna
Exception Tipo <Exception> (ver definición)
        
                {
                    "Columns": [
                        {
                            "ColumnName": "c0",
                            "ColumnHeader": "SOPORTE"
                        },
                        {
                            "ColumnName": "c1",
                            "ColumnHeader": "MARCA"
                        },
                        {
                            "ColumnName": "c2",
                            "ColumnHeader": "MODELO"
                        },
                        {
                            "ColumnName": "c3",
                            "ColumnHeader": "ANUNCIANTE"
                        },
                        {
                            "ColumnName": "c4",
                            "ColumnHeader": "INVERSION_EUROS_ENERO"
                        },
                        {
                            "ColumnName": "c5",
                            "ColumnHeader": "INVERSION_EUROS_FEBRERO"
                        }
                        ],
                    "Data": [
                        {
                            "c0": "20minutos.es",
                            "c1": "20 MINUTOS",
                            "c2": "TIEMPOYTEMPERATURA.ES",
                            "c3": "20 MINUTOS EDITORIAL, S.L.",
                            "c6": 0,
                            "c7": 0
                        },
                        {
                            "c0": "20minutos.es",
                            "c1": "ABANCA",
                            "c2": "CUENTA CLARA",
                            "c3": "ABANCA CORPORACION BANCARIA, S.A.",
                            "c6": 11028,
                            "c7": 0
                        },
                        {
                            "c0": "youtube.com",
                            "c1": "WUG",
                            "c2": "CHICLES",
                            "c3": "WUG FUNCTIONAL GUMS, S.L.",
                            "c6": 0,
                            "c7": 645
                        }
                        ],
                    "Exception": null
                }
            
        

/Query/getFilterValues


Realiza un filtro para la variable y cadena buscada, devolviendo los valores coincidentes en un array.


En función de la variable utilizada en el filtro, el array de resultados podrá contener información de otras variables relacionadas con la variable filtrada. Estos valores deberán utilizarse en posteriores peticiones a Info ío (/Query/execute) del mismo modo para asegurar la coherencia de los resultados obtenidos. En concreto, las variables que devuelven información de otras variables relacionadas son:


  • Grupo Marcas / Modelos: los valores de filtro muestran los datos del modelo/s filtrado/s más los datos de sus marcas asociadas
  • Grupo Marcas / Marcas: los valores de filtro muestran los datos de la marca/s filtrada/s más los datos de sus anunciantes y sectores relacionados
  • Grupo Marcas / Productos: los valores de filtro muestran los datos del producto/s filtrado/s más los datos de sus categorías y sectores relacionados.
  • Grupo Marcas / Categorías: los valores de filtro muestran los datos de la/s categoría/s filtradas/s más los datos de los sectores relacionados.
  • Grupo Medios / Soportes: los valores de filtro muestran los datos del soporte/s filtrados más los datos del medio relacionado.

Request

La petición requiere un único argumento obligatorio con los siguientes atributos:


Atributo Descripción
FilterValue String con el valor por el que se desea filtrar. El filtrado se realiza buscando valores que contengan la cadena indicada sin distinción entre mayúsculas y minúsculas
Group Grupo al que pertenece la variable. En Info ío se consideran los siguientes grupos de variables:
  • Grupo Marcas
  • Grupo Medios
  • CINE
  • DR, RV, SS
  • EXTERIOR
  • Internet
  • TV, RD
  • Otras variables comunes
VariableName Nombre de la variable. El listado de variables y grupos disponibles puede obtenerse desde /Query/getVariables
Response

La respuesta vendrá representada por una estructura de dato de tipo <Filter> (ver definición)


        
                {
                    "FilterValues": [
                        "[CAMPAÑAS LIMPIEZA Y ECOLOGIA][CAMPAÑAS INTERES PUBLICO][SERVICIOS PUBLICOS Y PRIVADOS]",
                        "[CREMAS LIMPIADORAS DE BELLEZA][TRATAMIENTOS DE BELLEZA FACIALES][BELLEZA E HIGIENE]",
                        "[LIMPIA MAQUINAS LAVAVAJILLAS][LAVAVAJILLAS][LIMPIEZA]",
                        "[LIMPIACRISTALES][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIADORES A VAPOR][PEQUEÑOS ELECTRODOMESTICOS][HOGAR]",
                        "[LIMPIADORES ANTICAL][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIADORES BAÑO][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIADORES COCINA][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIADORES DENTADURA POSTIZA][HIGIENE DE LA BOCA][BELLEZA E HIGIENE]",
                        "[LIMPIADORES MULTIUSOS][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIADORES SUELOS][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIADORES VITROCERAMICA][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIAINODOROS][LIMPIADORES][LIMPIEZA]",
                        "[LIMPIEZA Y CONSERVACION][ACCESORIOS Y MANTENIMIEN.AUTOMOCION][AUTOMOCION]",
                        "[LIMPIEZA Y MANTENIMIENTO][PISCINAS Y EQUIPAMIENTO][DEPORTES Y TIEMPO LIBRE]",
                        "[LIMPIEZA/MANTENIMIENTO][SERVICIOS VARIOS][SERVICIOS PUBLICOS Y PRIVADOS]",
                        "[LINEA DE LIMPIEZA][LINEA DE LIMPIEZA][LIMPIEZA]",
                        "[LINEA LIMPIADORES][LIMPIADORES][LIMPIEZA]",
                        "[LINEA UTILES DE LIMPIEZA][UTILES LIMPIEZA][LIMPIEZA]",
                        "[LINEA VARIOS LIMPIEZA][VARIOS LIMPIEZA][LIMPIEZA]",
                        "[OTROS LIMPIADORES][LIMPIADORES][LIMPIEZA]",
                        "[OTROS UTILES DE LIMPIEZA][UTILES LIMPIEZA][LIMPIEZA]",
                        "[OTROS VARIOS LIMPIEZA][VARIOS LIMPIEZA][LIMPIEZA]"
                        ],
                    "Exception": null,
                    "Group": "Grupo Marcas",
                    "VariableName": "Producto"
                }
            
        

/Query/getPonderations


Devuelve la lista de ponderaciones existentes para el usuario que está conectado al servicio. Debe tenerse en cuenta que el API sólo trabaja con ponderaciones guardadas en Info ío. El API no realizará cálculos con ponderaciones que el cliente pueda tener alojadas en local.


Request

La petición no requiere ningún argumento salvo los necesarios en el encabezado.


Response

Array con el listado de ponderaciones existentes para el usuario. Cada elemento del array está representado por una estructura de tipo <Ponderation> con los siguientes atributos:


Atributo Descripción
Id Valor numérico que indica el código de la ponderación a utilizar
Description String con el nombre de la ponderación
ShowAllValues Valor booleano para indicar si la consulta debe devolver sólo los valores ponderados (valor False), o tanto los valores ponderados como los valores sin ponderar (valor True)
Exception Tipo <Exception> (ver definición)

        
                [
                    {
                        "Id": 1,
                        "Description": "Pond. Anual 2007-2019(2019 con valores 2018) (22.02.2019) ",
                        "ShowAllValues": false,
                        "Exception": null
                    },
                    {
                        "Id": 2,
                        "Description": "Ponderación Trimestral 2007-2019 (22.02.2019) ",
                        "ShowAllValues": false,
                        "Exception": null
                    }
                ]
            
        

/Query/getQuery


Devuelve el diseño guardado de una consulta, selección de registros o informe periódico guardado relacionado con el usuario conectado al servicio. El API permite recuperar de este modo consultas o informes almacenados desde la versión de escritorio de la aplicación. La versión actual del API no contiene funcionalidad para realizar el guardado de las consultas / informes desde el propio API.


Request

La petición requiere un único argumento obligatorio con los siguientes atributos:


Atributo Descripción
QueryType String con el tipo de objeto a recuperar. Se aceptan tres valores posibles (respetando mayúsculas):
  • CONSULTA
  • INFORME PERIODICO
  • SELECCION REGISTROS
QueryName String con el nombre del objeto a recuperar

Response

Estructura de datos con el contenido del objeto recuperado:


Atributo Descripción
Name String con el nombre del objeto recuperado
Options Estructura de datos con las opciones generales de configuración de la consulta (ver definición)
Columns Array con las variables incluidas como columnas en la consulta. Cada columna estará representada por una estructura de dato de tipo <Variable> (ver definición)
Rows Array con las variables incluidas como filas en la consulta. Cada fila estará representada por una estructura de dato de tipo <Variable> (ver definición)
Filter Array con las variables y valores de filtro utilizadas en la consulta. Cada elemento del filtro estará representado por una estructura de dato de tipo <Filter> (ver definición). Para obtener un listado de valores de filtro válidos puede ser necesario hacer uso primero de la función /Query/getFilterValues
Exception Tipo <Exception> (ver definición)

La estructura devuelta por esta función puede ser reutilizada para realizar la posterior petición de información a través de la función /Query/execute


/Query/getVariables


Devuelve el listado de variables disponibles en el sistema que pueden ser utilizadas para la selección de registros y consultas a los datos de inversión.


Request

La petición no requiere ningún argumento salvo los necesarios en el encabezado.


Response

Array con el listado de variables disponibles en el sistema. Cada elemento del array está representado por una estructura de tipo <Variable> con los siguientes atributos


Atributo Descripción
Group Grupo de la variable. En Info ío se consideran los siguientes grupos de variables:
  • Grupo Marcas
  • Grupo Medios
  • CINE
  • DR, RV, SS
  • EXTERIOR
  • Internet
  • TV, RD
  • Otras variables comunes
VariableName String con el nombre de la variable
Exception Tipo <Exception> (ver definición)

Estructuras de datos comunes


Para mayor claridad, evitando la repetición innecesaria de información en la documentación del API, se listan a continuación aquellas estructuras de datos utilizadas en varios de los recursos listados anteriormente.


<Exception>


Atributo Tipo de dato Descripción
Source String Origen interno de la excepción
Message String Mensaje de error

Para aquellas estructuras de datos que incluyen el tipo <Exception>, y que son utilizadas tanto como parte de peticiones como de respuestas del servicio, la información relacionada con la excepción deberá omitirse en la petición, y si se incluye será ignorada.


<Filter>


Atributo Tipo de dato Descripción
Group String Grupo de la variable. En Info ío se consideran los siguientes grupos de variables:
  • Grupo Marcas
  • Grupo Medios
  • CINE
  • DR, RV, SS
  • EXTERIOR
  • Internet
  • TV, RD
  • Otras variables comunes
VariableName String Nombre de la variable. El listado de variables y grupos disponibles puede obtenerse desde /Query/getVariables
FilterValues String array Array de Strings con los valores de filtro a aplicar en la variable. Para obtener un listado de los valores posibles de filtro de una variable puede ser necesario la consulta previa a la función /Query/getFilterValues
Exception <Exception> Ver definición

<Measures>


Atributo Tipo de dato Descripción
Inserciones bool Valor booleano para indicar si se utilizará la medida de inserciones en la consulta
InvEstudioInfoadex bool Valor booleano para indicar si se utilizará la medida del estudio de inversiones de InfoAdex
InvTarifa bool Valor booleano para indicar si se utilizará la medida de inversión a tarifa en la consulta
Ocupacion bool Valor booleano para indicar si se utilizará la medida de Ocupación en la consulta

<Period>


Atributo Tipo de dato Descripción
Description String Origen interno de la excepción
Date_From Date Fecha desde la que se considerará el periodo. La fecha debe formatearse según el formato ISO 8601 (YYYY-MM-DD).
Date_To Date Fecha hasta la que se considerará el periodo. La fecha debe formatearse según el formato ISO 8601 (YYYY-MM-DD).

<Ponderation>


Atributo Tipo de dato Descripción
Id int Valor numérico que indica el código de la ponderación a utilizar. Para determinar el código de la ponderación a utilizar deberá consultarse primero la función /Query/getPonderations
Description String String opcional con el nombre de la ponderación
ShowAllValues bool Valor booleano para indicar si la consulta debe devolver sólo los valores ponderados (valor False), o tanto los valores ponderados como los valores sin ponderar (valor True)
Exception <Exception> Ver definición

<QueryOptions>


Atributo Tipo de dato Descripción
Consolidated bool Valor booleano para determinar si la consulta se hará sobre información consolidada o información detalle
Date_From Date Fecha desde la que se devolverá la información. La fecha debe formatearse según el formato ISO 8601 (YYYY-MM-DD).
Date_To Date Fecha hasta la que se devolverá la información. La fecha debe formatearse según el formato ISO 8601 (YYYY-MM-DD).
Measures <Measures> Estructura de datos con la indicación de las medidas que deberán incluirse en la consulta (ver definición)
Ponderation <Ponderation> Estructura de datos, opcional, con los datos de la ponderación a utilizar en la consulta (ver definición)
Periods <Period> [] Array de peridos adicionales, opcional, utilizados en la consulta. Cada elemento del array está representado por una estructura de datos de tipo <Period> (ver definición)
Exception <Exception> Ver definición

<Variable>


Atributo Tipo de dato Descripción
Group String Grupo de la variable. En Info ío se consideran los siguientes grupos de variables:
  • Grupo Marcas
  • Grupo Medios
  • CINE
  • DR, RV, SS
  • EXTERIOR
  • Internet
  • TV, RD
  • Otras variables comunes
VariableName String Nombre de la variable. El listado de variables y grupos disponibles puede obtenerse desde /Query/getVariables
Exception <Exception> Ver definición

Clientes de ejemplo


Puede encontrar aplicaciones de ejemplo acerca del uso del API en el repositorio público de GitHub creado a tal efecto


Dispone de dos aplicaciones de ejemplo en distintos lenguajes:

  •  .NET - Aplicación de escritorio de Windows en C#
  •  Python - Aplicación de consola en Python