Interoperability with the LocClim web site

Introduction

Beside allowing users to get climatic data through their browsers, the LocClim web site allows other servers to perform interoperability transactions: other servers can directly query the LocClim service to get climate data that they can process for their own purposes.
This documents describes how to perform interoperability transactions with the LocClim web site; it first presents the transaction protocol, and describe the request and the response format. Then it provides two examples of transactions. Finally, it presents the Java code of a client that connects to the LocClim web site and request some climatic data.

Transaction

The protocol used to get climate data is the HTTP protocol; this basically means that you have to connect to the LocClim host, port 80, and send a request having the form:

   GET /sd/locclim/srv/en/locclim.getValueXML?... HTTP/1.0

and then get a response hawing the form

   HTTP 200 OK
   ...
   
   XML response

For more details about the HTTP protocol please refer to RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1.
In the future we will probably switch to different protocols, possibly based on HTTP, like SOAP, but we will maintain the protocol described in this document for backward compatibility.

Request

The request is an HTTP request having the following URL:

   http://www.fao.org/sd/locclim/srv/en/locclim.getValueXML?ARGLIST

Where ARGLIST is a list of HTTP GET request arguments:

Name	Default	Values	Description
method	mandatory	inverseDistance	inverse distance interpolation method
variable	mandatory	me	average temperature (deg C)
		min	monthly average of daily minimum temperatures (deg C)
		max	monthly average of daily maximum temperatures (deg C)
		pr	precipitation (mm - liter/sqm)
		pet	PET (mm - liter/sqm)
		sufr	sunshine fraction (% of possible)
		windsp	wind speed (m/s)
		vap	water vapor pressure (Hpa)
lon	mandatory	-180...180	longitude of the query point (dec. degrees)
lat	mandatory	-90...90	latitude of the query point (dec. degrees)
alt	mandatory if altitude correction is requested	0...10000	altitude of the query point (m)
maxDist	300 Km	10...20000	maximum distance of the neighbor stations (Km)
minStations	3	3...	minimum number of neighbor stations
maxStations	12	3...	maximum number of neighbor stations
exponent	2	0..4	exponent for inverse distance weighting
altCorrection	mandatory	true,false	apply altitude correction
altCorrMaxDist	500	10...20000	maximum distance of neighbor stations for altitude correction (Km)
altCorrMinStations	3	3...	minimum number of neighbor stations for altitude correction
altCorrMaxStations	20	3...	maximum number of neighbor stations for altitude correction

Response

The HTTP response body contains the XML element <result> containing <value>, <info>, <warning> and <error> children.

   <result>
      <value period="PERIOD">VALUE</value>
      ...
      <info code="CODE" description="DESCRIPTION" period="PERIOD"/>
      ...
      <warning code="CODE" description="DESCRIPTION" period="PERIOD"/>
      ...
   </result>

For each <value> element, VALUE is the interpolated value and PERIOD is the month for which the value is valid. <info>, <warning> and <error> elements contain optional information, warnings and error notifications given by the interpolation method. CODE contains a standard code for the given information, warning or error, DESCRIPTION is a textual description and the optional period attribute is the month to which the info/warning/error applies.

These are the valid code/description pairs for <info> elements.

Code	Description
variable	climate variable requested
numStations	Number of neighbor stations used for the interpolation
altCorrection	true iff altitude correction was requested
altCorrNumStations	Number of neighbor stations used for altitude correction
altGradient	Altitude gradient (units/Km)
avgGradient	Average gradient (units/Km)

These are the valid code/description pairs for <warning> elements.

Code	Description
minAltGradient	min. alt. gradient exceeded (units/Km)
maxAltGradient	max. alt. gradient exceeded (units/Km)

If there is an error while processing the request, the HTTP response body contains the XML element <error>.

   <error status="STATUS">
      ...
   </error>

The optional status attribute contains an encoding of the error; the valid values for STATUS are the following:

Value	Description
minStations	found less than the requested number of neighbor stations
altCorrMinStations	found less than the requested number of neighbor stations for altitude correction

Examples

The following is a request for average temperature variable at longitude 0 degrees and latitude 40 degrees, with no altitude correction and all default values.

   http://www.fao.org/sd/locclim/srv/en/locclim.getValueXML?method=inverseDistance
        &variable=me&lon=0&lat=40&alt=&maxDist=&minStations=&maxStations=&exponent=
        &altCorrection=false&altCorrMaxDist=&altCorrMinStations=&altCorrMaxStations=

The response is:

   <result>
      <info code="numStations" description="12" />
      <info code="altCorrection" description="false" />
      <value period="1">10.513362</value>
      <value period="2">11.128847</value>
      <value period="3">12.940931</value>
      <value period="4">14.85277</value>
      <value period="5">18.246775</value>
      <value period="6">20.990204</value>
      <value period="7">24.18099</value>
      <value period="8">24.772953</value>
      <value period="9">22.359606</value>
      <value period="10">18.340921</value>
      <value period="11">14.221697</value>
      <value period="12">11.3174095</value>
      <info code="variable" description="me" />
   </result>

The following is a request for average temperature variable at longitude 0 degrees and latitude 40 degrees, this time with altitude correction and all default values.

   http://www.fao.org/sd/locclim/srv/en/locclim.getValueXML?method=inverseDistance
        &variable=me&lon=0&lat=40&alt=1000&maxDist=&minStations=&maxStations=&exponent=
        &altCorrection=true&altCorrMaxDist=&altCorrMinStations=&altCorrMaxStations=

