enlace - Inforiego

DESCRIPCIÓN DE LA API DE ACCESO A LOS DATOS BRUTOS DE
INFORIEGO. VERSIÓN 2.2 (22 DE OCTUBRE DE 2015)
1. ANTECEDENTES
El portal de InfoRiego provee de acceso a los datos de recomendaciones de riego a los
usuarios que lo necesiten, a través de un acceso web para navegadores.
Sin embargo, cada vez más se hace necesario proveer de acceso diferente para
comunicaciones M2M que permita un tratamiento automatizado de los datos desde la
parte cliente.
2. DESCRIPCIÓN DE LOS SERVICIOS
Se ha incorporado al portal de Inforiego de una API de acceso a través de invocaciones
HTTP, con las siguientes características:
-
Se habilita la comunicación a través de los métodos GET y POST de HTTP.
-
Se requiere el envío de parámetros al servicio a través de GET o POST.
2.1
SERVICIO DE DESCARGA DE DATOS DIARIOS
Se requiere el envío de los siguientes parámetros al servicio:
1. “username”: cadena con el nombre de usuario para acceder.
2. “password”: cadena con la contraseña del usuario anterior.
3. “provincia”: código numérico con la provincia.
4. “estacion”: código numérico de la estación.
5. “fecha_ini”: cadena con formato DD/MM/YYYY con la fecha de inicio de
consulta de los datos. Es optativo. Este parámetro solamente es útil para
realizar peticiones históricas cuando se desee restringir la antigüedad de la
información a incorporar.
1
6. “fecha_fin”: cadena con formato DD/MM/YYYY con la fecha de fin de consulta
de los datos. Debe ser igual o superior a la fecha de inicio, y como máximo
366 días superior a la fecha de inicio. Es optativo. Este parámetro se
establecerá solamente si se desea realizar peticiones históricas en un
intervalo temporal que no finaliza en la actualidad.
7. “fecha_ult_modif”: cadena con formato DD/MM/YYYY con la fecha de la
última modificación que han sufrido los datos a solicitar. Esta fecha deberá
ser la última en que se hayan realizado consultas de datos al servicio.
De este modo, se garantiza que se reciben los datos más actuales o válidos
de que se dispone, sustituyéndose aquellos registros que han sido
depurados o corregidos en la validación. Esta condición es adicional a la
restricción temporal opcionalmente establecida en los anteriores parámetros
“fecha_ini” y “fecha_fin”, de forma que se entregan los registros con fecha de
modificación igual o posterior a la última descarga realizada por el usuario,
adicionalmente a los que cumplan el anterior intervalo temporal que se haya
establecido.
Comentarios sobre los datos de entrada:
-
el usuario y password restringen el acceso para que este servicio no se use de forma
indiscriminada.
-
el código de provincia y estacion son necesarios para identificar de forma unívoca
una estación.
-
Si no se especifican la fecha de inicio y de fin de los datos pedidos, se tomará como
fecha de fin la fecha actual, y como fecha de inicio la fecha de hace 366 días.
La ruta a la que se deben enviar las peticiones GET o POST es, para los datos diarios,
http://www.inforiego.org/opencms/rest/diario
2.2
SERVICIO DE DESCARGA DE DATOS HORARIOS
Se requiere el envío de los siguientes parámetros al servicio:
1. “username”: cadena con el nombre de usuario para acceder.
2. “password”: cadena con la contraseña del usuario anterior.
3. “provincia”: código numérico con la provincia.
2
4. “estacion”: código numérico de la estación.
5. “fecha_ini”: cadena con formato DD/MM/YYYY con la fecha de inicio de
consulta de los datos. Es optativo. Este parámetro solamente es útil para
realizar peticiones históricas cuando se desee restringir la antigüedad de la
información a incorporar.
6. “fecha_fin”: cadena con formato DD/MM/YYYY con la fecha de fin de consulta
de los datos. Debe ser igual o superior a la fecha de inicio, y como máximo
31 días superior a la fecha de inicio. Es optativo. Este parámetro se
establecerá solamente si se desea realizar peticiones históricas en un
intervalo temporal que no finaliza en la actualidad.
7. “fecha_ult_modif”: cadena con formato DD/MM/YYYY con la fecha de la
última modificación que han sufrido los datos a solicitar. Esta fecha deberá
ser la última en que se hayan realizado consultas de datos al servicio.
De este modo, se garantiza que se reciben los datos más actuales o válidos
de que se dispone, sustituyéndose aquellos registros que han sido
depurados o corregidos en la validación. Esta condición es adicional a la
restricción temporal opcionalmente establecida en los anteriores parámetros
“fecha_ini” y “fecha_fin”, de forma que se entregan los registros con fecha de
modificación igual o posterior a la última descarga realizada por el usuario,
adicionalmente a los que cumplan el anterior intervalo temporal que se haya
establecido.
Comentarios sobre los datos de entrada:
-
el usuario y password restringen el acceso para que este servicio no se use de forma
indiscriminada.
-
el código de provincia y estacion son necesarios para identificar de forma unívoca
una estación.
-
Si no se especifican la fecha de inicio y de fin de los datos pedidos, se tomará como
fecha de fin la fecha actual, y como fecha de inicio la fecha de hace 31 días.
La ruta a la que se deben enviar las peticiones GET o POST es, para los datos diarios,
http://www.inforiego.org/opencms/rest/horario.
3
2.3
SERVICIO DE DESCARGA DE ESTACIONES
Se requiere el envío de los siguientes parámetros al servicio:
1. “username”: cadena con el nombre de usuario para acceder.
2. “password”: cadena con la contraseña del usuario anterior.
3. “latitud”:
latitud geográfica norte en formato de grados decimales,
correspondientes a la posición geográfica para la que se solicitan datos en el
Sistema de coordenadas Geográficas WGS84. Optativo. En el caso de que
se introduzca el par de coordenadas, se devolverán los datos de la estación
más próxima a la posición dada
4. “longitud”:
longitud
geográfica
en
formato
de
grados
decimales,
correspondientes a la posición geográfica para la que se solicitan datos en el
Sistema de coordenadas Geográficas WGS84. Se indicarán valores
negativos para las coordenadas al Oeste del meridiano de Greenwich.
Optativo. En el caso de que se introduzca el par de coordenadas, se
devolverán los datos de la estación más próxima a la posición dada.
Comentarios sobre los datos de entrada:
-
el usuario y password restringen el acceso para que este servicio no se use de forma
indiscriminada.
-
el código de provincia y estacion son necesarios para identificar de forma unívoca
una estación.
-
Las coordenadas son optativas. Si no se especifica ninguna, se devuelve el listado
completo de estaciones. Si sólo se especifica una de las dos coordenadas, se
devolverá un error.
La ruta a la que se deben enviar las peticiones GET o POST es, para los datos diarios,
http://www.inforiego.org/opencms/rest/estacion
4
3. DATOS DEVUELTOS
3.1
SERVICIO DE DESCARGA DE DATOS DIARIOS
El servicio puede devolver dos tipos de datos en función de si la petición es correcta o
no:
-
Type “Text/plain”, Status HTTP 400, si ha sucedido un error. El texto devuelto informa
del error. En la actualidad, los posibles errores son:
1. "Error 001: Faltan valores de entrada": en caso de que alguno de los
parámetros no exista o sea vacío
2. "Error 002: Los campos provincia y/o estacion deben ser numericos": en caso
de que el código de provincia o de estación no sean numéricos
3. "Error 003: La fecha de inicio no puede ser mayor que la de fin": si el campo
fecha_ini es posterior a fecha_fin
4. "Error 004: Error 004: La fecha de inicio no puede ser anterior a X días desde
la fecha de fin (actualmente X es 366).
5. "Error 005: Los campos de fecha de inicio y/o fecha de fin deben tener el
formato DD/MM/YYYY": si se especifica en los campos de fecha un formato
que no corresponde con el especificado.
6. "Error 006: El usuario no pertenece a Inforiego": si se está intentando validar
con un usuario que no pertenece a Inforiego.
7. "Error 007: El usuario y/o password no son correctos": si la combinación
usuario/password no es correcta.
8. "Error 008: La ruta no es correcta": si se está enviando a una URL que no
sea correcta.
-
Type “application/json”, Status HTTP 200, si ha ido correctamente. En ese caso, se
devuelve un array JSON, en la que cada entrada es un objeto JSON compuesto por
las siguientes claves:
1. AÑO (Año)
2. DIA (Dia Juliano)
3. DIRVIENTO (Dirección predominante del viento en el día)
4. DIRVIENTOVELMAX (Dirección del viento en la velocidad máxima en el día)
5
5. ETBC (Evapotranspiración calculada por el método de Blaney-Criddle)
6. ETHARG (Evapotranspiración calculada por el método de Hargreaves)
7. ETPMON (Evapotranspiración calculada por el método de Penman-Monteith)
8. ETRAD (Evapotranspiración calculada por el método de Radiación)
9. FECHA (Fecha dentro del año)
10. HORMINHUMMAX (Hora y minuto en el que se produce la humedad relativa
máxima del día)
11. HORMINHUMMIN (Hora y minuto en el que se produce la humedad relativa
minima del día)
12. HORMINTEMPMAX (Hora y minuto en el que se produce la temperatura
máxima del día)
13. HORMINTEMPMIN (Hora y minuto en el que se produce la temperatura
minima del día)
14. HORMINVELMAX (Hora y minuto en el que se produce la velocidad máxima
del viento en el día)
15. HUMEDADD (HUMEDAD MEDIA NOCTURNA [%])
16. HUMEDADMAX (Humedad relativa máxima del día)
17. HUMEDADMEDIA (Humedad relativa media del día)
18. HUMEDADMIN (Humedad relativa minima del día)
19. IDESTACION (Identificación de Estación)
20. IDPROVINCIA (Identificación de Provincia)
21. N (NÚMERO DE HORAS DE SOL [h])
22. PEBC (Precipitación efectiva calculada por el método de Blaney-Criddle)
23. PEHARG (Precipitación efectiva calculada por el método de Hargreaves)
24. PEPMON (Precipitación efectiva calculada por el método de PenmanMonteith)
25. PERAD (Precipitación efectiva calculada por el método de Radiación)
26. PRECIPITACION (Precipitación diaria)
27. RADIACION (Radiación solar diaria)
6
28. RECORRIDO (RECORRIDO DEL VIENTO [km])
29. RMAX (RESERVA MÁXIMA [mm])
30. RN (RADIACION NETA [MJ/m2] (Radiación solar neta diaria))
31. TEMPD (TEMPERATURA MEDIA DIURNA [ºC])
32. TEMPMAX (Temperatura máxima del día)
33. TEMPMEDIA (Temperatura media del día)
34. TEMPMIN (Temperatura mínima del día)
35. VD (VELOCIDAD MEDIA DEL VIENTO DIURNO [m/s])
36. VELVIENTO (Velocidad media del viento en el día)
37. VELVIENTOMAX (Velocidad máxima del viento en el día)
38. VN (VELOCIDAD MEDIA DEL VIENTO NOCTURNO [m/s])
Los campos 5,6,7,8,22,23,24,25 son calculados, mientras que los demás son tomados
directamente de la estación.
3.2
SERVICIO DE DESCARGA DE DATOS HORARIOS
El servicio puede devolver dos tipos de datos en función de si la petición es correcta o
no:
-
Type “Text/plain”, Status HTTP 400, si ha sucedido un error. El texto devuelto informa
del error. En la actualidad, los posibles errores son:
1. "Error 001: Faltan valores de entrada": en caso de que alguno de los
parámetros no exista o sea vacío
2. "Error 002: Los campos provincia y/o estacion deben ser numericos": en caso
de que el código de provincia o de estación no sean numéricos
3. "Error 003: La fecha de inicio no puede ser mayor que la de fin": si el campo
fecha_ini es posterior a fecha_fin
4. "Error 004: Error 004: La fecha de inicio no puede ser anterior a X días desde
la fecha de fin (actualmente X es 31).
7
5. "Error 005: Los campos de fecha de inicio y/o fecha de fin deben tener el
formato DD/MM/YYYY": si se especifica en los campos de fecha un formato
que no corresponde con el especificado.
6. "Error 006: El usuario no pertenece a Inforiego": si se está intentando validar
con un usuario que no pertenece a Inforiego.
7. "Error 007: El usuario y/o password no son correctos": si la combinación
usuario/password no es correcta.
8. "Error 008: La ruta no es correcta": si se está enviando a una URL que no
sea correcta.
-
Type “application/json”, Status HTTP 200, si ha ido correctamente. En ese caso, se
devuelve un array JSON, en la que cada entrada es un objeto JSON compuesto por
las siguientes claves:
1. AÑO (Año)
2. DIA (Dia Juliano)
3. DIRVIENTO (Dirección predominante del viento en el día)
4. FECHA (Fecha dentro del año)
5. HORAMIN (Hora y minuto en formato hhmm)
6. HUMEDADMEDIA (Humedad relativa media de la hora)
7. IDESTACION (Identificación de Estación)
8. IDPROVINCIA (Identificación de Provincia)
9. PRECIPITACION (Precipitación en la hora)
10. RADIACION (Radiación en la hora)
11. TEMPMEDIA (Temperatura media de la hora)
12. VELVIENTO (Velocidad media del viento en la hora)
3.3
SERVICIO DE DESCARGA DE ESTACIONES
El servicio puede devolver dos tipos de datos en función de si la petición es correcta o
no:
8
-
Type “Text/plain”, Status HTTP 400, si ha sucedido un error. El texto devuelto informa
del error. En la actualidad, los posibles errores son:
1. "Error 001: Faltan valores de entrada": en caso de que alguno de los
parámetros no exista o sea vacío
2. "Error 006: El usuario no pertenece a Inforiego": si se está intentando validar
con un usuario que no pertenece a Inforiego.
3. "Error 007: El usuario y/o password no son correctos": si la combinación
usuario/password no es correcta.
4. "Error 008: La ruta no es correcta": si se está enviando a una URL que no
sea correcta.
5. “Error 009: Coordenadas incorrectas”: si las coordenadas enviadas no son
válidas
-
Type “application/json”, Status HTTP 200, si ha ido correctamente. En ese caso, se
devuelve un array JSON, en la que cada entrada es un objeto JSON compuesto por
las siguientes claves:
1. ALTITUD (Altitud de ubicación de la estación)
2. ESTACION (Nombre de la estación agrometeorológica)
3. ESTACIONCORTO (Abreviatura de la estación)
4. FECHAFINDATOS (fecha de fin de datos de información agrometeorológica.
Nulo, si es una estación actualmente operativa)
5. FECHAINSTAL (Fecha desde la que se dispone de datos de la estación)
6. IDESTACION (Identificación de Estación)
7. IDPROVINCIA (Identificación de Provincia)
8. LATITUD (Latitud geográfica ETRS89)
9. LONGITUD (Longitud geográfica ETRS89)
10. X_UTM (Coordenada X UTM ETRS89)
11. Y_UTM (Coordenada Y UTM ETRS89)
9