Wiki - Yeqzids/7timer-issues GitHub Wiki
Last updated: 2023 March 29
Introduction
7Timer! is a meteorological forecast service developed to assist astronomical observation. It was inspired by Attilla Danko's Clear Sky Chart which provides a similar service for North America. 7Timer! is based on the products generated by the NCEP GFS model. The service was developed and managed by Quanzhi Ye with the help of many, and as of April 2023, it has been mainly maintained by Dimitrios Kechagias in consultation with Quanzhi. 7Timer! has been running since July 2005.
Obtaining forecast data
7Timer! provides four products, each has different emphases:
| Product | CIVIL | CIVIL Light | Two-Week-Overview | ASTRO | METEO |
|---|---|---|---|---|---|
| Description | 7-day 3-hourly general forecast | simplified 7-day forecast | 2-week overlook | 72-hour forecast for astronomical observations | 7-day forecast with detailed meteorological info |
| Cloud Cover | Y | Y | Y | Y | |
| Cloud Profile | Y | ||||
| Lifted Index | Y | Y | Y | Y | |
| 2m Temperature | Y | Y | Y | Y | |
| Max 2m Temp | Y | Y | |||
| Min 2m Temp | Y | Y | |||
| 2m Relative Humidity | Y | Y | Y | Y | |
| R.H. Profile | Y | ||||
| 10m Wind | Y | Y | Y | Y | Y |
| Wind Profile | Y | ||||
| Precipitation Type | Y | Y | Y | Y | Y |
| Precipitation Amount | Y | Y | |||
| Astro Seeing | Y | ||||
| Atmos Transparency | Y | ||||
| MSL Pressure | Y | ||||
| Snow Depth | Y | ||||
| Weather Type | Y | Y |
Forecast can be obtained by visiting the website or by accessing the application programming interface (API). 7Timer! provides weather maps as well as location-based forecasts for every grid point on the Earth at a resolution of 10 km. The location-based forecasts are encapsulated in a PNG image. Users are welcome to put these images on their websites.
Machine-readable API
7Timer! provides forecast data in XML and JSON format. The API is accessed by a URL with a form similar to
http://www.7timer.info/bin/api.pl?lon=113.17&lat=23.09&product=astro&output=xml
where the parameters are:
| Parameter | Description |
|---|---|
| lon | [deg, float] WGS84 coordinates of the site. |
| lat | [deg, float] WGS84 coordinates of the site. |
| ac | [km, int] Altitude Correction, only used in ASTRO forecast. Should be 0 (default), 2 or 7. |
| lang | [str] Language. Used in CIVIL, CIVIL Light, TWO, and ASTRO. Permissible values: en. |
| unit | [str] Unit used. Permissible values: metric, british. (At some point "british" will be replaced by "imperial".) |
| output | [str] Output format. Permissible values: xml, json. |
| tzshift | [int] Adjustment of timezone. Permissible values: 0, 1 or -1. |
Definition of graphic display and API output
CIVIL and CIVIL Light
| Parameter | Definition | Icon | API output (-9999 = invalid) | Meaning |
|---|---|---|---|---|
| cloudcover | Cloud Cover | 1 | 0%-6% | |
| 2 | 6%-19% | |||
| 3 | 19%-31% | |||
| 4 | 31%-44% | |||
| 5 | 44%-56% | |||
| 6 | 56%-69% | |||
| 7 | 69%-81% | |||
| 8 | 81%-94% | |||
| 9 | 94%-100% | |||
| lifted_index | Lifted Index | -10 | Below -7 | |
| -6 | -7 to -5 | |||
| -4 | -5 to -3 | |||
| -1 | -3 to 0 | |||
| 2 | 0 to 4 | |||
| 6 | 4 to 8 | |||
| 10 | 8 to 11 | |||
| 15 | Over 11 | |||
| prec_type | Precipitation Type | snow | Snow | |
| rain | Rain | |||
| frzr | Freezing rain | |||
| icep | Ice pellets | |||
| none | None | |||
| prec_amount | Precipitation Rate | 0 | None | |
| 1 | 0-0.25mm/hr | |||
| 2 | 0.25-1mm/hr | |||
| 3 | 1-4mm/hr | |||
| 4 | 4-10mm/hr | |||
| 5 | 10-16mm/hr | |||
| 6 | 16-30mm/hr | |||
| 7 | 30-50mm/hr | |||
| 8 | 50-75mm/hr | |||
| 9 | Over 75mm/hr | |||
| temp2m | 2m Temperature | - | 2m temperature in Censius | |
| rh2m | 2m Relative Humidity | - | 2m Relative Humidity | |
| wind10m_direction | 10m Wind Direction | N, NE, E, SE, S, SW, W, NW | Classical compass winds | |
| wind10m_speed | 10m Wind Speed | 1 | Below 0.3m/s (calm) | |
| 2 | 0.3-3.4m/s (light) | |||
| 3 | 3.4-8.0m/s (moderate) | |||
| 4 | 8.0-10.8m/s (fresh) | |||
| 5 | 10.8-17.2m/s (strong) | |||
| 6 | 17.2-24.5m/s (gale) | |||
| 7 | 24.5-32.6m/s (storm) | |||
| 8 | Over 32.6m/s (hurricane) | |||
| weather | Weather Type |  |
clearday, clearnight | Total cloud cover less than 20% |
 |
