Documentación API

Introducción

En primer lugar cabe remarcar que la presente plataforma y sus contenidos están pensados para ser entendidos y aprovechados por programadores informáticos. Si no eres programador (o simplemente te inicias ahora en el mundo de las APIs) basta con que entiendas que una API abierta como ésta le permite a cualquiera obtener información registrada de la base de datos desde cualquier lugar con acceso a internet.
No estamos hablando de que se puedan "navegar" los contenidos mediante una web al uso (eso sería una de las aplicaciones posibles), sino de que se pueden solicitar a voluntad y ser entendidos por programas informáticos (como una web o una APP móvil).
Por tanto, si quieres hacer uso de nuestros datos de turismo usando la API pero no eres programador, basta con que te pongas en contacto con uno y le muestres esta página.
IMPORTANTE: Las llamadas clicables aquí descritas como ejemplo (en azul), son ejemplos reales y funcionales.

Llamada y respuesta (solicitud de la información)

La forma de solicitar la información se realiza mediante una llamada que, en nuestro caso, se puede "copiar y pegar" en la barra de direcciones de tu navegador para obtener el resultado y comprobar de forma fácil que funciona.

Las llamadas se hacen por protocolo https a la siguiente url tipo: https://api.valldalbaida.com/opendata/?r=es/{peticion}/{opciones}

...donde {peticion} es la petición base, y {opciones} son las opciones (si se necesitaran) que detallarían la petición que se solicita.
La respuesta siempre viene dada en formato JSON.

En caso de error, o de listado de contenido vacío, la respuesta devuelve un JSON de este estilo: {"error":"contenido no encontrado"}

Un JSON no es más que una estructura de datos en un formato que cualquier lenguaje de programación sabe transformar rápidamente a su tipo de variables para usar esos datos como propios.
Es, por tanto, un formato pensado para las máquinas (aunque bastante legible para el humano). No obstante, el JSON devuelto puede ser "copiado y pegado" en webs como jsoneditoronline.org para poder ver los datos de manera más amigable para nosotros.

Ejemplo en PHP: <?php $taxonomiaJSONliteral = file_get_contents ("https://api.valldalbaida.com/opendata/?r=es/taxonomia"); $taxonomiaArrayPHP = json_decode ($taxonomiaJSONliteral,true); print_r ($taxonomiaArrayPHP); ?>

Listado de todos los contenidos

Descargar de golpe todos los contenidos puede ser demasiado pesado para enviar y procesar. Sin embargo, a veces resulta útil obtener un listado de ítems para comprobar actualizaciones o para saber qué contenidos hemos solicitado y cuáles no.
Por ello ofrecemos la siguiente petición, la cual devuelve un simple array de identificadores de contenido (en adelante, 'id') en el que se incluyen todos los id de todos los contenidos existentes. https://api.valldalbaida.com/opendata/?r=es/todo

Obtener todos los datos de un contenido concreto

Con la siguiente llamada obtenemos todos los datos del contenido solicitado: · https://api.valldalbaida.com/opendata/?r=es/contenido/{id}

Sirvan de ejemplo las siguientes llamadas: · https://api.valldalbaida.com/opendata/?r=es/contenido/34 : Ontinyent · https://api.valldalbaida.com/opendata/?r=es/contenido/53 : Font Jordana · https://api.valldalbaida.com/opendata/?r=es/contenido/380 : Palacio del Marqués de Otos

NOTAS:

El campo dificultad tiene actualmente estos valores (1=fácil | 3=media | 5=difícil).
El campo horario devuelve un array de horas semanales "desde-hasta". Así, s1 equivale al "desde" de un sábado y s2 al "hasta" de ese sábado. Puede haber varias filas de horario semanales si para un día de la semana (o varios) hay más tramos desde-hasta (como por ejemplo, si hay horario de mañana y tarde).
El campo precios devuelve un JSON de precios.

Taxonomía de contenidos

Los contenidos turísticos están clasificados en 3 niveles de categorías.

Tipo 1: Es la clasificación básica. Se compone de: · Municipios (idtipo1=1) · Productos Locales (idtipo1=2) · Entidades (idtipo1=3) · Alojamientos (idtipo1=4) · Restauración (idtipo1=5) · Locales de Ocio (idtipo1=6) · Patrimonio (idtipo1=7) · Eventos (idtipo1=8) · Actividades (idtipo1=9) · Rutas (idtipo1=10) · Comercios (idtipo1=11) · Industria (idtipo1=12) · Publicaciones (idtipo1=13) · Servicios (idtipo1=14) · Turismo experiencial (idtipo1=15)

Los niveles Tipo 2 y Tipo 3 corresponden a las tipologías en forma de subcategorías. Por lo general, todos los contenidos tienen asignadas una clasificación de nivel 1 y de nivel 2. La subcategorización de tercer nivel sólo aparece en algunos tipos de contenido. Para obtener un listado de la taxonomía completa, cabe realizar la siguiente llamada, pudiendo tambien indicarle el idioma solicitado (es,ca,en): https://api.valldalbaida.com/opendata/?r=es/taxonomia https://api.valldalbaida.com/opendata/?r=ca/taxonomia https://api.valldalbaida.com/opendata/?r=en/taxonomia

