Windguru JSON API, version 1.2.12, 14.4.2011
============================================

This is a very simple description of the API, hope you can understand it :)


URL of the API:
---------------

https://www.windguru.cz/int/jsonapi.php

http is not alowed, https must be used (for user's security)

All parameters are sent via GET or POST method, example:
https://www.windguru.cz/int/jsonapi.php?username=SOMEUSER&password=SAMOEPASSWORD&client=iphone&q=forecast..

If you use both POST and GET, POST variables have higher priority and will overwrite GET variables

Required parameters for all requests:
-------------------------------------

client (client identification, for example 'iphone')
q (query, see list below)

Optional paramaters for all requests
-------------------------------------

username (username of windguru user)
password (password of windguru user)
preview (enter preview=1 to see the reply structure in same format like examples below instead of JSON, good for exploring the API...)

Different queries (q) may have other required and/or optional parameters, see below.


QUERIES (q parameters)
----------------------
(see examples only for structure of the server reply, in real they will be JSON encoded) 


1) model_status

returns current status of all models on windguru, reply example:

Array   ---> (keys of the array are IDs of the model)
(
    [3] => Array
        (
            [id_model] => 3                     ---> ID of the model domain, (see the list of models below)
            [model_name] => GFS                 ---> label of the model
            [model] => gfs                      ---> abbreviation of the model domain which I use internally, it is better to use the ID (id_model)
            [initstamp] => 1212314400            
            [initdate] => 2008-06-01 12:00:00   ---> date of the model cycle in UTC
        )

    [15] => Array
        (
            [id_model] => 15
            [model_name] => WRF 9km
            [model] => mm5uk
            [initstamp] => 1192831200
            [initdate] => 2007-10-20 00:00:00
        )
...

list of currently used models:

 id_model | model_name | model  | note
----------+------------+--------+------ 
        3 | GFS        | gfs	| GFS (global)
        4 | NAM 12 km  | nam    | NAM 12 km (Northern America)
       10 | NWW3       | nww3	| NWW3 wave model 
       14 | WRF 27 km  | mm5eu  | WRF 27 km (Europe) 
       19 | MM5 9 km   | mm5czo | MM5 9 km (CZ)
       21 | WRF 9 km   | wrfeuh | WRF 9 km (Europe)
       22 | WRF 9 km   | wrfcah | WRF 9 km (Canary)
       23 | WRF 9 km   | wrfegh | WRF 9 km (Egypt)
       24 | HRW 5 km   | hiarw  | HRW 5 km (Hawaii)
       29 | WRF 12 km  | wrfarg | WRF 12 km (Argentina)		   
       30 | HRWe 4 km  | eastnmm| HRWe 4 km (US east)
       31 | HRWw 4 km  | westnmm| HRWw 4 km (US west)
       32 | WRF 3 km   | wrfczs | WRF 3 km (CZ)

       26 | HRWe 4 km  | eastarw| HRWe 4 km (US east)          [DEPRECATED]
       27 | HRWw 4 km  | westarw| HRWw 4 km (US west)          [DEPRECATED]
                                                                          
       12 | WRF 9km    | mm5cz  | WRF 9 km (CZ)                [DISCONTINUED]
       15 | WRF 9km    | mm5uk  | WRF 9 km (UK/FR)             [DISCONTINUED]
       16 | WRF 9km    | wrfpt  | WRF 9 km (PT/ES/IT/GR)       [DISCONTINUED]
       18 | MM5 27 km  | mm5euo | MM5 27 km (Europe)		   [DISCONTINUED]
       20 | MM5 9 km   | mm5uko | MM5 9 km (UK/FR)			   [DISCONTINUED]
                                                                             
       
As we are adding new WRF models over time you can expect this to change... 

Notes:

Always use id_model in order to identify models (model_name can change...)

Models that are marked deprecated: ID 26,27 (HRW for US) - they were replaced by other versions: ID 26=>30,27=>31
q=model_status will still show IDs 26,27 but with data replaced by 30 resp. 31.
q=forecast (see below) for IDs 26,27 will keep working but will contain forecast data from model 30 resp. 31
q=spot (see below) will not include IDs 26,27 in "models" array anymore

2) spot

