03-supported-apis.md

Supported APIs

• APIs
  • One Call
    • getWeather
    • getWeatherByDate
    • getWeatherSummaryByDate
    • getWeatherOverviewByDate
  • AI Assistant
    • startSession
    • resumeSession
  • Weather
    • getCurrent
    • getForecast
  • Air Pollution
    • getCurrent
    • getForecast
    • getHistory
  • Geocoding
    • getByLocationName
    • getByCoordinate
    • getByZipCode
• Common Methods
  • withUnitSystem
  • withLanguage
  • withCacheTtl

APIs

One Call

getWeather

getWeather(float $latitude, float $longitude): Weather

Get access to current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 8 days and government weather alerts.

Returns a Weather object:

$weather = $api->oneCall()->getWeather(50, 50);

getWeatherByDate

getWeatherByDate(float $latitude, float $longitude, \DateTimeInterface $dateTime): WeatherMoment

Get access to weather data for any datetime.

Returns a WeatherMoment object:

$weather = $api->oneCall()->getWeatherByDate(50, 50, new \DateTime('2023-05-13 16:32:00'));

getWeatherSummaryByDate

getWeatherSummaryByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherSummary

Get access to aggregated weather data for a particular date.

Returns a WeatherSummary object:

$weatherSummary = $api->oneCall()->getWeatherSummaryByDate(50, 50, new \DateTime('1985-07-19'));

getWeatherOverviewByDate

getWeatherOverviewByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherOverview

Get the weather overview with a human-readable summary for today and tomorrow's forecast, using OpenWeather AI.

Returns a WeatherOverview object:

$weatherOverview = $api->oneCall()->getWeatherOverviewByDate(50, 50, new \DateTime('today'));

AI Assistant

startSession

startSession(string $prompt): Answer

Start a new session (create a new conversation) with the Weather AI Assistant.

Returns a Answer object:

$answer = $api->assistant()->startSession('How is the weather today in Lisbon?');

resumeSession

resumeSession(string $sessionId, string $prompt): Answer

Resume a session (continue a conversation) with the Weather AI Assistant.

Returns a Answer object:

$answer = $api->assistant()->resumeSession('session-id', 'Do I need an umbrella?');

Weather

getCurrent

getCurrent(float $latitude, float $longitude): Weather

Get access to current weather data.

Returns a Weather object:

$currentWeather = $api->weather()->getCurrent(50, 50);

getForecast

getForecast(float $latitude, float $longitude, int $numResults = 40): WeatherCollection

Get access to 5-day weather forecast data with 3-hour steps.

Returns a WeatherCollection object:

// Since it returns data in 3-hour steps,
// passing 8 as the numResults means it will return results for the next 24 hours
$weatherForecast = $api->weather()->getForecast(50, 50, 8);

Air Pollution

getCurrent

getCurrent(float $latitude, float $longitude): AirPollution

Get access to current air pollution data.

Returns a AirPollution object:

$currentAirPollution = $api->airPollution()->getCurrent(50, 50);

getForecast

getForecast(float $latitude, float $longitude): AirPollutionCollection

Get access to air pollution forecast data per hour.

Returns a AirPollutionCollection object:

$airPollutionForecast = $api->airPollution()->getForecast(50, 50);

getHistory

getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \DateTimeInterface $endDate): AirPollutionCollection

Get access to historical air pollution data per hour between two dates.

Returns a AirPollutionCollection object:

$startDate = new \DateTime('-1 day');
$endDate = new \DateTime('now');

// returns air pollution data for the last 24 hours
$airPollutionHistory = $api->airPollution()->getHistory(50, 50, $startDate, $endDate);

Geocoding

getByLocationName

/**
 * @return Location[]
 */
getByLocationName(string $locationName, int $numResults = 5): array

Get geographical coordinates (latitude, longitude) by using the name of the location (city name or area name).

Returns an array of Location objects.

$locations = $api->geocoding()->getByLocationName('lisbon');

getByCoordinate

/**
 * @return Location[]
 */
getByCoordinate(float $latitude, float $longitude, int $numResults = 5): array

Get the name of the location (city name or area name) by using geographical coordinates (latitude, longitude).

Returns an array of Location objects.

$locations = $api->geocoding()->getByCoordinate(50, 50);

getByZipCode

getByZipCode(string $zipCode, string $countryCode): ZipLocation

Get geographical coordinates (latitude, longitude) by using the zip/postal code.

Returns a ZipLocation object.

$location = $api->geocoding()->getByZipCode('1000-001', 'pt');

Common Methods

withLanguage

withLanguage(string $language): self

Set the language per request. Only available for OneCall and Weather API requests.

use ProgrammatorDev\OpenWeatherMap\Language\Language

// uses the "pt" language for this request alone
$api->weather()
    ->withLanguage(Language::PORTUGUESE)
    ->getCurrent(50, 50);

withUnitSystem

withUnitSystem(string $unitSystem): self

Set the unit system per request. Only available for OneCall and Weather API requests.

use ProgrammatorDev\OpenWeatherMap\UnitSystem\UnitSystem;

// uses the "imperial" unit system for this request alone
$api->weather()
    ->withUnitSystem(UnitSystem::IMPERIAL)
    ->getCurrent(50, 50);

withCacheTtl

withCacheTtl(?int $ttl): self

Makes a request and saves into cache for the provided duration in seconds.

Semantics of values:

• 0, the response will not be cached (if the server specifies no max-age).
• null, the response will be cached for as long as it can (forever).

Note

Setting cache to null or 0 seconds will not invalidate any existing cache.

Available for all APIs if a cache adapter is set. Check the following documentation for more information.

// cache will be saved for 1 hour for this request alone
$api->weather()
    ->withCacheTtl(3600)
    ->getCurrent(50, 50);