Serenum API Wiki

Show or hide the roadmap

Introduction Download the files Get the API key Get the weather data Get started Error codes Issues? Contact us

Introduction

With Serenum API, you will get a detailed overview over the current weather and weather forecast for a place. You will also get detailed information about a place's local date and time, including astronomical data like the current positions of the Sun and the Moon. And the best part: Serenum API are completely open sourced and you can install it on your own server!

The API are divided in 2 sections: getting all the data about a single place (index.php), and see the difference between 2 places (diff.php).

Download the files

Clone the repository at Codeberg or download the ZIP or TAR.GZ file from the same place.
If you downloaded the compressed file, extract the files to the root of your web server.
Read the next chapter about how to get API key.

Get the API key

Before you can use Serenum API, you must get your own API key from OpenWeatherMap.

Create an account if you don't already have one at openweathermap.org.
When you've logged in, choose "API key" in the top menu. If you don't have any keys, create one below "Create key".
Method 1: Copy the API key and replace it with [your-api-key] for the variable $apikey in both index.php and diff.php.
Method 2: Append &key=[your-api-key] to domain.com/api?coor=59.38079,13.50239 in your browser.

Important

If you have created a new key or reactivated a key that has been inactivated, it can take some time until you can use the key.

Get the weather data

Now go to https://domain.com/api and follow the instructions which will say that you need to append the coordinates for the place you want to fetch the weather data for. You can get the coordinates for the place by go to OpenStreetMap or use the default ones that the API gives you.

If you choose to get coordinates from OSM, go to the place of choice and right-click on the place and choose "Centre map here". Now copy the coordinates from the URL and append them to domain.com/api or domain.com/api/diff. Follow the example in Serenum API for how it must look like.

Important

Be sure to replace / with , for the coordinates before you continue.

Get started

Serenum API only provides data in JSON.

https://domain.com/?coor=[latitude],[longitude]&key=[apikey]

https://domain.com/diff?coor=[latitude],[longitude];[latitude],[longitude]&key=[apikey]

Parameter	Required	Description
`latitude` & `longitude`	Required Yes	Geographical coordinates.
`apikey`	Required Yes	Your own API key from OpenWeatherMap.
`exclude`	Not required No	Exclude stuff from the API call, seperated with a comma and no spaces. Available values: `place`, `pollen`, `airp`, `astronomy`.

Fields in the API response

Despite the API itself are very self-explainable, there are fields that aren't and those are listed below. Other fields that needs more information are included.

Fields with the same name that can be found on more than 1 place, are listed with a wildcard (*).

`apikey`	Shows the entered API key.
`latitude`	Geographical coordinates of the place in latitude (truncated to 5 digits).
`longitude`	Geographical coordinates of the place in longitude (truncated to 5 digits).
`*` . `twentyfourhours`	Shows the time in 24h format for the chosen place.
`*` . `twelvehours`	Shows the time in 12h format for the chosen place.
`*` . `clouds`	Cloud cover in percentage (%)
`*` . `humidity`	Humidity in percentage (%)
`prob_precip`	The probability of precipitation in percentage (%)
`moon` . `schedules` . `` . `countdown` . ``	How many days, hours, and minutes there are left until the moon phase occures. The countdown goes after the chosen place's date and time.

Info

The astronomical values are only in beta! We've seen that the sun hours and moon hours are not the same as on timeanddate.com. We are working on a solution.

Error codes

When an error occurs in Serenum API, you will get the error code, a message saying what the error means in short, and (depending on the error) 1 or 2 other variable(s) that will help you getting on the right path. All errors are listed below with further explaination.

Error code	Description
Error 110 110	The geographical coordinates (latitude and longitude) are missing in the URL. You need to specify these in order to get the data from OpenWeatherMap. Please see "Get the weather data" for how to get the coordinates for a place.
Error 140 140	The geographical coordinates (latitude and longitude) are not valid. To get a valid latitude och longitude, they need to be 5 or more digits and with `-` and/or `.`. You can get one from OpenStreetMap (see "Get the weather data" to learn how).
Error 150 150	The API key from OpenWeatherMap are missing in the URL. You need to login to your account at openweathermap.org and retrieve your API key from there. See "Get the API key" for more information.
Error 160 160	The API key from OpenWeatherMap are not valid. Go to openweathermap.org and login to your account and either create a new API key or confirm that the entered API key are activated.
Error 170 170	At least 1 excluded variable are missing in the URL. See "Get started" for more information.
Error 200 200	The API were not able to fetch the data from OpenWeatherMap. This can occur if the API key from OSM are not valid based on their standards or not activated.

Issues? Contact us

If you have stumbled upon any issues, feel free to contact us on either Codeberg or Telegram.