SUN-BROKER

HOW TO USE

Make an API request with the lattitude and longitude of your location.

Like so: https://sun-broker.xyz/sun-state/[your_lat]/[your_long]

This will return an API response like so...

      {
       "suns_up":true,
       "time_to_sunrise":-1,
       "time_to_sunset":85,
       "is_after_solar_noon":true,
       "is_after_civil_twilight_begin":true,
       "is_after_civil_twilight_end":false,
       "is_after_nautical_twilight_begin":true,
       "is_after_nautical_twilight_end":false,
       "is_after_astronomical_twilight_begin":true,
       "is_after_astronomical_twilight_end":false,
       "results":{
          "sunrise":"2023-07-16T23:45:21+00:00",
          "sunset":"2023-07-17T14:34:35+00:00",
          "solar_noon":"2023-07-17T07:09:58+00:00",
          "day_length":53354,
          "civil_twilight_begin":"2023-07-16T23:14:46+00:00",
          "civil_twilight_end":"2023-07-17T15:05:10+00:00",
          "nautical_twilight_begin":"2023-07-16T22:34:22+00:00",
          "nautical_twilight_end":"2023-07-17T15:45:35+00:00",
          "astronomical_twilight_begin":"2023-07-16T21:48:11+00:00",
          "astronomical_twilight_end":"2023-07-17T16:31:45+00:00"
       },
       "status":"OK",
       "localized_times":{
          "sunrise":"2023-07-17 05:45",
          "sunset":"2023-07-17 20:34",
          "solar_noon":"2023-07-17 13:09",
          "day_length":53354,
          "civil_twilight_begin":"2023-07-17 05:14",
          "civil_twilight_end":"2023-07-17 21:05",
          "nautical_twilight_begin":"2023-07-17 04:34",
          "nautical_twilight_end":"2023-07-17 21:45",
          "astronomical_twilight_begin":"2023-07-17 03:48",
          "astronomical_twilight_end":"2023-07-17 22:31"
       },
       "thank_you":{
          "attribution":"Thank you to sunrise-sunset.org for providing a free and easy to use basis for retrieval of sunrise and sunset data.",
          "api_hit":"https://api.sunrise-sunset.org/json?lat=40.6892&lng=74.0445&date=2023-07-17&formatted=0"
       }
      }
      

RETURNED DATA EXPLAINED

• suns_up: [bool] Tells if the sun is currently up or not at the current location. Takes the local time and checks if it is between sunrise and sunset for the day.
• time_to_sunrise: [int] Gives the number of minutes until sunrise for the day. Is -1 if sunrise has already passed.
• time_to_sunset: [int] Gives the number of minutes until sunrise for the day. Is -1 if sunset has already passed.
• is_after_(param): [bool] A simple binary/boolean flag for if a horizon event has already passed for the day or not. This is for other events near sunrises and sunsets like civil twilight and nautical twilight.
• results: [obj] The original time data in UTC+0 from sunrise-sunset.org Who are nice enough to provide a free and easy to use API for basic sunrise and sunset data.
• status: [string] A string of if the request came back ok or what was wrong with it. Set by sunrise-sunset.org. Not super important for this application but I choose not to strip it.
• localized_times: [obj] An object of time results from sunrise-sunset.org. However these are converted to the local timezone of the location requested. Making it easier to parse when events are happening locally.
• thank_you: [obj] Thank you to those who provide upstream data and APIs to make this work. As well as info about requests sent to upsteam APIs.

WHY THIS IS NEEDED

I had a number of IFTTT events that I only wanted to filter so they'd only fire if the sun is up or down. Exact time of sunrise or sunset was unimportant in most cases.

There are a lot of helpful APIs for weather and sunrise and set data. Specifically sunrise-sunset.org is very lightweight and easy to use. However it does not handle timezones and returns everything in a UTC+0 time signature.

This becomes problematic. If you're using a tool like IFTTT or some other automation tools creating a now() type timestamp will give a local time to the browser or server. Which unless also in UTC+0 time will create a mismatch from the time and actual events at the actual physical location.

So this API was created to take in all the timed data for sunrises and sunsets and localize all timestamps. These timestamps can then reliably be compared against each other in the actual time of the physical location. Giving you an accurate reflection of the suns current position at that physical location.

© 2023 |