Skip to content

Foreca API

Jump to bottom Edit New page
clody69 edited this page Nov 5, 2012 · 1 revision

#Foreca API

Below there is a summary taken from the original documenation.

The API contains two main services:

  • NameFeed: name based on-line queries for forecasts, current conditions and maps
  • NaviFeed: lat/lon coordinate based on-line queries for forecasts, current conditions and maps

NameFeed

Documentation at Foreca: http://corporate.foreca.com/en/NameFeed

Base URL: http://aaltohtml5name.foreca.com/aaltohtml5-oct12a/

You can make the following queries:

  • Search for locations
  • Query a location ID for current conditions and weather forecast (hourly and daily)
  • Query a location ID for a weather map

Searching locations

You can search locations by query string. The query returns the list of matched location IDs and the available weather products at that location. Examples:

The products are:

  • cc: current condition
  • spot: hourly forecast
  • daily: daily forecast
  • satworld: past satelite maps (every 6h)
  • temp: temperature maps (current and forecast)
  • rain: rain maps (current and forecast)
  • cloud: cloud maps (current and forecast)
  • wind: wind maps (current and forecast)
  • symb: maps with weather symbols (current and forecast)

Searching by IP address and lat/lon coordinates is not currently enabled on our account.

Querying for weather conditions and forecast

For a particular location ID, you can query for the actual data of the selected weather products. Here is an example for location ID=102643743 (London, UK). We query for several products:

The response fields are explained below:

  • dt - date time stamp of the observation/forecast, for daily overview dt contains only the date part. Times are reported in local time for the requested location, except for observations (the obs tag), where dt is in local time of the observation station location.
  • station - observation station name - e.g. "Berlin Tegelhof"
  • dist - distance to the observation station from the given coordinates appended with direction to the station in English, e.g. "8 km NE"
  • p - pressure in hPa, e.g. "1012"
  • v - visibility in meters, e.g. "10000" for 10 km
  • t - temperature (default unit: Celsius)
  • tx - day maximum temperature (default unit: Celsius)
  • tn - night minimum temperature (default unit: Celsius)
  • tf - the so-called feels-like temperature (default unit: Celsius), which is the combined NOAA/NWS 'face only' wind chill index and Rothfusz heat index, which take into account the cooling and heating effects of wind and humidity
  • d - dewpoint temperature (default unit: Celsius)
  • rh - relative humidity in percentages, range from 0 to 100
  • rhx - night maximum of relative humidity in percentages, range from 0 to 100
  • rhn - day minimum of relative humidity in percentages, range from 0 to 100
  • pr - accumulated precipitation (default unit: millimeters)
  • pp - probability of precipitation in percentages, range from 0 to 100
  • tp - probability of thunder in percentages, range from 0 to 100
  • ws - 10 minute average wind speed (default unit: m/s)
  • wsx - daily maximum of the 10 minute average wind speed (default unit: m/s)
  • wsa - daily average of the 10 minute average wind speed (default unit: m/s)
  • wn - wind direction string, one of: N, NE, E, SE, S, SW, W, NW (Foreca provides a symbol set to match these)
  • c - cloudiness, in percentages, range from 0 to 100
  • ca - average cloudiness during the day in percentages, range from 0 to 100
  • s - symbol code (Foreca provides a symbol set to match these)
  • sT - symbol code as text, use lang parameter to control output language
  • rise - sun rise time in 24h clock notation in local time
  • set - sun set time in 24h clock notation in local time
  • dl - day length in minutes
  • uv - UV index based on the global ozone forecast model (1-2=low, 3-5=moderate, 6-7=high, 8-10=very high, 11+=extreme) NOTE: max 5 days forecast available

Querying for a weather map

For a particular location ID, you can query for various weather maps and different levels of zoom (1-5). The query is a two steps process:

1. Query the available map images for a particular product Here is an example for location ID=102643743 (London, UK). Several maps are available at this location: http://aaltohtml5name.foreca.com/aaltohtml5-oct12a/spot-tile.php?l=102643743&zoom=4&mapw=512&maph=512&products=sat,temp,rain,cloud,wind&windunit=KMH&tempunit=C&lang=en

2. Fetch the actual map image

http://aaltohtml5name.foreca.com/aaltohtml5-oct12a/tilecrop.php?p=sat&x=3837&y=1445&z=4&lx=256&ly=256&w=512&h=512&fmt=&l=en&t=20121101180000&m=0

NaviFeed

Documentation at Foreca: http://corporate.foreca.com/en/NaviFeed

Base URL: http://aaltohtml5navi.foreca.com/

Format Variable: "xml/aaltohtml5-oct12a"