returns short info about a spot

REQUIRED parameters:
id_spot ... ID of the spot

reply example:

Array
(
    [id_spot] => 43			 ---> id of the spot
    [spotname] => Tarifa     ---> spot name
    [country] => Spain       ---> country
    [lat] => 36				 ---> latitude (as decimal number)
    [lon] => -5.65           ---> longitude (as decimal number)
    [alt] => 0               ---> altitude of the spot (meters above sea level)
    [tz] => Europe/Madrid    ---> timezone of the spot
    [gmt_hour_offset] => 2   ---> current local time hour offset from GMT/UTC
    [sunrise] => 08:15       ---> sunrise in local time
    [sunset] => 20:13        ---> sunset in local time
    [sst] => 25       	 	 ---> sea surface temperature in celsius (if available)
    [models] => Array        ---> array of model IDs available for this spot
        (                    
            [0] => 16        
            [1] => 14        
            [2] => 18        
            [3] => 3         
            [4] => 10        
        )

)


3) forecast

returns forecast for a spot and also include the same info as the above 'spot' query

REQUIRED parameters:
id_spot ... ID of the spot
id_model ... ID of the model, or 'all' which will get forecasts from all available models for this spot, or more IDs separated by comma 

Only PRO users can view WRF and MM5 models

reply example:

Array
(
    [id_spot] => 43
    [spotname] => Tarifa
    [country] => Spain
    [lat] => 36
    [lon] => -5.65
    [alt] => 0               
    [tz] => Europe/Madrid
    [gmt_hour_offset] => 2
    [sunrise] => 08:15
    [sunset] => 20:13
    [sst] => 25       	 	
    [models] => Array
        (
            [0] => 16
            [1] => 14
            [2] => 18
            [3] => 3
            [4] => 10
        )

    [forecast] => Array                        ---> array of forecasts
        (
            [3] => Array                       ---> id of the model
                (                                 
                    [initstamp] => 1212314400  ---> unix timestamp of the model cycle
                    [APCP] => Array            ---> forecast parameter (detailed description below...)
                        (
                            [0] => 			   ---> values for each forecast hour
                            [3] => 0
                            [6] => 0
                            [9] => 0
                            [12] => 0
                            [15] => 0
                            [18] => 0
							...
                        )

                    [initdate] => 2008-06-01 12:00:00   ---> model initialization time in UTC
                    [model_name] => GFS                 ---> model label
                )

        )

)
							
Desciption of forecast variables:
                                                                    
APCP        ... precipitation for last 3 hours [mm](GFS,NAM)
APCP1       ... precipitation for last 1 hour [mm] (WRF,MM5,HRW)
TCDC        ... total cloud cover [%] (GFS,NAM,WRF,MM5,HRW)
TMP         ... temperature in 2 meters above surface [deg. Celsius] (GFS,NAM,WRF,MM5,HRW)
WINDSPD     ... windspeed in 10 meters above surface [knots] (GFS,NAM,WRF,MM5,HRW)
GUST        ... wind gusts [knots] (GFS,NAM,WRF,MM5)
WINDDIR     ... wind direction in degrees, 0 = north, 90 = east, 180 south ... (GFS,NAM,WRF,MM5,HRW)
WINDIRNAME  ... wind direction as english abbr. (GFS,NAM,WRF,MM5,HRW)  
HTSGW       ... significant wave height [meters] (NWW3)
DIRPW       ... direction of the dominant waves in degrees, 0 = north, 90 = east, 180 south ... (NWW3)
WAVEDIRNAME ... wave direction as english abbr. (NWW3)
PERPW       ... peak wave period [seconds] (NWW3)
TMPE        ... temperature in 2 meters with correction to real altitude of the spot [deg. Celsius] (GFS,NAM,HRW,some WRF)
FLHGT       ... freezing level height [meters] (GFS,NAM,some WRF)
SLP         ... sea level pressure [hPa] (GFS,NAM,HRW,some WRF)
HCDC        ... high cloud cover [%] (GFS,NAM,WRF)
MCDC        ... middle cloud cover [%] (GFS,NAM,WRF)
LCDC        ... low cloud cover [%] (GFS,NAM,WRF)
RH          ... relative humidity at 2 meters above surface [%] (GFS,NAM,HRW,some WRF)