Detalle sobre algunos tipos de contenido de Nivel 1:
Es importante remarcar que las definiciones aquí descritas responden a una clasificación muy particular para adaptarlas a una estructura coherente de datos que pueda diferenciarlas. Por tanto, algunos términos necesitan de una aclaración previa. Estos son:

Entidades: Suelen ser públicas o privadas: ayuntamientos, empresas de ocio, asociaciones...
Locales de ocio: Lugares donde ejercer algún evento o actividad cultural o lúdica.
Eventos y Actividades: Mentalmente pueden confundirse por el uso que le damos coloquialmente. Para nosotros la diferencia entre un tipo y otro es su frecuencia, quedando definido así:
- Un Evento es ocasional. Ocurre, como máximo, una vez al año. Tiene una fecha/hora de inicio y otra de finalización.
  Ejemplos: un concierto, una Entrada de Moros y Cristianos, un monólogo...
- Una actividad es periódica y ocurre todas las semanas. Suele tener un horario en el que podemos realizarla.
  Ejemplos: Actividad de tiro con arco los sábados por la mañana, Subida en globo los fines de semana, Encuentros o tertulias semanales en la biblioteca municipal...

Listados de tipos de contenido de Nivel 1

Cualquier listado de contenidos de tipo Nivel 1, devolverá un listado sencillo con estos campos:


            
                    · id: Valor entero. Representa el identificador del contenido.
                
· titulo: Texto. Es el título del contenido.
                
· geopos: Coordenadas. Posición del contenido.
                
· img: Dirección URL de la imagen principal del contenido.

Listado de todos los municipios

Para obtener todos los municipios de La Vall d'Albaida, basta con realizar la siguiente llamada: https://api.valldalbaida.com/opendata/?r=es/listar/municipios

Según lo comentado, devuelve un array con: id, titulo, img

Listado de los contenidos de los municipios

Por razones evidentes, salvo los municipios, el resto de contenidos de Tipo 1, se listan filtrando por municipio. La URL de la petición tiene esta forma: https://api.valldalbaida.com/opendata/?r=es/listar/municipio={id}/tipo1={idtipo1}

También podriamos obtener varios resultados de destinto contenido. Pudiendo pedir varios municipios o varios tipo1 https://api.valldalbaida.com/opendata/?r=es/listar/municipio={id,id,id...}/tipo1={idtipo1,idtipo1,idtipo1...}

Solicitamos que nos muestre los alojamientos de 3 poblaciones · https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio=15,4,34&tipo1=4 : Alojamientos de los municipios (15, 4 y 34)

Incluso pudiendo indicar todo el contenido: · https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio=todos&tipo1=4 : Todos los alojamientos de todos los municipios · https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio=15,4,34&tipo1=todos : Todos c. de los municipios (15, 4 y 34) · https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio=todos&tipo1=todos : Todos los contenidos de todos los municipios

Paginación

La paginación se encuentra presente en el listado de los contenidos. Si no se quiere utilizar paginacion solamente se devolveran 500 resultado, demorando un tiempo de entre 250 - 400ms.

Si se desea obtener mas contenidos estamos obligados a paginar el contenido. Para paginarlo hay que agregar los parametros &paginacion, &desde, $hasta https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio={id}&tipo1=4&paginacion={'rango'}&desde={'numdesde'}&hasta={'numhasta'}

Veamos un ejemplo: Mostrar de restauración, los primeros 100 contenidos del municipio 34 (ontinyent) https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio=34&tipo1=5&paginacion=rango&desde=0&hasta=100

Para obtener todos los valores solamente hay que repetir lo anterior en un bucle

Listado de NOTICIAS de un municipio

Para listar las noticias de un contenido el funcionamiento es el mismo que el anterior, pero se recomienda utilizar la paginación para filtra por fecha (fechadesde, fechahasta) o por rango (numdesde, numhasta) https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio={id}&tipo1=8&paginacion={'rango','fecha'}&desde={'numdesde',fechadesde'}&hasta={'numhasta',fechahasta'}

Donde {fechadesde} corresponde a la fecha de inicio que queramos mostrar (formato: YYY-MM-DD) y {fechahasta} la fecha fin. https://api.valldalbaida.com/opendata/?r=es/listar/contenidos&municipio=15&tipo1=13&paginacion=fecha&desde=2018-01-01&hasta=2018-12-31

Listado de Eventos

Para listar los eventos se utiliza el siguiente formato de llamada: https://api.valldalbaida.com/opendata/?r=es/eventos/ &paginacion=('rango' | 'fecha') &desde=('numero' | 'fecha' ) &hasta=('numero' | 'fecha' ) &poblacion=(idpoblacion | idp1,idp2... | todos) &subtipo1='numero' &subtipo2='numero'

Si no se especifica el valor hasta tanto si paginación es igual a fecha o a rango, la consulta estará limitada a 100 resultados.

Parámetros obligatorios:{paginacion},{desde}

Formato de respuesta si ha ido todo bién: {action:'ok', num_response:100, response:[...]} Formato de respuesta si ha fallado algo: {action:'error', num_response:0, response: 'La consulta a fallado'}

(Ejemplo de consulta)
Consulta para mostrar los 100 eventos a partir de la fecha de hoy (2024-04-26) de la población Ontinyent(34): https://api.valldalbaida.com/opendata/?r=es/eventos/&paginacion=fecha&desde=2024-04-26&poblacion=34