The Foreca NaviFeed service provides weather forecasts, current conditions and mobile weather animations for any location in the world. It allows to query for:

  • current conditions and forecast (hourly and daily)
  • map images

Querying current conditions and forecast

The URL has the following syntax: http://aaltohtml5navi.foreca.com/aaltohtml5.php?lon=<longitude>&lat=<latitude>&format=xml/aaltohtml5-oct12a

where

  • lon: the longitude of the location, in decimal degrees
  • lat: the latitude of the location, in decimal degrees

As an example, the following URL queries the current conditions (by default it includes the next 3 days forecast): http://aaltohtml5navi.foreca.com/aaltohtml5.php?lon=25&lat=60&format=xml/aaltohtml5-oct12a&tempunit=C&windunit=MS

Querying for daily or hourly forecast can be achieved by adding the ftimes parameter to the query string. The format is ftimes=length/timestep/<firststep>:

  • length: length of the forecast in hours (e.g. 72 for the next 3 days). Max forecast is 10days (2400h)
  • timestep: interval between the forecast in hours. Possible values are: 1h, 3h, 6h, 24h
  • firststep: (optional) time of the first forecast. For daily forecasts (of type x/24h), it's the number of hours before midnight (the default is 11). For hourly forecast, it's the minimum number of hours from now to the first forecast (default is 0).

Examples:

  • ftimes=72/24h - Default, 1 pm, i.e. switch the date at 13:00 o'clock
  • ftimes=72/24h/11 - Same as default, switch the date at 13:00 o'clock, 11 hours before midnight
  • ftimes=72/24h/3 - Switch the date at 9 pm (3 hours before midnight)
  • ftimes=72/24h/0 - Switch the date at midnight
  • ftimes=72/24h/-6 - Show yesterday's forecast until 6 am
  • ftimes=12/1h - Default, hourly forecasts twelve hours forwards from now
  • ftimes=12/1h/0 - Same as default, hourly forecasts with first time step zero hours from now
  • ftimes=12/1h/6 - Hourly forecasts for twelve hours, starting six hours from now, i.e. ending 18 hours from now

Here are some query examples:

Additional query parameters are:

  • alt - altitude above sea level in meters, e.g. "2148" for 2148 meters. By default the altitude is estimated from the numerical weather prediction (NWP) model value for the given coordinates, which can cause errors in mountain regions. Providing the actual altitude will enable the NaviFeed forecast engine to make better temperature predictions in locations with large height variation. On level ground the benefit will be negligible.
  • tempunit - either "C" or "F" for Celsius or Fahrenheit, defaults to Celsius
  • windunit - either "MS", "KTS", "KMH", or "MPH" for m/s, knots, km/h or miles/h, defaults to m/s
  • tz - POSIX formatted time zone string for response time stamps, e.g. "UTC", or "Europe/Helsinki". If not given, time zone is approximated from coordinates, which can result in errors near time zone borders.

The response parameters are:

  • dt - time stamp of the observation/forecast, for daily overview dt contains only the date part. Unless provided in the query parameters, for NaviFeed forecasts the time zone is an approximation, which may be inaccurate near time zone borders. When using Foreca IDs (NameFeed or Batch XML) the time zone is accurate. For observations (the obs tag) the time is always in local time of the observation station.
  • station - observation station name - e.g. "Berlin Tegelhof"
  • dist - distance to the observations station from the given coordinates appended with wind direction in English, e.g. "8 km NE"
  • p - pressure in hPa, e.g. "1012"
  • v - visibility in meters, e.g. "10000" for 10 km
  • t - air temperature (default unit: Celsius)
  • tx - 24h maximum temperature (default unit: Celsius) (daily summary data)
  • tn - 24h minimum temperature (default unit: Celsius) (daily summary data)
  • tf - the so-called feels-like temperature (default unit: Celsius), which is the combined NOAA/NWS 'face only' wind chill index and Rothfusz heat index, which take into account the cooling and heating effects of wind and humidity
  • rh - relative humidity in percentages, range from 0 to 100
  • pp - probability of precipitation in percentages, range from 0 to 100
  • pr - accumulated precipitation (default unit: millimeters)
  • ws - 10 minute average wind speed (default unit: m/s)
  • wn - wind direction string, one of: N, NE, E, SE, S, SW, W, NW (Foreca provides a symbol set to match these)
  • s - symbol code (Foreca provides a symbol set to match these)

Querying for maps

Querying for the map products must follow these steps:

  1. Querying for the available weather products at a location
  2. Querying for the map URLs for the chosen products and location
  3. Querying for the actual images of the weather maps
Add a custom footer
Add a custom sidebar

Clone this wiki locally