3) spots

returns list of spots

other paramaters (optional):

you can specify following filters:
id_country           ... ID of country - filter spots by specified country
id_region            ... ID of region - filter spots by specified region
since_id             ... ID of the spot - returns only spots with ID higher than 'since_id'
since_date           ... date in 'YYYY-MM-DD' or 'YYYY-MM-DD HH:ii:ss' format - returns only spots added since 'since_date'
since_date_modified  ... date in 'YYYY-MM-DD' or 'YYYY-MM-DD HH:ii:ss' format - returns only spots modified since 'since_date_modified'
id_user				 ... ID of user, shows spots of this user. By default (without this parameter) the query will list official spots and custom spots of logged in user
						 to list only official spots use id_user=169 (ID of "windguru" user is 169)

you can also list spots in given distance from specified spot or lat/lon point:
radius            ... distance in kilometers from the reference spot or lat/lon point (max. distance = 1000), if you set this you must also set one of the next 2 parameters:
ref_id_spot       ... ID of the reference spot which is the center of the radius
ref_latlon        ... 'lat,lon' of the center of the radius, lat and lon are in degrees as decimal numbers, separated by comma, example: ref_latlon=56.12,-110.31
	example: "radius=100&ref_latlon=56.12,-110.31" - list spots that are max 100 km from point at latitude 56.12 and longiitude -110.31
	example: "radius=50&ref_id_spot=53" - list spots that are max 50 km from spot ID=53

(AND condition is used if more filters are specified)

options:
opt                  ... entering 'simple' into this will show only simple list of spots - see below

reply example: 

Array
(
    [count] => 3057                         ---> number of spots in this list
    [spots] => Array                        ---> array of spots
        (
            [0] => Array
                (
                    [id_spot] => 9451       ---> ID of the spot
                    [spotname] => Algiers   ---> spot name (without country)
                    [country] => Algeria    ---> country 
                    [id_user] => 169        ---> ID of the user, user windguru (official spots) are ID = 169
                )

            [1] => Array
                (
                    [id_spot] => 52075
                    [spotname] => Antigua
                    [country] => Antigua and Barbuda
                    [id_user] => 169
                )

            [2] => Array
                (
                    [id_spot] => 64141
                    [spotname] => Bariloche
                    [country] => Argentina
                    [id_user] => 169
                )
....


example of simple list (with opt=simple):

Array
(
    [count] => 3057
    [spots] => Array                         
        (
            [9451] => Algeria - Algiers
            [52075] => Antigua and Barbuda - Antigua
            [64141] => Argentina - Bariloche
            [261] => Argentina - Buenos Aires
            [8165] => Argentina - Claromeco
            [91085] => Argentina - Hinojo Grande
            [5687] => Argentina - Chascomus
            [90107] => Argentina - Chasico
            [74124] => Argentina - Isla Escondida
            [9441] => Argentina - La Balandra
            [80503] => Argentina - Lago Puelo
...
the array of spots show full names of the spot (COUNTRY - SPOTNAME), keys are the spot IDs    

In case you are using the 'radius' parameter to list spots within radius of a point, the reply will also contain 'distance' variable at each spot 
(distance in kilometers from the center point), latitude (lat) and longitude (lon) and the list is sorted by the distance instead of spotname, example:

Array
(
    [count] => 31
    [spots] => Array
        (
            [0] => Array
                (
                    [id_spot] => 53
                    [spotname] => Maui (north shore)
                    [country] => United States
                    [distance] => 0.000
                    [lat] => 20.935
                    [lon] => -156.36
                    [id_user] => 169
                )

            [1] => Array
                (
                    [id_spot] => 208798
                    [spotname] => Ho'okipa
                    [country] => United States
                    [distance] => 1.179
                    [lat] => 20.93
                    [lon] => -156.35
                    [id_user] => 169
                )

            [2] => Array
                (
                    [id_spot] => 208799
                    [spotname] => Kuau
                    [country] => United States
                    [distance] => 1.670
                    [lat] => 20.92
                    [lon] => -156.36
                    [id_user] => 169
                )
...


4) f_spots

shows favourite spots of current user, same output format like 'spots' 

5) c_spots

shows custom spots of current user, same output format like 'spots' 

6) fc_spots

shows favourite and custom spots of current user, same output format like 'spots' 

for all 4) - 6) queries you can use the opt=simple parameter too


7) search_spots

