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.
Usage
To evaluate your usage, you can go to the API portal where you can view your quota and usage for this day (since 0UTC). Paying users can see their usage for the past 30 days.
Alternatively, you can use the /usage endpoint. This endpoint takes no arguments (besides your API key) and does not cost any credits. The response is formatted like this (where the usage and quota are expressed as number of credits):
{\n \"daily_usage\": 140,\n \"daily_quota\": 1000,\n \"plan\": \"paying\",\n \"time\": \"2026-06-12T19:11:48.963Z\"\n}\n\nIf 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.
\nModel: Sunsethue ray-based v3
\nData source: ICON (DWD)
\nResolution: 0.25° x 0.25°
Runs: 00z, 06z, 12z, 18z (daily at resp. 04:30, 10:30, 16:30, 22:30 UTC)
Forecast horizon: 78h
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, updated four times per day with new input data. The past 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.