pcloudyday, pcloudynight | Total cloud cover between 20%-60% | ||
 |
mcloudyday, mcloudynight | Total cloud cover between 60%-80% | ||
 |
cloudyday, cloudynight | Total cloud cover over over 80% | ||
 |
humidday, humidnight | Relative humidity over 90% with total cloud cover less than 60% | ||
 |
lightrainday, lightrainnight | Precipitation rate less than 4mm/hr with total cloud cover more than 80% | ||
 |
oshowerday, oshowernight | Precipitation rate less than 4mm/hr with total cloud cover between 60%-80% | ||
 |
ishowerday, ishowernight | Precipitation rate less than 4mm/hr with total cloud cover less than 60% | ||
 |
lightsnowday, lightsnownight | Precipitation rate less than 4mm/hr | ||
 |
rainday, rainnight | Precipitation rate over 4mm/hr | ||
 |
snowday, snownight | Precipitation rate over 4mm/hr | ||
 |
rainsnowday, rainsnownight | Precipitation type to be ice pellets or freezing rain | ||
 |
tsday, tsnight | Lifted Index less than -5 with precipitation rate below 4mm/hr | ||
 |
tsrainday, tsrainnight | Lifted Index less than -5 with precipitation rate over 4mm/hr |
Two-Week-Overview
| Parameter | Definition | Icon | API output (-9999 = invalid) | Meaning |
|---|---|---|---|---|
| cloudcover | Cloud Cover | 1 | 0%-6% | |
| 2 | 6%-19% | |||
| 3 | 19%-31% | |||
| 4 | 31%-44% | |||
| 5 | 44%-56% | |||
| 6 | 56%-69% | |||
| 7 | 69%-81% | |||
| 8 | 81%-94% | |||
| 9 | 94%-100% | |||
| lifted_index | Lifted Index | -10 | Below -7 | |
| -6 | -7 to -5 | |||
| -4 | -5 to -3 | |||
| -1 | -3 to 0 | |||
| 2 | 0 to 4 | |||
| 6 | 4 to 8 | |||
| 10 | 8 to 11 | |||
| 15 | Over 11 | |||
| temp2m_max | 2m Max Temperature | - | 2m max temperature in Censius | |
| temp2m_min | 2m Min Temperature | - | 2m min temperature in Censius | |
| rh2m | 2m Relative Humidity | - | 2m Relative Humidity | |
| wind10m_direction | 10m Wind Direction | N, NE, E, SE, S, SW, W, NW | Classical compass winds | |
| wind10m_speed | 10m Wind Speed | 1 | Below 0.3m/s (calm) | |
| 2 | 0.3-3.4m/s (light) | |||
| 3 | 3.4-8.0m/s (moderate) | |||
| 4 | 8.0-10.8m/s (fresh) | |||
| 5 | 10.8-17.2m/s (strong) | |||
| 6 | 17.2-24.5m/s (gale) | |||
| 7 | 24.5-32.6m/s (storm) | |||
| 8 | Over 32.6m/s (hurricane) | |||
| weather | Weather Type |  |
clear | Total cloud cover less than 20% |
 |
pcloudy | Total cloud cover between 20%-80% | ||
 |
cloudy | Total cloud cover over 80% | ||
 |
rain | Rain | ||
 |
snow | Snow | ||
 |
ts | Thunderstorm | ||
 |
tsrain | Thunderstorm with rain |
ASTRO
For thumbnails:
| Label | Definition |
|---|---|
 |
Octet-gram of cloud cover, blue is clear while white is cloud. e.g. the "cake" on the left is 0% cloud while the one on the right is 100% cloud. |
 |
Astronomical seeing. From left to right: <0.5", 0.5"-0.75", 0.75"-1", 1"-1.25", 1.25"-1.5", 1.5"-2", 2"-2.5", >2.5". In short, the smaller/bluer, the better the seeing condition is. |
 |
Atmospheric transparency. From left to right: <0.3, 0.3-0.4, 0.4-0.5, 0.5-0.6, 0.6-0.7, 0.7-0.85, 0.85-1, >1 (unit: mag per air mass). In short, the fewer bars/bluer, the better the transparency is. |
 |