search for spots by name and/or nickname of specified user, output is sorted by 'COUNTRY - SPOTNAME'

REQUIRED parameters:
search ... search pattern for the spot, at least 2 characters (same syntax as spot search on windguru website, * wildcard possible)
nickname ... search pattern for the nickname of user, with this you can only search spots of specified user
(not both 'search' and 'nickname' are required, but at least one of them)

other optional parameters:
limit ... max. number of spots in the result (results per page), default 20, maximum is 1000
page ... if there are more spots found then 'limit', use this to list through more pages, default 1 
opt ... entering 'simple' into this will show only simple list of spots, same like in queries 3) - 6)

the server reply is again same as for queries 3) - 6) except it also includes 'nickname' variable for custom spots (indication of the owner of the spot)


8) geo_regions

returns list of georegions as array, keys are their IDs 

example reply: 

Array
(
    [2] => Africa
    [142] => Asia
    [53] => Australia and New Zealand
    [29] => Caribbean
    [13] => Central America
    [150] => Europe
    [21] => Northern America
    [9] => Oceania
    [5] => South America
)

hmm... :) this will be the same for a long time ;)

9) countries

returns list of countries as array, keys are their IDs 

other paramaters (optional):
id_georegion ... ID of geo region, only show countries of that geo region
with_spots   ... '1' if you only want to return countries with existing spots

example reply:

Array
(
    [8] => Albania
    [20] => Andorra
    [40] => Austria
    [112] => Belarus
    [56] => Belgium
    [70] => Bosnia and Herzegovina
    [100] => Bulgaria
    [191] => Croatia
    [196] => Cyprus
    [203] => Czech Republic
    [208] => Denmark
    [233] => Estonia
    [234] => Faroe Islands
    [246] => Finland
    [250] => France
...


10) regions

returns list of regions as array, keys are their IDs 

other paramaters (optional):
id_country ... ID of country, show regions of that country
with_spots   ... '1' if you only want to return regions with existing spots

Array
(
    [61] => Aquitaine
    [50] => Basse Normandie I
    [51] => Basse Normandie II
    [63] => Camargue & Bouches du Rhône
    [65] => Côte d'Azur
    [49] => Haute Normandie
    [58] => Charente Maritime
    [60] => Ile de Ré
    [59] => Ile d'Oleron
...


11) add_f_spot

adds spot to user's favourites, does not work for anonymous users

REQUIRED parameters:
id_spot ... ID of the spot

if adding the spot was succesfull server replies:

Array
(
    [return] => OK
    [message] => Favourite spot added
)

or (if spot already exists in users favourites):

Array
(
    [return] => OK
    [message] => Spot already in favourites
)


12) remove_f_spot

removes spot from user's favourites, does not work for anonymous users

REQUIRED parameters:
id_spot ... ID of the spot

if removing the spot was succesfull server replies:

Array
(
    [return] => OK
    [message] => Spot removed from favourites
)

or (if spot was not in user's favourites at all):

Array
(
    [return] => OK
    [message] => Spot not in favourites
)


13) list_status

returns times of last update to country list, region list, geo region list

Array   
(
    [countries_update] => Array
        (
            [timestamp] => 1212314400           ---> unix timestamp of last update 
            [datetime] => 2008-06-01 12:00:00   ---> date and time of the last update (UTC)
        )

	[regions_update] => Array
        (
            [timestamp] => 1212314400           ---> unix timestamp of last update 
            [datetime] => 2008-06-01 12:00:00   ---> date and time of the last update (UTC)
        )

	[geo_regions_update] => Array
        (
            [timestamp] => 1212314400           ---> unix timestamp of last update 
            [datetime] => 2008-06-01 12:00:00   ---> date and time of the last update (UTC)
        )


14) user

