mirror of
https://bitbucket.org/akapribot/owm-japis.git
synced 2025-04-25 07:17:11 -07:00
2.5.0.2 is ready! All found bugs are fixed. A better README file. And more to come soon.
This commit is contained in:
Ashutosh Kumar Singh
parent
0e90f5dcda
commit
135ff2bf74
10 changed files with 295 additions and 185 deletions
199
README.md
199
README.md
|
|
@ -2,34 +2,46 @@
|
|||
|
||||
####Java APIs for OpenWeatherMap.org
|
||||
|
||||
OWM JAPIs lets you easily access information about current weather, weather forecasts,
|
||||
daily forecasts, etc. directly from OpenWeatherMap.org by providing direct, easy-to-configure, and
|
||||
easy-to-use APIs written in Java.
|
||||
Create weather-aware applications for **Java and Android platforms** in minimum time using this easy-to-use, detailed and documented API library for retrieving weather data from OpenWeatherMap.org.
|
||||
|
||||
You can use this library to create weather applications using Java.
|
||||
OWM JAPIs lets you **get weather data in just 3-5 lines of code** (excluding any other/skeleton code, of course). You can develop applications for multiple platforms using this library, such as Windows, Mac OS X and Linux (by creating Java applications), and Android.
|
||||
|
||||
|
||||
|
||||
###Why to use OWM JAPIs?
|
||||
1. Free
|
||||
2. Easy to use
|
||||
3. Minimizes your code
|
||||
|
||||
OWM JAPIs lets you **focus only on your application code** and weather retrieval code is already there. Additionally, weather retrieval code becomes short and simple using this library – as less as 3-5 lines of code can get you weather data from OpenWeatherMap.org in your Java or Android application. **Don't believe? Have a look on the example below.**
|
||||
|
||||
|
||||
|
||||
##Downloads
|
||||
Kindly download the library's binaries from [OWM APIs Downloads](http://go.aksingh.net/owm-japis-downloads).
|
||||
Download the library's source and binaries from [OWM JAPIs Downloads][1].
|
||||
|
||||
|
||||
|
||||
##Versions
|
||||
###2.5 (Compatible with OWM APIs v2.5)
|
||||
###2.5 (Compatible with OpenWeatherMap.org's API v2.5)
|
||||
|
||||
|
||||
####2.5.0.1 (latest)
|
||||
####2.5.0.2 (latest)
|
||||
|
||||
**Bug-fix version:**
|
||||
1. Fixed bugs which caused wrong parsing of date and time.
|
||||
2. Improved code formatting and readability (for developers).
|
||||
|
||||
|
||||
####2.5.0.1
|
||||
|
||||
**Implemented:**
|
||||
|
||||
1. Current Weather
|
||||
2. Weather Forecasts
|
||||
3. Daily Forecasts
|
||||
4. Wind degree to direction converter
|
||||
|
||||
**Not implemented (planned):**
|
||||
|
||||
**Not implemented but planned:**
|
||||
1. Searching of City
|
||||
2. Weather Maps
|
||||
3. Country code to name converter
|
||||
|
|
@ -37,80 +49,147 @@ Kindly download the library's binaries from [OWM APIs Downloads](http://go.aksin
|
|||
|
||||
|
||||
|
||||
##Why to use OWM JAPIs?
|
||||
1. Free
|
||||
2. Easy to use
|
||||
3. Minimize your code
|
||||
4. Lessen your efforts
|
||||
|
||||
Using OWM JAPIs, you only need to focus on your application and its user interface, and you can just leave
|
||||
the work of accessing weather and forecast data from OpenWeatherMap.org on this library. This reduces code
|
||||
in your program and improves the readability and performance of your code.
|
||||
|
||||
|
||||
|
||||
##How to use OWM JAPIs?
|
||||
Add OWM_JAPIs.jar and JSON.jar to your project's libararies directory, and then, code this way:
|
||||
Anyone with little coding knowledge of Java will feel at home while using this library. **Identifiers are written to be self-explanatory and APIs' documentation** is also provided. It makes the coding process very easy, even for beginners.
|
||||
|
||||
1. Create and initialize object of OpenWeatherMap
|
||||
2. Call this object's functions to get desired data (current weather, forecast, etc.)
|
||||
3. This object's functions returns desired data in a new object
|
||||
4. Call this new object's functions to get information about weather
|
||||
1. Add these two JAR files in your project's libraries:
|
||||
1. OWM_JAPIs.jar
|
||||
2. JSON.jar
|
||||
2. Write your code as such:
|
||||
1. Create and initialize object {obj1} of "OpenWeatherMap" class
|
||||
2. Call this object's {obj1} functions to get the desired weather data (such as current weather, weather forecast, etc.).
|
||||
3. The data is returned as a new object {obj2} of a compatible class based on the type of asked weather data (current weather data comes in a different class's object than weather forecast data).
|
||||
3. Call this returned object's {obj2} functions to get the required information from the collective weather data (such as temperature, pressure, wind speed, etc.).
|
||||
|
||||
Using OWM JAPIs is very simple, and anyone with little coding knowledge will feel at home while making use
|
||||
of this library. Identifiers are written to be self-explanatory and java documentation is also provided.
|
||||
Kindly have a look on the example below for a clear understanding.
|
||||
|
||||
|
||||
|
||||
##Example
|
||||
### Basic Example
|
||||
####Source Code
|
||||
|
||||
import java.io.IOException;
|
||||
import java.net.MalformedURLException;
|
||||
import net.aksingh.java.api.owm.CurrentWeatherData;
|
||||
import net.aksingh.java.api.owm.OpenWeatherMap;
|
||||
import org.json.JSONException;
|
||||
|
||||
public class OwmJapisExample1 {
|
||||
|
||||
public static void main(String[] args)
|
||||
throws IOException, MalformedURLException, JSONException {
|
||||
|
||||
// declaring object of "OpenWeatherMap" class
|
||||
OpenWeatherMap owm = new OpenWeatherMap("");
|
||||
|
||||
// getting current weather data for the "London" city
|
||||
CurrentWeatherData cwd = owm.currentWeatherByCityName("London");
|
||||
|
||||
//printing city name from the retrieved data
|
||||
System.out.println("City: " + cwd.getCityName());
|
||||
|
||||
// printing the max./min. temperature
|
||||
System.out.println("Temperature: " + cwd.getMainData_Object().getMaxTemperature()
|
||||
+ "/" + cwd.getMainData_Object().getMinTemperature() + "\'F");
|
||||
}
|
||||
}
|
||||
|
||||
####Output
|
||||
|
||||
City: London
|
||||
Temperature: 73.4/68.72 'F
|
||||
|
||||
|
||||
###Advance Example
|
||||
You can simply use the APIs (as given in basic example) for learning, testing or experimenting with the functions provided in this library. But it's not good enough for a production or enterprise environment.
|
||||
|
||||
Professionally, you should always **write code which can handle errors/exceptions** at the runtime. OWM JAPIs solves this problem too – by providing checker functions which allows you to **check if a data is available or not**, i.e., that particular data is retrieved and parsed properly or not. Of course, exception handling can still be used, but these functions are really useful and make the data-error-handling task very simple.
|
||||
|
||||
Using OWM JAPIs, you can always check if a particular data is available or not. This is done by using the **has<data-name>()** functions. For example, **hasResponseCode()** function checks if the retrieved data has a response code or not; and if available, response code can be used to check if the whole data was downloaded and parsed correctly or not, as shown below in the example.
|
||||
|
||||
####Source Code
|
||||
|
||||
import java.io.IOException;
|
||||
import java.net.MalformedURLException;
|
||||
import net.aksingh.java.api.owm.CurrentWeatherData;
|
||||
import net.aksingh.java.api.owm.OpenWeatherMap;
|
||||
import org.json.JSONException;
|
||||
|
||||
public class OwmJapisTest {
|
||||
|
||||
public static void main(String[] args)
|
||||
throws IOException, MalformedURLException, JSONException {
|
||||
|
||||
// declaring object of "OpenWeatherMap" class
|
||||
OpenWeatherMap owm = new OpenWeatherMap("");
|
||||
|
||||
// getting current weather data for the "London" city
|
||||
CurrentWeatherData cwd = owm.currentWeatherByCityName("London");
|
||||
|
||||
// checking data retrieval was successful or not using the response code
|
||||
// response code = 200 means successful retrieval
|
||||
if (cwd.hasResponseCode() && cwd.getResponseCode() == 200) {
|
||||
|
||||
// checking if city name is available
|
||||
if (cwd.hasCityName()) {
|
||||
//printing city name from the retrieved data
|
||||
System.out.println("City: " + cwd.getCityName());
|
||||
}
|
||||
|
||||
// checking if max. temp. and min. temp. is available
|
||||
if (cwd.getMainData_Object().hasMaxTemperature() && cwd.getMainData_Object().hasMinTemperature()) {
|
||||
// printing the max./min. temperature
|
||||
System.out.println("Temperature: " + cwd.getMainData_Object().getMaxTemperature()
|
||||
+ "/" + cwd.getMainData_Object().getMinTemperature() + "\'F");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
####Output
|
||||
|
||||
City: London
|
||||
Temperature: 73.4/68.72 'F
|
||||
|
||||
|
||||
|
||||
##Source code
|
||||
Kindly get the library's source code from [OWM APIs Source](http://go.aksingh.net/owm-japis-src).
|
||||
Download the library's source code from [OWM JAPIs Source][2].
|
||||
|
||||
|
||||
|
||||
##Bugs / Requests
|
||||
Got a problem, error, or bug in the library? Or want a new feature that's not there in OWM JAPIs?
|
||||
Got a problem, error or bug in the library? Or want a new feature that's not present in OWM JAPIs?
|
||||
|
||||
Let me know about it, and I will try to solve/add it in the next release.
|
||||
|
||||
Kindly post bugs or feature requests at [OWM APIs Bugs/Requests](http://go.aksingh.net/owm-japis-bugs).
|
||||
Kindly post bugs or feature requests at [OWM JAPIs Bugs/Requests][3] and I will try to solve/add it in the next release.
|
||||
|
||||
|
||||
|
||||
##Developer
|
||||
**Ashutosh Kumar Singh**
|
||||
|
||||
Homepage: [AKSingh.net](http://www.aksingh.net)
|
||||
|
||||
Email: me@aksingh.net
|
||||
**Ashutosh Kumar Singh** | [AKSingh.net][4] | me@aksingh.net
|
||||
|
||||
|
||||
|
||||
##Credits
|
||||
1. OpenWeatherMap.org
|
||||
|
||||
1. [OpenWeatherMap.org][5]
|
||||
for providing free weather data and creating easy-to-use web APIs.
|
||||
|
||||
2. [JSON.org][6]
|
||||
for providing such a great data interchange language and its implementation in Java.
|
||||
|
||||
|
||||
|
||||
##License
|
||||
Copyright (C)2013 Ashutosh Kumar Singh [me@AKSingh.net]
|
||||
Copyright (c) 2013-2014 Ashutosh Kumar Singh [me@AKSingh.net]
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included
|
||||
in all copies or substantial portions of the Software.
|
||||
Released under the terms of [MIT license][7]. It's open source and developer-friendly.
|
||||
|
||||
The Software shall be used for Good, not Evil.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
||||
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
||||
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
||||
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
||||
OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
[1]: http://go.aksingh.net/owm-japis-downloads
|
||||
[2]: http://go.aksingh.net/owm-japis-src
|
||||
[3]: http://go.aksingh.net/owm-japis-bugs
|
||||
[4]: http://www.aksingh.net/
|
||||
[5]: http://openweathermap.org/
|
||||
[6]: http://www.json.org/java/index.html
|
||||
[7]: http://opensource.org/licenses/MIT
|
||||
Loading…
Add table
Add a link
Reference in a new issue