Chances of rain/snow. |
 |
Atmospheric instability. From left to right: lifted index between 0 to -3, -3 to -5, and below -5. |
 |
Humid weather warning. From left to right: relative humidity between 80%-90%, 90%-95%, and over 95%. |
 |
Windy weather warning. From left to right: sustained wind speed between 8.0-10.8m/s (fresh), 10.8-17.2m/s (strong), and over 17.2m/s (gale or above). |
For machine-readable API:
| Parameter | Definition | Value (-9999 = undefined) | Meaning |
|---|---|---|---|
| cloudcover | Cloud Cover | 1 | 0%-6% |
| 2 | 6%-19% | ||
| 3 | 19%-31% | ||
| 4 | 31%-44% | ||
| 5 | 44%-56% | ||
| 6 | 56%-69% | ||
| 7 | 69%-81% | ||
| 8 | 81%-94% | ||
| 9 | 94%-100% | ||
| seeing | Seeing | 1 | <0.5" |
| 2 | 0.5"-0.75" | ||
| 3 | 0.75"-1" | ||
| 4 | 1"-1.25" | ||
| 5 | 1.25"-1.5" | ||
| 6 | 1.5"-2" | ||
| 7 | 2"-2.5" | ||
| 8 | >2.5" | ||
| transparency | Transparency | 1 | <0.3 |
| 2 | 0.3-0.4 | ||
| 3 | 0.4-0.5 | ||
| 4 | 0.5-0.6 | ||
| 5 | 0.6-0.7 | ||
| 6 | 0.7-0.85 | ||
| 7 | 0.85-1 | ||
| 8 | >1 | ||
| lifted_index | Lifted Index | -10 | Below -7 |
| -6 | -7 to -5 | ||
| -4 | -5 to -3 | ||
| -1 | -3 to 0 | ||
| 2 | 0 to 4 | ||
| 6 | 4 to 8 | ||
| 10 | 8 to 11 | ||
| 15 | Over 11 | ||
| temp2m | 2m Temperature | - | 2m temperature in Celsius |
| rh2m | 2m Relative Humidity | -4 | 0%-5% |
| -3 | 5%-10% | ||
| -2 | 10%-15% | ||
| -1 | 15%-20% | ||
| 0 | 20%-25% | ||
| 1 | 25%-30% | ||
| 2 | 30%-35% | ||
| 3 | 35%-40% | ||
| 4 | 40%-45% | ||
| 5 | 45%-50% | ||
| 6 | 50%-55% | ||
| 7 | 55%-60% | ||
| 8 | 60%-65% | ||
| 9 | 65%-70% | ||
| 10 | 70%-75% | ||
| 11 | 75%-80% | ||
| 12 | 80%-85% | ||
| 13 | 85%-90% | ||
| 14 | 90%-95% | ||
| 15 | 95%-99% | ||
| 16 | 100% | ||
| wind10m_direction | 10m Wind Direction | N, NE, E, SE, S, SW, W, NW | |
| wind10m_speed | 10m Wind Speed | 1 | Below 0.3m/s (calm) |
| 2 | 0.3-3.4m/s (light) | ||
| 3 | 3.4-8.0m/s (moderate) | ||
| 4 | 8.0-10.8m/s (fresh) | ||
| 5 | 10.8-17.2m/s (strong) | ||
| 6 | 17.2-24.5m/s (gale) | ||
| 7 | 24.5-32.6m/s (storm) | ||
| 8 | Over 32.6m/s (hurricane) | ||
| prec_type | Precipitation Type | snow, rain, none |
About the "Altitude Correction" function: You may consider setting this function if the location of interest is much (over 1000 meters) higher than its surrounding area. 7Timer! will give the forecast at 2km or 7km above the surface of the grid. The Altitude Correction can be set to 2km or 7km.
METEO
| Parameter | Definition | Value (-9999 = undefined) | Meaning |
|---|---|---|---|
| cloudcover, highcloud, midcloud, lowcloud | Cloud Cover (total, high, mid, low) | 1 | 0%-6% |
| 2 | 6%-19% | ||
| 3 | 19%-31% | ||
| 4 | 31%-44% | ||
| 5 | 44%-56% | ||
| 6 | 56%-69% | ||
| 7 | 69%-81% | ||
| 8 | 81%-94% | ||
| 9 | 94%-100% | ||
| rh2m, rh_profile | Relative Humidity at 2m and different geopotential layers | -4 | 0%-5% |
| -3 | 5%-10% | ||
| -2 | 10%-15% | ||
| -1 | 15%-20% | ||
| 0 | 20%-25% | ||
| 1 | 25%-30% | ||
| 2 | 30%-35% | ||
| 3 | 35%-40% | ||
| 4 | 40%-45% | ||
| 5 | 45%-50% | ||
| 6 | 50%-55% | ||
| 7 | 55%-60% | ||
| 8 | 60%-65% | ||
| 9 | 65%-70% | ||
| 10 | 70%-75% | ||
| 11 | 75%-80% | ||
| 12 | 80%-85% | ||
| 13 | 85%-90% | ||
| 14 | 90%-95% | ||
| 15 | 95%-99% | ||
| 16 | 100% | ||
| wind10m_direction, wind_direction_profile | Wind direction at 10m and different geopotential layers | Wind direction in degrees | |
| wind10m_speed, wind_speed_profile | Wind Speed (10m and profile) | 1 | Below 0.3m/s (calm) |
| 2 | 0.3-3.4m/s (light) | ||
| 3 | 3.4-8.0m/s (moderate) | ||
| 4 | 8.0-10.8m/s (fresh) | ||
| 5 | 10.8-17.2m/s (strong) | ||
| 6 | 17.2-24.5m/s (gale) | ||
| 7 | 24.5-32.6m/s (storm) | ||
| 8 | 32.6-36.7m/s (hurricane) | ||
| 9 | 36.7-41.4m/s (hurricane+) | ||
| 10 | 41.4-46.2m/s (hurricane+) | ||
| 11 | 46.2-50.9m/s (hurricane+) | ||
| 12 | 50.9-55.9m/s (hurricane+) | ||
| 13 | Over 55.9m/s (hurricane+) | ||
| lifted_index | Lifted Index | -10 | Below -7 |
| -6 | -7 to -5 | ||
| -4 | -5 to -3 | ||
| -1 | -3 to 0 | ||
| 2 | 0 to 4 | ||
| 6 | 4 to 8 | ||
| 10 | 8 to 11 | ||
| 15 | Over 11 | ||
| temp2m | 2m Temperature | - | 2m temperature in Celsius |
| msl_pressure | MSL Pressure | MSL Pressure in hPa | |
| prec_type | Precipitation Type | snow | Snow |
| rain | Rain | ||
| frzr | Freezing rain | ||
| icep | Ice pellets | ||
| none | None | ||
| prec_amount | Precipitation Amount | 0 | None |
| 1 | 0-0.25mm/hr | ||
| 2 | 0.25-1mm/hr | ||
| 3 | 1-4mm/hr | ||
| 4 | 4-10mm/hr | ||
| 5 | 10-16mm/hr | ||
| 6 | 16-30mm/hr | ||
| 7 | 30-50mm/hr | ||
| 8 | 50-75mm/hr | ||
| 9 | 75+mm/hr | ||
| snow_depth | Snow Depth | 0 | None |
| 1 | 0-1cm | ||
| 2 | 1-5cm | ||
| 3 | 5-10cm | ||
| 4 | 10-25cm | ||
| 5 | 25-50cm | ||
| 6 | 50-100cm | ||
| 7 | 100-150cm | ||
| 8 | 150-250cm | ||
| 9 | 250+cm |
Usage
This service is provided as-is. Feel free to use it as you like. There is no need to ask me for permission if you want to put the forecast graph on your website or use the data for your software (free or paid). I would certainly appreciate a note if you like it, or if you have any suggestions or comments. Note that development has long ceased because I have lost the luxury of having abundant free time (lives...), but I try to keep it running as long and stable as I can.
Acknowledgement
Without the help of these generous people, 7Timer! would not be possible:
- Chenzhou Cui, administrator of the Cosmostation service of the National Astronomical Observatories of China. 7Timer! was hosted on a Cosmostation server from 2005 to 2010.
- Dimitrios Kechagias, the author of Xasteria. 7Timer! has been hosted on servers he provided since 2018. Please support his work if you can -- Xasteria is a great app!
- Johnson Lau, who wrote an automatic data handling pipeline for 7Timer! (which remains in use today) and provided hardware for the operation.
- Haiming Tang, administrator of the Chinese Network for Astronomy Popularization. 7Timer! was hosted on CNAP from 2011 to 2018.
- Zuqiang Li, littlePig and Max helped me into code development in the early days of 7Timer!. Liaoshan Shi helped tested every major upgrade.
- Many people, some anonymous, support this work in various ways.
THANK YOU all!
Icons are designed by Weather Sniffer and Iconbest.
About the author
Quanzhi Ye was a high schooler and was a newbie in programming when he started to develop 7Timer! in 2005. As a passionate stargazer, he wanted 7Timer! because he was frequently frustrated by the bad weather when he went out for stargazing near his hometown of Guangzhou, China, a tropical city known for its rainfall and variable weather. Now he is a professional astronomer working at the University of Maryland, USA. He still goes out for stargazing once in a while, and with the generous help from many, trying to keep 7Timer! running as long as he can.