returns info about user

Array
(
    [id_user] => 1
    [username] => vh
    [id_country] => 203
    [wind_units] => msd		---> 'ms' = m/s, 'msd' = m/s with 0.1 precision, 'knots' = knots, 'kmh' = km/h, 'bft' = Bft, 'mph' = mph
    [temp_units] => c		---> 'c' = celsius, 'f' = fahrenheit
    [wave_units] => m		---> 'm' = meters, 'ft' = feet
    [pro] => 1				---> 1 = yes, 0 = no
    [no_ads] => 0			---> 1 = ads turned off, 0 = ads enabled 
    [view_hours_from] => 3  ---> visible hours in forecast - from
    [view_hours_to] => 23	---> visible hours in forecast - to
)

for anonymous users this query just returns default values:

Array
(
    [id_user] => 0
    [username] => 
    [id_country] => 0
    [wind_units] => knots
    [temp_units] => c
    [wave_units] => m
    [pro] => 0
    [no_ads] => 0
    [view_hours_from] => 3
    [view_hours_to] => 22
)

15) forecast_latlon

(only available for PRO users)

returns forecast for given latitude and longitude, result is the same format as 'forecast' query explained earlier
this query might be more heavy on windguru meteodata server so please doublecheck that it is not used unnecessarily... 

REQUIRED parameters:
lat ... latitude of the spot (degrees as decimal number, eg. 12.34)
lon ... longitude of the spot (degrees as decimal number, eg. 56.78)
id_model ... ID of the model, or 'all' which will get forecasts from all available models for this location, or more IDs separated by comma

Recommended value for id_model is 'all' which will return forecasts from all models available for given coordinates. Wave model forecast is not available.

reply example:

note that here the info about spot contains a little unusual info:
'id_spot' is 0
'spotname' is simply composed from spot coordinates / altitude
'id_country' is 0 (we do not detect country of the place) 
timezone info should be correct (autodetected using service from www.geonames.org)

Array
(
    [id_spot] => 0
    [spotname] => Lat: 50.12, Lon: 14.45, Alt: 244 m
    [country] => 
    [id_country] => 0
    [lat] => 50.12
    [lon] => 14.45
    [alt] => 244
    [tz] => Europe/Prague
    [gmt_hour_offset] => 2
    [sunrise] => 05:25
    [sunset] => 20:32
    [sst] => 13
    [forecast] => Array
        (
            [3] => Array
                (
                    [initstamp] => 1269342000
                    [RH] => Array
                        (
                            [0] => 58
                            [3] => 59
                            [6] => 84
                            [9] => 92
                            ...

                    [initdate] => 2008-06-01 12:00:00
                    [model_name] => GFS
                )

        )

)

16) version

returns api version

Array
(
    [api_version] => 1.2.10
)


17) app_version

returns version of the app for given client and url for download (only if available for given client)

REQUIRED parameters:
client ... client identification

Array
(
    [app_version] => 1.0
    [app_url] => http://www.windguru.cz/downloads/winmobile/windguru_winmobile_1.0.cab
)



API Errors:
-----------

In case of an error server reply will look like this

Array
(
    [return] => error
    [error_id] => 5
    [error_message] => Missing query [q]
)

List of errors:
1, Username does not exist
2, Wrong password
3, Wrong spot ID [id_spot]
4, Wrong model ID [id_model]
5, Missing query [q]
6, Missing username or password
7, Unknown query [q]
8, HTTP requests not alowed, use HTTPS only
9, Wrong client
10, Search pattern must have at least 2 characters
11, Wrong search
12, Only available for Windguru PRO users
13, Not available for anonymous users
14, Unspecified error
15, Missing lat/lon
16, Wrong spot radius filter
17, Not enough permission
18, Wrong API login
19, Unknown username


