weather/README.md

Using the OpenWeatherClient Library

To integrate weather data into your application using the ohrionmartin/weather package, follow these steps:

1. Add the Repository and Dependency

Update your composer.json file to include the custom repository and require the ohrionmartin/weather package:

"repositories": [
    {
        "type": "vcs",
        "url": "https://git.nampharm.com.na/ohrionmartin/weather"
    }
],
"require": {
    "ohrionmartin/weather": "dev-master"
}

Then run:

composer update

2. Configure the API Key

Ensure you have an API key from OpenWeatherMap. Add it to your .env file:

OPENWEATHER_API_KEY=your_api_key_here

3. Add Weather Route

In your application (e.g., in routes.php or equivalent), add the following route to handle weather requests:

use GuzzleHttp\Client;
use Illuminate\Http\Request;
use Ohrionmartin\Weather\Service\OpenWeatherClient;

$router->get('/weather', function (Request $request) {
    $apiKey = env('OPENWEATHER_API_KEY');
    if (!$apiKey) {
        return response()->json(['error' => 'OPENWEATHER_API_KEY is not configured'], 500);
    }

    $client = new Client();
    $ow = new OpenWeatherClient($client, $apiKey);

    $options = [];
    if ($request->has('units')) {
        $options['units'] = $request->get('units'); // 'standard'|'metric'|'imperial'
    }
    if ($request->has('lang')) {
        $options['lang'] = $request->get('lang');
    }
    if ($request->has('exclude')) {
        $options['exclude'] = $request->get('exclude'); // comma-separated segments
    }

    try {
        if ($request->has('city')) {
            $data = $ow->oneCallByCity((string) $request->get('city'), $options);
        } else {
            if (!$request->has('lat') || !$request->has('lon')) {
                return response()->json(['error' => 'Provide either ?city=Name or ?lat=..&lon=..'], 400);
            }
            $lat = (float) $request->get('lat');
            $lon = (float) $request->get('lon');
            $data = $ow->oneCall($lat, $lon, $options);
        }

        return response()->json($data);
    } catch (\RuntimeException $e) {
        return response()->json(['error' => $e->getMessage()], 502);
    }
});

4. Usage Examples

You can access the weather endpoint with the following query parameters:

• By city name: http://localhost:8080/weather?city=London
• By coordinates: http://localhost:8080/weather?lat=51.5074&lon=-0.1278
• With optional parameters:
  • units: standard, metric, or imperial (e.g., ?units=metric)
  • lang: Language code for response (e.g., ?lang=fr)
  • exclude: Comma-separated segments to exclude (e.g., ?exclude=minutely,hourly)

Example request:

curl "http://localhost:8080/weather?city=London&units=metric&lang=fr"

This will return weather data in JSON format for London in metric units and French language.