Welcome to Eris

Eris is an open source weather API for getting the current weather condition across the globe.

Quick access:


Eris is a simple Spring Boot Java API service that is developed as a consolidation of the following services:

The technology stack solely consists of Spring Boot framework. The live version of the API service is hosted on Red Hat OpenShift. The service can be hosted in any platform that supports Spring Boot.

Feel free to fork the project and create your own private API instance.


All the project dependencies exist in pom.xml file and once you run the project, all dependencies will be downloaded.

API documentation

Eris has two APIs which both do the same thing, getting the current weather condition.

Each API designed for its own use case, though both give the same response.

To access the APIs need to perform get request at the following URLs:


This endpoint is suitable for the case that coordinates (latitude, longitude) are available. To use this API three URL parameters are required which two are compulsory and another one is optional.

The list of parameters with their description can be found below table

Parameter Description Type Compulsory
lat Latitude Decimal
lon Longitude Decimal
fahrenheit Temperature scale, supported Fahrenheit (true) and Celsius (false, default) Boolean

The JSON response of the call is something similar to below:

   "geoLocation":"Suria KLCC, KLCC-Bukit Bintang Pedestrian Walkway, Bukit Bintang, Sentul, KL, 50540, Malaysia",
         "description":"broken clouds",

If none numeric lat and/or lon given to the endpoint, instead of throwing 400 Bad Request, the API returns the following response,

   "errors":["Invalid latitude and/or longitude provided!"],


This point suits when no coordinates are available. As a result, the weather condition retrieved via the caller IP address location. Obviously, compare with the /current, this endpoint has lower accuracy. The reason for this is because coordinates acquired based on IP address which is usually not the same with the user’s location. In most cases, the location of the IP refers to the nearest ISP center that the user is connected to. The API parameters are as follows:

Parameter Description Type Compulsory
fahrenheit Temperature scale, supported Fahrenheit (true) and Celsius (false, default) Boolean

The IP address retrieved automatically from request header and as it can be seen, no parameter is defined to manually determine it. The response of this endpoint is identical with the /current one.


To call the endpoints, you need to send get request with appropriate URL parameters.

The request URL for /current should be something similar to this.


Consequently, the request URL for /currentbyip should be similar to below:


In Unix/Linux, you can use curl command to call the service.

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET 'http://weather-api.madadipouya.com/v1/weather/current?lat=3.15694859&lon=101.7123029&fahrenheit=false'


curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET 'http://weather-api.madadipouya.com/v1/weather/currentbyip?fahrenheit=false'

Deploy your own Eris instance

To run and deploy the project on your local or any desired server, first clone the project and then follow the below instructions.

Free public Eris instance

We have a free running public instance of Eris hosted on Open Shift. The instance is available from the following link:



Authors and Contributors

This API is developed and maintained by Kasra Madadipouya (@kasramp). Anyone is welcome to contribute to this project.


Facing any problems, found bugs or having any inquiries? Just drop an email to kasra@madadipouya.com



Eris Weather API is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

Eris Weather API is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. http://www.gnu.org/licenses/


© 2017 Kasra Madadipouya kasra@madadipouya.com