Serenum Wiki

Show or hide the roadmapIntroductionDownload the filesGet the API keyGet the weather dataGet startedError codesIssues? 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

  1. Clone the repository at Codeberg or download the ZIP or TAR.GZ file from the same place.
  2. If you downloaded the compressed file, extract the files to the root of your web server.
  3. 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.

  1. Create an account if you don't already have one at openweathermap.org.
  2. When you've logged in, choose "API key" in the top menu. If you don't have any keys, create one below "Create key".
  3. Method 1: Copy the API key and replace it with [your-api-key] for the variable $apikey in both index.php and diff.php.
  4. 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]
ParameterRequiredDescription
latitude & longitudeYesGeographical coordinates.
apikeyYesYour own API key from OpenWeatherMap.
excludeNoExclude 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 (*).

apikeyShows the entered API key.
latitudeGeographical coordinates of the place in latitude (truncated to 5 digits).
longitudeGeographical coordinates of the place in longitude (truncated to 5 digits).
* . twentyfourhoursShows the time in 24h format for the chosen place.
* . twelvehoursShows the time in 12h format for the chosen place.
* . cloudsCloud cover in percentage (%)
* . humidityHumidity in percentage (%)
prob_precipThe 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 codeDescription
110The 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.
140The 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).
150The 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.
160The 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.
170At least 1 excluded variable are missing in the URL. See "Get started" for more information.
200The 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.