Weather API: Difference between revisions

From Deep Sky Chile
← Older edit
No edit summary
No edit summary
 
(6 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Deep Sky Chile Weather API User Manual ==
== Deep Sky Chile Weather API User Manual ==


The Deep Sky Chile Weather API provides real-time weather and astronomical data, including cloud cover, temperature, wind speed, rain, light levels, and key astronomical measurements.
The Deep Sky Chile Weather API provides real-time weather and astronomical data, including cloud cover, temperature, wind speed, rain, light levels, seeing conditions, and key astronomical measurements.


=== Base URL ===
=== Base URL ===
The base URL for accessing the API is: http://api.deepskychile.com/weather
The base URL for accessing the API is:
<code>http://api.deepskychile.com/weather</code>


=== Endpoint ===
=== Endpoint ===
* '''GET /weather''': Retrieves the current weather and astronomical data, including cloud, rain, light states, and important astronomical metrics.
* '''GET /weather''': Retrieves the current weather and astronomical data, including cloud, rain, light states, seeing, and important astronomical metrics.


=== Response Format ===
=== Response Format ===
The API returns the data in JSON format with the following structure:
The API returns data in JSON format with the following structure:
<pre>
{
{
     "weather": {
     "weather": {
         "cloudwatcher": {
         "cloudwatcher": {
             "clouds": <clouds_value>,
             "clouds": &lt;clouds_value&gt;,
             "temp": <temperature_value>,
             "temp": &lt;temperature_value&gt;,
             "wind": <wind_speed>,
             "wind": &lt;wind_speed&gt;,
             "gust": <wind_gust>,
             "gust": &lt;wind_gust&gt;,
             "rain": <rain_value>,
             "rain": &lt;rain_value&gt;,
             "light": <light_level>,
             "light": &lt;light_level&gt;,
             "switch": <switch_state>,
             "switch": &lt;switch_state&gt;,
             "safe": <safe_state>,
             "safe": &lt;safe_state&gt;,
             "hum": <humidity>,
             "hum": &lt;humidity&gt;,
             "dewp": <dew_point>,
             "dewp": &lt;dew_point&gt;,
             "cloudsState": "<clouds_state>",
             "cloudsState": "&lt;clouds_state&gt;",
             "rainState": "<rain_state>",
             "rainState": "&lt;rain_state&gt;",
             "lightState": "<light_state>"
             "lightState": "&lt;light_state&gt;"
         },
         },
         "ninox": {
         "ninox": {
             "UTC": "<utc_time>",
             "UTC": "&lt;utc_time&gt;",
             "NSBNow": <current_NSB_value>,
             "NSBNow": &lt;current_NSB_value&gt;,
             "SunAltitude": <sun_altitude>,
             "SunAltitude": &lt;sun_altitude&gt;,
             "MoonAltitude": <moon_altitude>,
             "MoonAltitude": &lt;moon_altitude&gt;,
             "MoonPhase": <moon_phase>,
             "MoonPhase": &lt;moon_phase&gt;,
             "ZenithGalacticLatitude": <galactic_latitude>,
             "ZenithGalacticLatitude": &lt;galactic_latitude&gt;,
             "NightBestNSB": <best_NSB_value>,
             "NightBestNSB": &lt;best_NSB_value&gt;,
             "NightBestNSBTime": "<night_best_NSB_time>",
             "NightBestNSBTime": "&lt;night_best_NSB_time&gt;",
             "NightBestNSBZGL": <night_best_ZGL>,
             "NightBestNSBZGL": &lt;night_best_ZGL&gt;,
             "OverallBestNSB": <overall_best_NSB_value>,
             "OverallBestNSB": &lt;overall_best_NSB_value&gt;,
             "OverallBestNSBTime": "<overall_best_NSB_time>",
             "OverallBestNSBTime": "&lt;overall_best_NSB_time&gt;",
             "OverallBestNSBZGL": <overall_best_ZGL>
             "OverallBestNSBZGL": &lt;overall_best_ZGL&gt;
        },
        "seeing": {
            "UTC": "&lt;seeing_utc_time&gt;",
            "SeeingValue": &lt;seeing_value&gt;,
            "status": "&lt;seeing_monitor_status&gt;",
            "avgSeeing": &lt;average_seeing&gt;,
            "monitoringSeeingStart": "&lt;seeing_monitoring_start&gt;",
            "minSeeing": &lt;minimum_seeing_since_start&gt;,
            "minSeeingTime": "&lt;minimum_seeing_time&gt;",
            "nightMinSeeing": &lt;minimum_seeing_current_night&gt;,
            "nightMinSeeingTime": "&lt;minimum_seeing_time_current_night&gt;"
         },
         },
         "average": {
         "average": {
             "avgHum": <average_humidity>,
             "avgHum": &lt;average_humidity&gt;,
             "avgWind": <average_wind_speed>,
             "avgWind": &lt;average_wind_speed&gt;,
             "avgTemp": <average_temperature>,
             "avgTemp": &lt;average_temperature&gt;,
             "monitoringStart": "<monitoring_start_date>"
             "monitoringStart": "&lt;monitoring_start_date&gt;"
         }
         }
     }
     }
}
}
</pre>
=== Fields === 
'''weather''' 
The main object containing weather data from four sources: <code>cloudwatcher</code>, <code>ninox</code>, <code>seeing</code>, and <code>average</code>.


=== Fields ===
'''cloudwatcher (General Weather Data)'''
weather  
* '''clouds''' (float): Current sky temperature in degrees Celsius. 
The main object containing weather data from three sources: cloudwatcher, ninox, and average.
* '''temp''' (float): Current temperature in degrees Celsius. 
* '''wind''' (float): Wind speed in km/h. 
* '''gust''' (float): Wind gust speed in km/h. 
* '''rain''' (float): Rain value (unitless). 
* '''light''' (float): Ambient light level (unitless). 
* '''switch''' (integer): Lock switch status: 
  * 1 – Observatories are unlocked. 
  * 0 – Observatories are locked. 
* '''safe''' (integer): Safety status: 
  * 1 – Safe. 
  * 0 – Unsafe. 
* '''hum''' (float): Relative humidity (%). 
* '''dewp''' (float): Dew point temperature in degrees Celsius. 
* '''cloudsState''' (string): 
  * "Clear" – Low cloud cover. 
  * "Cloudy" – Moderate cloud cover. 
  * "Overcast" – High cloud cover or fully covered skies. 
* '''rainState''' (string): 
  * "Dry" – Rain &gt; 2000. 
  * "Wet" – Rain between 1700 and 2000. 
  * "Raining" – Rain &lt; 1700.  
* '''lightState''' (string):
  * "Dark" – Light &gt; 8000. 
  * "Bright" – Light between 6 and 8000.
  * "Sunny" – Light &lt;= 6. 


cloudwatcher (General Weather Data)
'''ninox (Astronomical Data)'''
* '''clouds''' (float): The current sky temperature in degrees Celsius. 
* '''UTC''' (string): Current UTC time, format yyyy-mm-dd hh:mm:ss.   
* '''temp''' (float): The current temperature in degrees Celsius.   
* '''NSBNow''' (float): Current sky-brightness (NSB) value; lower is darker.   
* '''wind''' (float): The current wind speed in kilometer per hour (km/h).   
* '''SunAltitude''' (float): Altitude of the Sun (°).   
* '''gust''' (float): The current wind gust speed in kilometer per hour (km/h).   
* '''MoonAltitude''' (float): Altitude of the Moon (°).   
* '''rain''' (float): The amount of rain, no unit.   
* '''MoonPhase''' (float): Moon phase (%).   
* '''light''' (float): The ambient light level, no unit.   
* '''ZenithGalacticLatitude''' (float): Galactic latitude at zenith (°).   
* '''switch''' (integer): Lock switch status value. Possible values:
* '''NightBestNSB''' (float): Best NSB value for the current night.   
  * 1: Observatories are unlocked. 
* '''NightBestNSBTime''' (string): Timestamp of <code>NightBestNSB</code>.   
  * 0: Observatories are locked.   
* '''NightBestNSBZGL''' (float): Zenith galactic latitude at <code>NightBestNSBTime</code>.   
* '''safe''' (integer): Safety status value. Possible values:
* '''OverallBestNSB''' (float): Best overall NSB recorded.   
  * 1: Safe. 
* '''OverallBestNSBTime''' (string): Timestamp of <code>OverallBestNSB</code>.   
  * 0: Unsafe.   
* '''OverallBestNSBZGL''' (float): Galactic latitude at <code>OverallBestNSBTime</code>.
* '''hum''' (float): The relative humidity in percentage.   
* '''dewp''' (float): The dew point temperature in degrees Celsius.   
* '''cloudsState''' (string): Determined based on the clouds value. Possible values:
  * "Clear": Cloud coverage is low.
  * "Cloudy": Moderate cloud cover.
  * "Overcast": High cloud cover or fully covered skies.   
* '''rainState''' (string): Determined based on the rain value. Possible values:
  * "Dry": No significant rain detected (rain value greater than 2000).
  * "Wet": Light rain (rain value between 1700 and 2000).
  * "Raining": Moderate to heavy rain (rain value less than 1700).   
* '''lightState''' (string): Determined based on the light value. Possible values:
  * "Dark": Light intensity above 8000.
  * "Bright": Light intensity between 6 and 8000.
  * "Sunny": Light intensity below 6.


ninox (Astronomical Data)
'''seeing (Atmospheric Seeing Conditions)'''
* '''UTC''' (string): The current UTC time, formatted as yy-mm-dd hh:mm:ss.   
* '''UTC''' (string): UTC time of the current seeing measurement.   
* '''NSBNow''' (float): The current NSB (Sky Brightness) value. It represents the visibility of the night sky. Lower values indicate better observing conditions.   
* '''SeeingValue''' (float): Current seeing value in arcseconds (lower = better).   
* '''SunAltitude''' (float): The altitude of the Sun in degrees. Negative values indicate the Sun is below the horizon.
* '''status''' (string): Operational status of the seeing monitor (e.g., "Monitoring", "Idle (Daytime)").
* '''MoonAltitude''' (float): The altitude of the Moon in degrees. Negative values indicate the Moon is below the horizon.   
* '''avgSeeing''' (float): Average seeing since monitoring began.   
* '''MoonPhase''' (float): The phase of the Moon, measured as a percentage (0-100%).   
* '''monitoringSeeingStart''' (string): Start timestamp for seeing monitoring (yyyy-mm-dd hh:mm:ss).   
* '''ZenithGalacticLatitude''' (float): The galactic latitude at the zenith, used to describe the position relative to the galactic plane. 
* '''minSeeing''' (float): Lowest (best) seeing since <code>monitoringSeeingStart</code>.   
* '''NightBestNSB''' (float): The best NSB value for the night.   
* '''minSeeingTime''' (string): Timestamp of <code>minSeeing</code>.   
* '''NightBestNSBTime''' (string): The timestamp of when the best NSB conditions occur during the night.   
* '''nightMinSeeing''' (float): Best seeing during the current astronomical night.   
* '''NightBestNSBZGL''' (float): The Zenith Galactic Latitude associated with the best NSB value.   
* '''nightMinSeeingTime''' (string): Timestamp of <code>nightMinSeeing</code>.
* '''OverallBestNSB''' (float): The overall best NSB value over a longer period, representing the best observing conditions overall. 
* '''OverallBestNSBTime''' (string): The timestamp of when the overall best NSB conditions occur. 
* '''OverallBestNSBZGL''' (float): The Zenith Galactic Latitude associated with the overall best NSB value.


average (Averaged Historical Data)
'''average (Averaged Historical Data)'''
* '''avgHum''' (float): The average relative humidity in percentage since monitoring began.   
* '''avgHum''' (float): Average humidity (%) since monitoring began.   
* '''avgWind''' (float): The average wind speed in kilometer per hour (km/h) since monitoring began.   
* '''avgWind''' (float): Average wind speed (km/h) since monitoring began.   
* '''avgTemp''' (float): The average temperature in degrees Celsius since monitoring began.   
* '''avgTemp''' (float): Average temperature (°C) since monitoring began.   
* '''monitoringStart''' (string): The timestamp marking the start of monitoring, formatted as yyyy-mm-dd hh:mm:ss.
* '''monitoringStart''' (string): Start timestamp for historical averages (yyyy-mm-dd hh:mm:ss).


=== Example Response ===
=== Example Response ===
<pre>
{
{
     "weather": {
     "weather": {
         "cloudwatcher": {
         "cloudwatcher": {
             "clouds": -17.18,
             "clouds": -14.82,
             "temp": 36.33,
             "temp": 12.09,
             "wind": 3,
             "wind": 3,
             "gust": 5,
             "gust": 3,
             "rain": 5094,
             "rain": 5248,
             "light": 2,
             "light": 57232,
             "switch": 1,
             "switch": 1,
             "safe": 1,
             "safe": 1,
             "hum": 14,
             "hum": 22,
             "dewp": 4.6,
             "dewp": -9,
             "cloudsState": "Clear",
             "cloudsState": "Clear",
             "rainState": "Dry",
             "rainState": "Dry",
             "lightState": "Sunny"
             "lightState": "Dark"
         },
         },
         "ninox": {
         "ninox": {
             "UTC": "24-11-15 09:05:52",
             "UTC": "2025-05-24 07:42:47",
             "NSBNow": 15.96,
             "NSBNow": 21.02,
             "SunAltitude": -8,
             "SunAltitude": -48.5,
             "MoonAltitude": 0.3,
             "MoonAltitude": -10.7,
             "MoonPhase": 99.5,
             "MoonPhase": 11.42,
             "ZenithGalacticLatitude": -0.9,
             "ZenithGalacticLatitude": -15.9,
             "NightBestNSB": 19.43,
             "NightBestNSB": 21.41,
             "NightBestNSBTime": "24-11-15 08:28:44",
             "NightBestNSBTime": "2025-05-24 00:59:44",
             "NightBestNSBZGL": -7,
             "NightBestNSBZGL": 32,
             "OverallBestNSB": 24.1,
             "OverallBestNSB": 21.96,
             "OverallBestNSBTime": "24-05-07 23:17:28",
             "OverallBestNSBTime": "2025-05-17 23:30:55",
             "OverallBestNSBZGL": 16.2
             "OverallBestNSBZGL": 23.2
        },
        "seeing": {
            "UTC": "2025-05-24 07:35:03",
            "SeeingValue": 1.22,
            "status": "Idle (Daytime)",
            "avgSeeing": 0.93,
            "monitoringSeeingStart": "2025-05-21 14:04:05",
            "minSeeing": 0.48,
            "minSeeingTime": "2025-05-22 10:22:06",
            "nightMinSeeing": 0.54,
            "nightMinSeeingTime": "2025-05-24 06:20:06"
         },
         },
         "average": {
         "average": {
             "avgHum": 26.43,
             "avgHum": 25.22,
             "avgWind": 6.81,
             "avgWind": 3.37,
             "avgTemp": 19.21,
             "avgTemp": 15.26,
             "monitoringStart": "2023-01-03 22:41:01"
             "monitoringStart": "2023-05-24 09:49:02"
         }
         }
     }
     }
}
}
</pre>


=== Error Handling ===
=== Error Handling ===
If an error occurs while fetching the data, the API will return a generic HTTP error response (e.g., 500 Internal Server Error).
If an error occurs while fetching the data, the API will return a generic HTTP error response (e.g., 500&nbsp;Internal&nbsp;Server&nbsp;Error).
 
=== Example Request ===
To retrieve the current weather and astronomical data, make a simple GET request to the following endpoint:
GET http://api.deepskychile.com/weather


=== Authentication ===
=== Example Request ===
Currently, the API does not require authentication. Any future authentication requirements will be detailed here.
To retrieve the current weather and astronomical data: 
<code>GET http://api.deepskychile.com/weather</code>


=== Conclusion ===
=== Authentication ===
This API provides both weather and astronomical data to help with sky observations and general weather monitoring at Deep Sky Chile. It allows users to track cloud coverage, temperature, rain, light levels, and other important factors for stargazing, as well as obtain detailed astronomical conditions such as NSB, Sun and Moon altitudes, and phase data.
Currently, the API does not require authentication. Any future requirements will be documented here.


If you need further assistance or have additional questions about using the API, feel free to reach out.
=== Conclusion === 
This API provides detailed weather, seeing, and astronomical data to support stargazing, observatory operations, and long-term monitoring at Deep Sky Chile.


[[Category:User manuals]]
[[Category:User manuals]]

Latest revision as of 13:28, 8 December 2025

Deep Sky Chile Weather API User Manual[edit]

The Deep Sky Chile Weather API provides real-time weather and astronomical data, including cloud cover, temperature, wind speed, rain, light levels, seeing conditions, and key astronomical measurements.

Base URL[edit]

The base URL for accessing the API is: http://api.deepskychile.com/weather

Endpoint[edit]

  • GET /weather: Retrieves the current weather and astronomical data, including cloud, rain, light states, seeing, and important astronomical metrics.

Response Format[edit]

The API returns data in JSON format with the following structure: 

{
    "weather": {
        "cloudwatcher": {
            "clouds": <clouds_value>,
            "temp": <temperature_value>,
            "wind": <wind_speed>,
            "gust": <wind_gust>,
            "rain": <rain_value>,
            "light": <light_level>,
            "switch": <switch_state>,
            "safe": <safe_state>,
            "hum": <humidity>,
            "dewp": <dew_point>,
            "cloudsState": "<clouds_state>",
            "rainState": "<rain_state>",
            "lightState": "<light_state>"
        },
        "ninox": {
            "UTC": "<utc_time>",
            "NSBNow": <current_NSB_value>,
            "SunAltitude": <sun_altitude>,
            "MoonAltitude": <moon_altitude>,
            "MoonPhase": <moon_phase>,
            "ZenithGalacticLatitude": <galactic_latitude>,
            "NightBestNSB": <best_NSB_value>,
            "NightBestNSBTime": "<night_best_NSB_time>",
            "NightBestNSBZGL": <night_best_ZGL>,
            "OverallBestNSB": <overall_best_NSB_value>,
            "OverallBestNSBTime": "<overall_best_NSB_time>",
            "OverallBestNSBZGL": <overall_best_ZGL>
        },
        "seeing": {
            "UTC": "<seeing_utc_time>",
            "SeeingValue": <seeing_value>,
            "status": "<seeing_monitor_status>",
            "avgSeeing": <average_seeing>,
            "monitoringSeeingStart": "<seeing_monitoring_start>",
            "minSeeing": <minimum_seeing_since_start>,
            "minSeeingTime": "<minimum_seeing_time>",
            "nightMinSeeing": <minimum_seeing_current_night>,
            "nightMinSeeingTime": "<minimum_seeing_time_current_night>"
        },
        "average": {
            "avgHum": <average_humidity>,
            "avgWind": <average_wind_speed>,
            "avgTemp": <average_temperature>,
            "monitoringStart": "<monitoring_start_date>"
        }
    }
}

Fields[edit]

weather The main object containing weather data from four sources: cloudwatcher, ninox, seeing, and average.

cloudwatcher (General Weather Data)

  • clouds (float): Current sky temperature in degrees Celsius.
  • temp (float): Current temperature in degrees Celsius.
  • wind (float): Wind speed in km/h.
  • gust (float): Wind gust speed in km/h.
  • rain (float): Rain value (unitless).
  • light (float): Ambient light level (unitless).
  • switch (integer): Lock switch status:
 * 1 – Observatories are unlocked.  
 * 0 – Observatories are locked.
  • safe (integer): Safety status:
 * 1 – Safe.  
 * 0 – Unsafe.
  • hum (float): Relative humidity (%).
  • dewp (float): Dew point temperature in degrees Celsius.
  • cloudsState (string):
 * "Clear" – Low cloud cover.  
 * "Cloudy" – Moderate cloud cover.  
 * "Overcast" – High cloud cover or fully covered skies.
  • rainState (string):
 * "Dry" – Rain > 2000.  
 * "Wet" – Rain between 1700 and 2000.  
 * "Raining" – Rain < 1700.
  • lightState (string):
 * "Dark" – Light > 8000.  
 * "Bright" – Light between 6 and 8000.  
 * "Sunny" – Light <= 6.

ninox (Astronomical Data)

  • UTC (string): Current UTC time, format yyyy-mm-dd hh:mm:ss.
  • NSBNow (float): Current sky-brightness (NSB) value; lower is darker.
  • SunAltitude (float): Altitude of the Sun (°).
  • MoonAltitude (float): Altitude of the Moon (°).
  • MoonPhase (float): Moon phase (%).
  • ZenithGalacticLatitude (float): Galactic latitude at zenith (°).
  • NightBestNSB (float): Best NSB value for the current night.
  • NightBestNSBTime (string): Timestamp of NightBestNSB.
  • NightBestNSBZGL (float): Zenith galactic latitude at NightBestNSBTime.
  • OverallBestNSB (float): Best overall NSB recorded.
  • OverallBestNSBTime (string): Timestamp of OverallBestNSB.
  • OverallBestNSBZGL (float): Galactic latitude at OverallBestNSBTime.

seeing (Atmospheric Seeing Conditions)

  • UTC (string): UTC time of the current seeing measurement.
  • SeeingValue (float): Current seeing value in arcseconds (lower = better).
  • status (string): Operational status of the seeing monitor (e.g., "Monitoring", "Idle (Daytime)").
  • avgSeeing (float): Average seeing since monitoring began.
  • monitoringSeeingStart (string): Start timestamp for seeing monitoring (yyyy-mm-dd hh:mm:ss).
  • minSeeing (float): Lowest (best) seeing since monitoringSeeingStart.
  • minSeeingTime (string): Timestamp of minSeeing.
  • nightMinSeeing (float): Best seeing during the current astronomical night.
  • nightMinSeeingTime (string): Timestamp of nightMinSeeing.

average (Averaged Historical Data)

  • avgHum (float): Average humidity (%) since monitoring began.
  • avgWind (float): Average wind speed (km/h) since monitoring began.
  • avgTemp (float): Average temperature (°C) since monitoring began.
  • monitoringStart (string): Start timestamp for historical averages (yyyy-mm-dd hh:mm:ss).

Example Response[edit]

{
    "weather": {
        "cloudwatcher": {
            "clouds": -14.82,
            "temp": 12.09,
            "wind": 3,
            "gust": 3,
            "rain": 5248,
            "light": 57232,
            "switch": 1,
            "safe": 1,
            "hum": 22,
            "dewp": -9,
            "cloudsState": "Clear",
            "rainState": "Dry",
            "lightState": "Dark"
        },
        "ninox": {
            "UTC": "2025-05-24 07:42:47",
            "NSBNow": 21.02,
            "SunAltitude": -48.5,
            "MoonAltitude": -10.7,
            "MoonPhase": 11.42,
            "ZenithGalacticLatitude": -15.9,
            "NightBestNSB": 21.41,
            "NightBestNSBTime": "2025-05-24 00:59:44",
            "NightBestNSBZGL": 32,
            "OverallBestNSB": 21.96,
            "OverallBestNSBTime": "2025-05-17 23:30:55",
            "OverallBestNSBZGL": 23.2
        },
        "seeing": {
            "UTC": "2025-05-24 07:35:03",
            "SeeingValue": 1.22,
            "status": "Idle (Daytime)",
            "avgSeeing": 0.93,
            "monitoringSeeingStart": "2025-05-21 14:04:05",
            "minSeeing": 0.48,
            "minSeeingTime": "2025-05-22 10:22:06",
            "nightMinSeeing": 0.54,
            "nightMinSeeingTime": "2025-05-24 06:20:06"
        },
        "average": {
            "avgHum": 25.22,
            "avgWind": 3.37,
            "avgTemp": 15.26,
            "monitoringStart": "2023-05-24 09:49:02"
        }
    }
}

Error Handling[edit]

If an error occurs while fetching the data, the API will return a generic HTTP error response (e.g., 500 Internal Server Error).

Example Request[edit]

To retrieve the current weather and astronomical data: GET http://api.deepskychile.com/weather

Authentication[edit]

Currently, the API does not require authentication. Any future requirements will be documented here.

Conclusion[edit]

This API provides detailed weather, seeing, and astronomical data to support stargazing, observatory operations, and long-term monitoring at Deep Sky Chile.

Retrieved from "https://wiki.deepskychile.com/index.php?title=Weather_API&oldid=125"