The response is:

   <result>
      <info code="numStations" description="12" />
      <info code="altCorrection" description="true" />
      <info code="altCorrNumStations" description="20" />
      <info code="altGradient" description="-9.103907597569565" period="1" />
      <info code="altGradient" description="-8.219694263168451" period="2" />
      <info code="altGradient" description="-6.975472146818723" period="3" />
      <info code="altGradient" description="-6.371315987824718" period="4" />
      <info code="altGradient" description="-5.749533376544448" period="5" />
      <info code="altGradient" description="-4.934261189806267" period="6" />
      <info code="altGradient" description="-4.689962089192269" period="7" />
      <info code="altGradient" description="-5.563872235644409" period="8" />
      <info code="altGradient" description="-6.71829422595291" period="9" />
      <info code="altGradient" description="-8.225502583523305" period="10" />
      <info code="altGradient" description="-8.710110163784416" period="11" />
      <info code="altGradient" description="-8.998702977546886" period="12" />
      <info code="avgGradient" description="-7.021719069781364" />
      <value period="1">1.8063419</value>
      <value period="2">3.2674932</value>
      <value period="3">6.269557</value>
      <value period="4">8.7592125</value>
      <value period="5">12.747893</value>
      <value period="6">16.27105</value>
      <value period="7">19.695492</value>
      <value period="8">19.451641</value>
      <value period="9">15.9341955</value>
      <value period="10">10.4740095</value>
      <value period="11">5.8913045</value>
      <value period="12">2.7110064</value>
      <info code="variable" description="me" />
   </result>

Java code

The following code implements a program that reads from the command line the LocClim host name and port, a variable code, longitude and latitude, perform an HTTP transaction and prints the data returned by LocClim.

package org.fao.locclim.utils;

import java.io.*;
import java.net.*;

public class HTTPSample
{
   private static final int BUFSIZE = 1024;

   public static void main(String args[])
   {
      if (args.length != 5)
      {
         System.err.println("usage: httpsample host port variable longitude latitude");
         System.exit(1);
      }
      String host     = args[0];
      String port     = args[1];
      String variable = args[2];
      String lon      = args[3];
      String lat      = args[4];

      try
      {
         String values = getValues(host, port,
                                  "inverseDistance", variable,
                                   lon, lat,
                                   null, null, null,
                                   null,
                                   false, null,
                                   null, null, null);
         System.out.println("VALUES:\n" + values);
      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
   }

   private static String getValues(String host, String port,
                                   String method, String variable,
                                   String lon, String lat,
                                   String maxDist, String minStations, String maxStations,
                                   String exponent,
                                   boolean altCorrection, String alt,
                                   String altCorrMaxDist, String altCorrMinStations, String altCorrMaxStations)
      throws Exception
   {
      if (maxDist            == null) maxDist            = "";
      if (minStations        == null) minStations        = "";
      if (maxStations        == null) maxStations        = "";
      if (exponent           == null) exponent           = "";
      if (alt                == null) alt                = "";
      if (altCorrMaxDist     == null) altCorrMaxDist     = "";
      if (altCorrMinStations == null) altCorrMinStations = "";
      if (altCorrMaxStations == null) altCorrMaxStations = "";

      StringBuffer file = new StringBuffer("/sd/locclim/srv/en/locclim.getValueXML");
      file.append("?method="             + method);
      file.append("&variable="           + variable);
      file.append("&lon="                + lon);
      file.append("&lat="                + lat);
      file.append("&maxDist="            + maxDist);
      file.append("&minStations="        + minStations);
      file.append("&maxStations="        + maxStations);
      file.append("&exponent="           + exponent);
      file.append("&altCorrection="      + altCorrection);
      file.append("&alt="                + alt);
      file.append("&altCorrMaxDist="     + altCorrMaxDist);
      file.append("&altCorrMinStations=" + altCorrMinStations);
      file.append("&altCorrMaxStations=" + altCorrMaxStations);

      URL url = new URL("http", host, Integer.parseInt(port), file.toString());
      HttpURLConnection conn = (HttpURLConnection)url.openConnection();
      InputStream input = conn.getInputStream();
      ByteArrayOutputStream output = new ByteArrayOutputStream();
      byte buffer[] = new byte[BUFSIZE];
      for (int nRead; (nRead = input.read(buffer, 0, BUFSIZE)) > 0; )
         output.write(buffer, 0, nRead);
      conn.disconnect();
      output.close();
      return output.toString();
   }
}

This is a sample run of the program requesting average temperature at location (0, 40):

   % java -cp . org.fao.locclim.utils.HTTPSample www.fao.org 80 me 0 40
   VALUES:
   <result>
      <info code="numStations" description="12" />
      <info code="altCorrection" description="false" />
      <value period="1">10.513362</value>
      <value period="2">11.128847</value>
      <value period="3">12.940931</value>
      <value period="4">14.85277</value>
      <value period="5">18.246775</value>
      <value period="6">20.990204</value>
      <value period="7">24.18099</value>
      <value period="8">24.772953</value>
      <value period="9">22.359606</value>
      <value period="10">18.340921</value>
      <value period="11">14.221697</value>
      <value period="12">11.3174095</value>
      <info code="variable" description="me" />
   </result>
   %