OpenWeather Connector

Instructions to use OpenWeatherConnector

1. Obtain an API key from OpenWeathermap.org by signing up for a free account. This will automatically create an API key that you can copy from your account page (you can create additional keys if you wish).
2. In the src/main/resources/ directory, copy apikeys.json-TEMPLATE to apikeys.json and then open apikeys.json for editing. In the line that has

     "openweathermap": ""

   insert your API key inside the blank quotes, for example:

     "openweathermap": "0123456789abcdeffedcba9876543210"

   • Do NOT rename apikeys.json-TEMPLATE as apikeys.json, or you will cause apikeys.json, with your API key, to be present in your repository, despite the src/main/resources/.gitignore entry that is meant to prevent this.
   • Do NOT place your API key in apikeys.json-TEMPLATE, or you will cause your API key to be present in your repository.
3. You may wish to review edu.unl.cse.soft160.json_connections.Demonstration to see example uses of OpenWeatherConnector.
4. When creating an OpenWeatherConnector object, if it should connect to the local file system, then use the single-argument constructor, using "weather", "onecall", "forecast", "air_pollution", "air_pollution/history", or "air_pollution/forecast" as the argument (or another subdirectory of src/main/resources/ that is named after one of the data sets provided by the OpenWeather API).
5. When creating an OpenWeatherConnector object, if it should connect to the OpenWeathermap.org RESTful service, use the two-argument constructor. The first argument needs to be one of the data sets provided by the OpenWeather API, and the second argument needs to be the user's API key. Do not hard-code an API key. Instead, Call RestConnection.getApiKey("openweathermap") to obtain the API key from apikeys.json or prompt the user to enter their API key.
6. You must invoke an OpenWeatherConnector object's retrieveData(String) method before invoking any of its other non-constructor methods to obtain the data that the other methods will use. You may make additional calls to retrieveData(String) to replace the data with other data.
   • retrieveData(String)'s argument specifies the data to be used.
   • If the OpenWeatherConnector instance is connected to the local file system, then the argument is the name of the file to be loaded.
   • If the OpenWeatherConnector instance is connected to OpenWeathermap.org RESTful service, then the argument is the query string to be sent to the RESTful service. See the OpenWeather API specification for details.
     • Pay particular attention to option to specify the system of measurements in the query, and which data are available only in one unit of measure.
     • Here are links to the query details for specific data sets:
       • "weather", the current weather data set
       • "onecall", the "One Call API" data set
       • forecast, the 5-day/3-hour forecast data set
       • air_pollution, the air quality and pollution data set
         • Includes air_pollution/forecast and air_pollution/history
7. The remaining OpenWeatherConnector methods provide typed values for the JSON fields in the data loaded by retrieveData(String).

Use in Your Project

JavaDoc

You can generate the JavaDoc pages for publicly-accessible elements by invoking the javadoc:javadoc Maven target from your IDE or from the command line:

mvn javadoc:javadoc

Open the file target/site/apidocs/index.html in your web browser to use the JavaDoc pages.

Copying files into your project

If you copy the classes and interface from this project into your own, be sure that:

• You copy the fields into the same directories, i.e.:
  • src/main/java/edu/unl/cse/soft160/json_connections/connection/Connection.java
  • src/main/java/edu/unl/cse/soft160/json_connections/connection/FileConnection.java
  • src/main/java/edu/unl/cse/soft160/json_connections/connection/RestConnection.java
  • src/main/java/edu/unl/cse/soft160/json_connections/connector/OpenWeatherConnector.java
  • src/main/resources/apikeys-TEMPLATE.json
  • src/main/resources/.gitignore (this file prevents apikeys.json from being committed to your repository)
• Your pom.xml file specifies the appropriate plugins and dependencies
  • Your pom.xml file specifies Java version 11 or later

    <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
           <source>11</source>
           <target>11</target>
        </configuration>
    </plugin>

  • Your pom.xml file includes a dependency for JSON.simple

    <dependency>
        <groupId>com.googlecode.json-simple</groupId>
        <artifactId>json-simple</artifactId>
        <version>1.1.1</version>
     </dependency>

Limitations

• OpenWeatherConnector only supports the free, no-cost APIs provided by OpenWeathermap.org. We do not have plans to support the subscription-based APIs.
• We do not currently access the NWS alerts from the onecall dataset but will do so soon.
• We not currently support the onecall/timemachine dataset but will do so soon.
• We may access sunset, sunrise, moonset, moonrise, and moon phase if it's needed.
• We may add support for the Geocoding API ("direct" and "reverse" data sets).
• We do not anticipate supporting the Weather Stations API nor the Weather Triggers API, as they are not needed for our intended use of OpenWeatherConnector. (Also, RestConnection does not (yet) support PUSH and PUT calls, which would be required for those APIs.)
• Three-hour rain (and three-hour snow) total defaults to the 1-hour rain (snow) when a separate 3-hour value is not reported. Recent real-world data calls into question the assumption that a 3-hour value will be reported when rain has fallen for more than an hour (or even more than three hours)

JSON Connections for Files and REST APIs

REpresentational State Transfer APIs (also known as REST APIs, RESTful APIs, or RESTful web services) are a mechanism to request data from and send data to remote servers without maintaining active, stateful connections over a possibly-unreliable network. The edu.unl.cse.soft160.json_connections.connection.RestConnection class is sufficient to request data from a RESTful service.

The edu.unl.cse.soft160.json_connections.connection.FileConnection class offers the same interface for requesting data, except that the data will be found on the local file system. FileConnection can also save data to a file which can be used to save data retrieved from a server using RestConnection to be used later.

The edu.unl.cse.soft160.json_connections.connector.OpenWeatherConnector class provides a wrapper for RestConnection and FileConnection to simplify client code that uses data from OpenWeathermap.org.

In a typical project, you should only need to directly use OpenWeatherConnector.