Capital Weather Overview

Capital Weather is a sample Bluemix application which utilizes the Weather Channel service, two mapping APIs, Leaflet and Esri Leaflet, and the Google Maps Geocoding API. It allows users to visualize the current weather in all the world capitals, as well as obtain historical weather data and future weather projections. The app provides a real world use case of the Weather Channel API and implements several of the methods exposed by that interface.

The application is built to interface with the Insights for Weather service on Bluemix or the full TWC API. It will dynamically adjust the capabilities available in the UI based on which service is being used.

Running the app on Bluemix

If you do not already have a Bluemix account, sign up here
Download and install the Cloud Foundry CLI tool
Clone the app to your local environment from your terminal using the following command:
```
git clone https://github.com/IBM-Bluemix/capital-weather.git
```
cd into this newly created directory
Open the manifest.yml file and change the host value to something unique.

The host you choose will determinate the subdomain of your application's URL: <host>.mybluemix.net
Connect to Bluemix in the command line tool and follow the prompts to log in.
```
$ cf api https://api.ng.bluemix.net
$ cf login
```

Create the Weather Channel service in Bluemix.

$ cf create-service weatherinsights Free-v2 capital-weather-data

Push the app to Bluemix.
```
$ cf push
```

And voila! You now have your very own instance of Capital Weather running on Bluemix.

Run the app locally

If you do not already have a Bluemix account, sign up here
If you have not already, download node.js and install it on your local machine.
Clone the app to your local environment from your terminal using the following command:
```
git clone https://github.com/IBM-Bluemix/capital-weather.git
```
cd into this newly created directory
Install the required npm and bower packages using the following command
```
npm install
```
Create a Weather Channel service using your Bluemix account and replace the corresponding credentials in your vcap-local.json file. You must then delete the user-provided service object.
Start your app locally with the following command
```
npm run watch
```

This command will trigger cake to build and start your application. When your app has started, your console will print that your server started on: http://localhost:6003.

Since we are using cake, the app is rebuilt continuously as changes are made to the local file system. Therefore, you do not have to constantly stop and restart your app as you develop locally. Execute npm run cake to see the other commands available in the Cakefile.

Using the Full TWC API

Bluemix provides access to the Insights for Weather service, an API exposing a several core Weather Co capabilities. As can be seen in this repo's live demo, additional historical data is available using the full TWC API. If you have API credentials for this API, complete the above steps and then follow the steps below to implement ths functionality.

On Bluemix

Create a user-provided service to represent the full TWC API

$ cf cups weather-service -p '{"url":"http://   api.weather.com","apiKey":"API_KEY"}'

Bind this new service to your existing Capital Weather app
```
$ cf bind-service capital-weather weather-service
```
Restage your app so that this new service supercedes the existing Insights for Weather service
```
$ cf restage capital-weather
```

Locally

Replace the contents of your vcap-local.json file with the following:

{
  "services": {
    "user-provided": [
      {
        "name":  "weather-service",
        "credentials": {
          "apiKey": "API_KEY",
          "url":    "http://api.weather.com"
        }
      }
    ]
  }
}

Replace API_KEY with your provided TWC API key.

Restage your application
```
$ npm run watch
```

Decomposition Instructions

The primary purpose of this demo is to provide a sample implementation of the Weather Channel API. The relevant code for this integration is located within the lib/weatherService.js file and has been extracted into several source gists. All helper functions are also included in the gists for reference. This section details the callback functions created to call this API.

Current Conditions

A callback function for getting the current weather conditions for the input latitude/longitude value. Utilizes the current method of the Weather Channel API.

Past Conditions

A callback function for getting the weather conditions on a prior date for the input latitude/longitude value. This function leverages the getOneHC helper method. Utilizes the historical method of the Weather Channel API.

Historical Conditions

A callback function for getting weather conditions for the past ten years on the current date for the input latitude/longitude value. This function makes several calls to the getOneHC helper method. Utilizes the historical method of the Weather Channel API.

API documentation

This sample application was built with developer reusability in mind. For ease of use, I have created Swagger UI API documentation for the algorithms built into this sample app. The API is currently rate limited, so please use it sparingly.

Troubleshooting

The primary source of debugging information for your Bluemix app is the logs. To see them, run the following command using the Cloud Foundry CLI:

  $ cf logs capital-weather --recent

For more detailed information on troubleshooting your application, see the Troubleshooting section in the Bluemix documentation.

Contribute

We are more than happy to accept external contributions to this project, be it in the form of issues and pull requests. If you find a bug, please report it via the Issues section or even better, fork the project and submit a pull request with your fix! Pull requests will be evaulated on an individual basis based on value add to the sample application.

Credit

3rdculturekid - weather loading gif [source]
designmodo - historical weather data icon [source][license]
Lin Pham - past and future weather data icons [source]

Privacy Notice

The capital-weather sample web application includes code to track deployments to Bluemix and other Cloud Foundry platforms. The following information is sent to a Deployment Tracker service on each deployment:

Application Name (application_name)
Space ID (space_id)
Application Version (application_version)
Application URIs (application_uris)

This data is collected from the VCAP_APPLICATION environment variable in IBM Bluemix and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Bluemix. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.

Disabling Deployment Tracking

Deployment tracking can be disabled by removing require("cf-deployment-tracker-client").track(); from the beginning of the app.js file.

IBM-Cloud / capital-weather

readme