The Sunsethue API provides API products, tools, and resources that enable you to access and use Sunsethue's data products in your applications and projects.
\nSteps to start using the Sunsethue API:
\nSign up for the API on sunsethue.com/dev-api
\nGenerate an API key in the API portal sunsethue.com/dev-api/portal
\nConsult your daily request quota, you cannot go over the daily request quota on a free account. Be aware that the number of credits used differ per endpoint.
\nThe Sunsethue API uses API keys for authentication. You can generate a Sunsthue API key in the API portal.
\nYou must include your API key in every request you make to the Sunsethue API. The key can be passed in two ways:
\nPass the API key in the header of the HTTP request using the x-api-key property
Pass the API key as an argument (key={your_key}) in the URL of the request
Be careful with exposing the API key to the frontend of your application, as it can be accessed and stolen by malicious actors.
\nGenerate a key
If you do not have an API key yet, you can click \"generate key\" to generate a random API key. Make sure to store this key securely as it cannot be viewed again. Every account is limited to one API key.
Delete a key
To delete your API key, click \"delete key\". This can only be done if you have an active API key. On deletion, the API key will stop working instantly.
Regenerating a key
To generate a new key, delete your existing key and generate a new key.
If your request fails, an error response is returned. The returned object contains a status field with
400: user error
500: server error
The code field and message contain more information about the error. If you need help, please contact tropoflow@gmail.com, and include your request URL and the error code.
Example error response:
\n{\n status: 400,\n code: 204,\n message: \"Exceeded daily quota\"\n}\n\nIn case of issues with the Sunsethue API, contact me at tropoflow@gmail.com
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"📄 Introduction","slug":"introduction"}],"owner":"39964523","collectionId":"0c102ce6-6f37-4748-b0bc-c054d99488b8","publishedId":"2sAYBUDY4W","public":true,"customColor":{"top-bar":"fffdff","right-sidebar":"303030","highlight":"ca6acd"},"publishDate":"2024-11-24T16:05:46.000Z"},"item":[{"name":"Sunsethue","item":[{"name":"event","id":"90613726-edcc-47d2-8b23-1b9c2c956bde","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sunsethue.com/event?latitude={{latitude}}&longitude={{longitude}}&date={{date}}&type={{type}}&forecast={{forecast}}","description":"The event endpoint is used to access the forecasted data for a single event. The event is defined by a date, type and location. The date should be in local time (not in UTC time).
In case you only need the time, magic hours, and/or direction, you can set the forecast property to false. This will make sure model_data is always false, and as explained below, this will reduce the number of credits used.
The number of credits this API call adds to your daily total depends on model_data:
If model_data is false: 1 credit per request
If model_data is true: 5 credits per request
The data is returned in json format.
\nWhereby the coordinates object has a latitude and a longitude property.
(Required) Latitude of the location (in WGS84)
\n","type":"text/plain"},"key":"latitude","value":"{{latitude}}"},{"description":{"content":"(Required) Longitude of the location (in WGS84)
\n","type":"text/plain"},"key":"longitude","value":"{{longitude}}"},{"description":{"content":"(Required) Date of the event (in yyyy-mm-dd) in local time
\n","type":"text/plain"},"key":"date","value":"{{date}}"},{"description":{"content":"(Required) Type of the event (sunrise or sunset)
\n","type":"text/plain"},"key":"type","value":"{{type}}"},{"description":{"content":"(Optional, default=true) Whether forecasts should be fetched
\n","type":"text/plain"},"key":"forecast","value":"{{forecast}}"}],"variable":[]}},"response":[{"id":"048b6d15-08a3-4f66-bd0e-1aa9d75f27c8","name":"default","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{key}}","type":"text"}],"url":{"raw":"https://api.sunsethue.com/event?latitude=40.7&longitude=-74&date=2024-11-24&type=sunset","host":["https://api.sunsethue.com"],"path":["event"],"query":[{"key":"latitude","value":"40.7"},{"key":"longitude","value":"-74"},{"key":"date","value":"2024-11-24"},{"key":"type","value":"sunset"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"428"},{"key":"Cache-Control","value":"private"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Etag","value":"W/\"1ac-RchXrMtw7Ko+3Z8MwKt+OcQdjCs\""},{"key":"Function-Execution-Id","value":"ml9txmy6vd5c"},{"key":"Server","value":"Google Frontend"},{"key":"Strict-Transport-Security","value":"max-age=31556926"},{"key":"X-Cloud-Trace-Context","value":"5bb163f08d9fba09c0e084c5e638d1d9"},{"key":"X-Country-Code","value":"US"},{"key":"X-Powered-By","value":"Express"},{"key":"X-Ratelimit-Limit","value":"100"},{"key":"X-Ratelimit-Remaining","value":"98"},{"key":"X-Ratelimit-Reset","value":"1732464543"},{"key":"Accept-Ranges","value":"bytes"},{"key":"Date","value":"Sun, 24 Nov 2024 16:08:58 GMT"},{"key":"X-Served-By","value":"cache-iad-kcgs7200103-IAD"},{"key":"X-Cache","value":"MISS"},{"key":"X-Cache-Hits","value":"0"},{"key":"X-Timer","value":"S1732464538.645192,VS0,VE491"},{"key":"Vary","value":"cookie,need-authorization, x-fh-requested-host, accept-encoding"},{"key":"alt-svc","value":"h3=\":443\";ma=86400,h3-29=\":443\";ma=86400,h3-27=\":443\";ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"time\": \"2024-11-24T16:08:57.906Z\",\n \"location\": {\n \"latitude\": 40.7,\n \"longitude\": -74\n },\n \"grid_location\": {\n \"latitude\": 41,\n \"longitude\": -74\n },\n \"data\": {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.34,\n \"cloud_cover\": 0.19,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-24T21:32:00.000Z\",\n \"direction\": 243.1,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-24T21:57:00.000Z\",\n \"2024-11-24T22:10:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-24T21:17:00.000Z\",\n \"2024-11-24T21:51:00.000Z\"\n ]\n }\n }\n}"},{"id":"9234929b-6123-420f-9724-da167ed9c443","name":"no_model_data","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{key}}","type":"text"}],"url":{"raw":"https://api.sunsethue.com/event?latitude=50.4&longitude=-70&date=2024-11-30&type=sunrise","host":["https://api.sunsethue.com"],"path":["event"],"query":[{"key":"latitude","value":"50.4","description":"Latitude of the location (in WGS84)"},{"key":"longitude","value":"-70","description":"Longitude of the location (in WGS84)"},{"key":"date","value":"2024-11-30","description":"Date of the event (in yyyy-mm-dd)"},{"key":"type","value":"sunrise","description":"Type of the event (sunrise or sunset)"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"376"},{"key":"Cache-Control","value":"private"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Etag","value":"W/\"178-uCjUgCXkOCAuC/fGaa1RwRikDM4\""},{"key":"Function-Execution-Id","value":"ml9tzvs4k52m"},{"key":"Server","value":"Google Frontend"},{"key":"Strict-Transport-Security","value":"max-age=31556926"},{"key":"X-Cloud-Trace-Context","value":"eb7645a7364e3bb3800de89e5cced8d4"},{"key":"X-Country-Code","value":"US"},{"key":"X-Powered-By","value":"Express"},{"key":"X-Ratelimit-Limit","value":"100"},{"key":"X-Ratelimit-Remaining","value":"97"},{"key":"X-Ratelimit-Reset","value":"1732458752"},{"key":"Accept-Ranges","value":"bytes"},{"key":"Date","value":"Sun, 24 Nov 2024 14:32:31 GMT"},{"key":"X-Served-By","value":"cache-iad-kcgs7200096-IAD"},{"key":"X-Cache","value":"MISS"},{"key":"X-Cache-Hits","value":"0"},{"key":"X-Timer","value":"S1732458751.218896,VS0,VE432"},{"key":"Vary","value":"cookie,need-authorization, x-fh-requested-host, accept-encoding"},{"key":"alt-svc","value":"h3=\":443\";ma=86400,h3-29=\":443\";ma=86400,h3-27=\":443\";ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"time\": \"2024-11-24T14:32:31.497Z\",\n \"location\": {\n \"latitude\": 50.4,\n \"longitude\": -70\n },\n \"grid_location\": {\n \"latitude\": 50.5,\n \"longitude\": -70\n },\n \"data\": {\n \"type\": \"sunrise\",\n \"model_data\": false,\n \"time\": \"2024-11-30T12:17:00.000Z\",\n \"direction\": 124.2,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-30T11:30:00.000Z\",\n \"2024-11-30T11:46:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-30T11:54:00.000Z\",\n \"2024-11-30T12:38:00.000Z\"\n ]\n }\n }\n}"}],"_postman_id":"90613726-edcc-47d2-8b23-1b9c2c956bde"},{"name":"forecast","id":"c9a81294-6467-470b-8f66-279e806790b8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sunsethue.com/forecast?latitude={{latitude}}&longitude={{longitude}}&days={{days}}&type={{type}}&forecast={{forecast}}&timezone={{timezone}}","description":"The forecast endpoint is used to access the forecasted data for multiple events at once. Without any optional parameeters, it returns both sunrise and sunset events for the coming 3 days.
The events can be further filtered using the days and type parameters. This can influence the number of events returned.
The number of credits this API call adds to your daily total depends on the number of events and model_data:
If model_data is false: 1 credit per request per event
If model_data is true: 5 credits per request per event
The data is returned in json format.
\nWhereby the coordinates object has a latitude and a longitude property.
(Required) Latitude of the location (in WGS84)
\n","type":"text/plain"},"key":"latitude","value":"{{latitude}}"},{"description":{"content":"(Required) Longitude of the location (in WGS84)
\n","type":"text/plain"},"key":"longitude","value":"{{longitude}}"},{"description":{"content":"(Optional, default=3) Numbers of forecast days (integer)
\n","type":"text/plain"},"key":"days","value":"{{days}}"},{"description":{"content":"(Optional, default=both) Type of the events (sunrise or sunset)
\n","type":"text/plain"},"key":"type","value":"{{type}}"},{"description":{"content":"(Optional, default=true) Whether forecasts should be fetched
\n","type":"text/plain"},"key":"forecast","value":"{{forecast}}"},{"description":{"content":"(Optional, default=0) Timezone of the location to get the correct events when filtering by day (valid float)
\n","type":"text/plain"},"key":"timezone","value":"{{timezone}}"}],"variable":[]}},"response":[{"id":"f34f5f56-ae49-4b02-a5c9-35155c162cbe","name":"default","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{key}}","type":"text"}],"url":{"raw":"https://api.sunsethue.com/forecast?latitude=-21.83&longitude=55","host":["https://api.sunsethue.com"],"path":["forecast"],"query":[{"key":"latitude","value":"-21.83"},{"key":"longitude","value":"55"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"1901"},{"key":"Cache-Control","value":"private"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Etag","value":"W/\"76d-3SrnUbHEQOYMhvcm+sAzK/wnMoY\""},{"key":"Function-Execution-Id","value":"ml9thmud76hz"},{"key":"Server","value":"Google Frontend"},{"key":"Strict-Transport-Security","value":"max-age=31556926"},{"key":"X-Cloud-Trace-Context","value":"086b3582aefc4ac6764ef8b45854617f"},{"key":"X-Country-Code","value":"US"},{"key":"X-Powered-By","value":"Express"},{"key":"X-Ratelimit-Limit","value":"100"},{"key":"X-Ratelimit-Remaining","value":"96"},{"key":"X-Ratelimit-Reset","value":"1732463649"},{"key":"Accept-Ranges","value":"bytes"},{"key":"Date","value":"Sun, 24 Nov 2024 15:54:07 GMT"},{"key":"X-Served-By","value":"cache-iad-kcgs7200125-IAD"},{"key":"X-Cache","value":"MISS"},{"key":"X-Cache-Hits","value":"0"},{"key":"X-Timer","value":"S1732463646.442525,VS0,VE1090"},{"key":"Vary","value":"cookie,need-authorization, x-fh-requested-host, accept-encoding"},{"key":"alt-svc","value":"h3=\":443\";ma=86400,h3-29=\":443\";ma=86400,h3-27=\":443\";ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"time\": \"2024-11-24T15:54:07.311Z\",\n \"location\": {\n \"latitude\": -21.83,\n \"longitude\": 55\n },\n \"grid_location\": {\n \"latitude\": -21.5,\n \"longitude\": 55\n },\n \"data\": [\n {\n \"type\": \"sunrise\",\n \"model_data\": true,\n \"quality\": 0.34,\n \"cloud_cover\": 0.05,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-24T01:28:00.000Z\",\n \"direction\": 112.6,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-24T00:57:00.000Z\",\n \"2024-11-24T01:08:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-24T01:14:00.000Z\",\n \"2024-11-24T01:40:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.35,\n \"cloud_cover\": 0.86,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-24T14:45:00.000Z\",\n \"direction\": 247.4,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-24T15:05:00.000Z\",\n \"2024-11-24T15:16:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-24T14:33:00.000Z\",\n \"2024-11-24T15:00:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunrise\",\n \"model_data\": true,\n \"quality\": 0.39,\n \"cloud_cover\": 0.37,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-25T01:28:00.000Z\",\n \"direction\": 112.9,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-25T00:57:00.000Z\",\n \"2024-11-25T01:08:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-25T01:13:00.000Z\",\n \"2024-11-25T01:40:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.41,\n \"cloud_cover\": 0.43,\n \"quality_text\": \"Good\",\n \"time\": \"2024-11-25T14:46:00.000Z\",\n \"direction\": 247.1,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-25T15:06:00.000Z\",\n \"2024-11-25T15:17:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-25T14:34:00.000Z\",\n \"2024-11-25T15:01:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunrise\",\n \"model_data\": true,\n \"quality\": 0.35,\n \"cloud_cover\": 0.19,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-26T01:28:00.000Z\",\n \"direction\": 113.1,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-26T00:57:00.000Z\",\n \"2024-11-26T01:08:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-26T01:13:00.000Z\",\n \"2024-11-26T01:40:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.32,\n \"cloud_cover\": 0.55,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-26T14:47:00.000Z\",\n \"direction\": 246.9,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-26T15:07:00.000Z\",\n \"2024-11-26T15:18:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-26T14:35:00.000Z\",\n \"2024-11-26T15:01:00.000Z\"\n ]\n }\n }\n ]\n}"},{"id":"e6c93d6e-d7dc-4ee4-a299-13cac03a16ab","name":"optional_params","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{key}}","type":"text"}],"url":{"raw":"https://api.sunsethue.com/forecast?latitude=-21.83&longitude=55&days=2&type=sunset&timezone=-3","host":["https://api.sunsethue.com"],"path":["forecast"],"query":[{"key":"latitude","value":"-21.83"},{"key":"longitude","value":"55"},{"key":"days","value":"2"},{"key":"type","value":"sunset"},{"key":"timezone","value":"-3"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"726"},{"key":"Cache-Control","value":"private"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Etag","value":"W/\"2d6-luSW4SMv4GBATKDwTQW6qszNiXg\""},{"key":"Function-Execution-Id","value":"ml9t8oedppc7"},{"key":"Server","value":"Google Frontend"},{"key":"Strict-Transport-Security","value":"max-age=31556926"},{"key":"X-Cloud-Trace-Context","value":"af699b7d7d0a688ae9d5ec7bb45190fc"},{"key":"X-Country-Code","value":"US"},{"key":"X-Powered-By","value":"Express"},{"key":"X-Ratelimit-Limit","value":"100"},{"key":"X-Ratelimit-Remaining","value":"94"},{"key":"X-Ratelimit-Reset","value":"1732463702"},{"key":"Accept-Ranges","value":"bytes"},{"key":"Date","value":"Sun, 24 Nov 2024 15:54:55 GMT"},{"key":"X-Served-By","value":"cache-iad-kcgs7200023-IAD"},{"key":"X-Cache","value":"MISS"},{"key":"X-Cache-Hits","value":"0"},{"key":"X-Timer","value":"S1732463695.440806,VS0,VE413"},{"key":"Vary","value":"cookie,need-authorization, x-fh-requested-host, accept-encoding"},{"key":"alt-svc","value":"h3=\":443\";ma=86400,h3-29=\":443\";ma=86400,h3-27=\":443\";ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"time\": \"2024-11-24T15:54:55.708Z\",\n \"location\": {\n \"latitude\": -21.83,\n \"longitude\": 55\n },\n \"grid_location\": {\n \"latitude\": -21.5,\n \"longitude\": 55\n },\n \"data\": [\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.35,\n \"cloud_cover\": 0.86,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-24T14:45:00.000Z\",\n \"direction\": 247.4,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-24T15:05:00.000Z\",\n \"2024-11-24T15:16:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-24T14:33:00.000Z\",\n \"2024-11-24T15:00:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.41,\n \"cloud_cover\": 0.43,\n \"quality_text\": \"Good\",\n \"time\": \"2024-11-25T14:46:00.000Z\",\n \"direction\": 247.1,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-25T15:06:00.000Z\",\n \"2024-11-25T15:17:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-25T14:34:00.000Z\",\n \"2024-11-25T15:01:00.000Z\"\n ]\n }\n }\n ]\n}"},{"id":"ed6a0c77-df4a-4667-ab83-efc8340e2a04","name":"partially_no_model_data","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{key}}","type":"text"}],"url":{"raw":"https://api.sunsethue.com/forecast?latitude=-21.83&longitude=55&days=5&type=sunset","host":["https://api.sunsethue.com"],"path":["forecast"],"query":[{"key":"latitude","value":"-21.83"},{"key":"longitude","value":"55"},{"key":"days","value":"5"},{"key":"type","value":"sunset"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"1495"},{"key":"Cache-Control","value":"private"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Etag","value":"W/\"5d7-+qnpYTs8RqPfZ7jWSG4AZ6y6Us0\""},{"key":"Function-Execution-Id","value":"ml9t9c7ybd8o"},{"key":"Server","value":"Google Frontend"},{"key":"Strict-Transport-Security","value":"max-age=31556926"},{"key":"X-Cloud-Trace-Context","value":"e994642186a8d5e4c72b1f6fc4e5f72f;o=1"},{"key":"X-Country-Code","value":"US"},{"key":"X-Powered-By","value":"Express"},{"key":"X-Ratelimit-Limit","value":"100"},{"key":"X-Ratelimit-Remaining","value":"99"},{"key":"X-Ratelimit-Reset","value":"1732463778"},{"key":"Accept-Ranges","value":"bytes"},{"key":"Date","value":"Sun, 24 Nov 2024 15:56:09 GMT"},{"key":"X-Served-By","value":"cache-iad-kcgs7200024-IAD"},{"key":"X-Cache","value":"MISS"},{"key":"X-Cache-Hits","value":"0"},{"key":"X-Timer","value":"S1732463767.246186,VS0,VE2259"},{"key":"Vary","value":"cookie,need-authorization, x-fh-requested-host, accept-encoding"},{"key":"alt-svc","value":"h3=\":443\";ma=86400,h3-29=\":443\";ma=86400,h3-27=\":443\";ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"time\": \"2024-11-24T15:56:09.199Z\",\n \"location\": {\n \"latitude\": -21.83,\n \"longitude\": 55\n },\n \"grid_location\": {\n \"latitude\": -21.5,\n \"longitude\": 55\n },\n \"data\": [\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.35,\n \"cloud_cover\": 0.86,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-24T14:45:00.000Z\",\n \"direction\": 247.4,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-24T15:05:00.000Z\",\n \"2024-11-24T15:16:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-24T14:33:00.000Z\",\n \"2024-11-24T15:00:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.41,\n \"cloud_cover\": 0.43,\n \"quality_text\": \"Good\",\n \"time\": \"2024-11-25T14:46:00.000Z\",\n \"direction\": 247.1,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-25T15:06:00.000Z\",\n \"2024-11-25T15:17:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-25T14:34:00.000Z\",\n \"2024-11-25T15:01:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": true,\n \"quality\": 0.32,\n \"cloud_cover\": 0.55,\n \"quality_text\": \"Fair\",\n \"time\": \"2024-11-26T14:47:00.000Z\",\n \"direction\": 246.9,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-26T15:07:00.000Z\",\n \"2024-11-26T15:18:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-26T14:35:00.000Z\",\n \"2024-11-26T15:01:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": false,\n \"time\": \"2024-11-27T14:47:00.000Z\",\n \"direction\": 246.7,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-27T15:08:00.000Z\",\n \"2024-11-27T15:19:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-27T14:35:00.000Z\",\n \"2024-11-27T15:02:00.000Z\"\n ]\n }\n },\n {\n \"type\": \"sunset\",\n \"model_data\": false,\n \"time\": \"2024-11-28T14:48:00.000Z\",\n \"direction\": 246.5,\n \"magics\": {\n \"blue_hour\": [\n \"2024-11-28T15:08:00.000Z\",\n \"2024-11-28T15:19:00.000Z\"\n ],\n \"golden_hour\": [\n \"2024-11-28T14:36:00.000Z\",\n \"2024-11-28T15:03:00.000Z\"\n ]\n }\n }\n ]\n}"}],"_postman_id":"c9a81294-6467-470b-8f66-279e806790b8"}],"id":"66952111-8064-4da3-aec4-5327735fb781","description":"The sunsethue endpoints give access to the core feature of the Sunsethue API: the sunrise and sunset forecasts. There are two endpoints you can access:
/event to access Sunsethue's forecast and all relevant metadata for a single event
/forecast to access multiple events
The technical details about the Sunsethue model are subject to change. Changes will not affect the structure of the API.
\nData source: ICON (DWD)
\nResolution: 0.5° x 0.5°
Runs: 00z, 06z, 12z, 18z (daily at resp. 05:40, 10:20, 16:40, 22:20 UTC)
Timestep spacing 2h
Interpolation: only between timesteps
\nForecast horizon: 78h (06z, 18z only update first 28h)
Data retention: 7 days
An event is a single sunrise or sunset for a single location and a given date. Every event consists of a json object event_data that contains all relevant data:
quality, quality_text and cloud_cover will only be present if model_data=true.
When is there model_data?
Since not all properties of the event object are present if model_data is false it is useful to know when there will be no model_data?
Sunsethue forecasts are made for up to three days in the future. They are updated every day at 8-9 UTC and18-19 UTC.The last forecasts are stored for 7 days. So data can be accessed between seven days in the past and three days in the future.
Sunsethue forecasts are only available for locations between 55°S and 70°N.
Lastly, the model_data could be false due to issues at Sunsethue or the weather data provider.
Defining quality_text
Defining magics object
The number of credits per request to the Sunsethue endpoints depend on the number of events retrieved and on model_data.
If model_data is false: 1 credit per event
If model_data is true: 5 credits per event
Example: if you make a request using the /forecast endpoint for 6 events, for which 4 have model_data, (4 x 5) + (2 x 1) = 22 credits are added to your daily total.