docs: updated one call resource related info

Author: andrepimpao

docs/03-supported-apis.md

@@ -31,46 +31,41 @@
 getWeather(float $latitude, float $longitude): OneCall
 ```
 
-Get current and forecast (minutely, hourly and daily) weather data.
+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 [`OneCall`](05-entities.md#onecall) object:
+Returns a [`Weather`](05-entities.md#weather) object:
 
 ```php
-$weather = $openWeatherMap->oneCall()->getWeather(50, 50);
-
-echo $weather->getCurrent()->getTemperature();
+$weather = $api->oneCall()->getWeather(50, 50);
 ```
 
-#### `getHistoryMoment`
+#### `getWeatherByDate`
 
 ```php
-getHistoryMoment(float $latitude, float $longitude, \DateTimeInterface $dateTime): WeatherLocation
+getWeatherByDate(float $latitude, float $longitude, \DateTimeInterface $dateTime): WeatherMoment
 ```
 
-Get weather data from a single moment in the past.
+Get access to weather data for any datetime.
 
-Returns a [`WeatherLocation`](05-entities.md#weatherlocation) object:
+Returns a [`WeatherMoment`](05-entities.md#weathermoment) object:
 
 ```php
-$weather = $openWeatherMap->oneCall()->getHistoryMoment(50, 50, new \DateTime('2023-01-01 12:00:00'));
-
-echo $weather->getTemperature();
+$weather = $api->oneCall()->getWeatherByDate(50, 50, new \DateTime('2023-05-13 16:32:00'));
 ```
 
-#### `getHistoryAggregate`
+#### `getWeatherSummaryByDate`
 
 ```php
-getHistoryAggregate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherAggregate
+getWeatherSummaryByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherSummary
 ```
 
-Get aggregated weather data from a single day in the past.
+Get access to aggregated weather data for a particular date.
 
-Returns a [`WeatherAggregate`](05-entities.md#weatheraggregate) object:
+Returns a [`WeatherSummary`](05-entities.md#weathersummary) object:
 
 ```php
-$weather = $openWeatherMap->oneCall()->getHistoryAggregate(50, 50, new \DateTime('1985-07-19'));
-
-echo $weather->getTemperature();
+$weatherSummary = $api->oneCall()->getWeatherSummaryByDate(50, 50, new \DateTime('1985-07-19'));
 ```
 
 ### Weather
@@ -81,7 +76,7 @@ echo $weather->getTemperature();
 getCurrent(float $latitude, float $longitude): Weather
 ```
 
-Get current weather data.
+Get access to current weather data.
 
 Returns a [`Weather`](05-entities.md#weather-2) object:
 
@@ -95,7 +90,7 @@ $currentWeather = $api->weather()->getCurrent(50, 50);
 getForecast(float $latitude, float $longitude, int $numResults = 40): WeatherCollection
 ```
 
-Get weather forecast for the next 5 days in 3-hour steps.
+Get access to 5-day weather forecast data with 3-hour steps.
 
 Returns a [`WeatherCollection`](05-entities.md#weathercollection) object:
 
@@ -113,7 +108,7 @@ $weatherForecast = $api->weather()->getForecast(50, 50, 8);
 getCurrent(float $latitude, float $longitude): AirPollution
 ```
 
-Get current air pollution data.
+Get access to current air pollution data.
 
 Returns a [`AirPollution`](05-entities.md#airpollution) object:
 
@@ -127,7 +122,7 @@ $currentAirPollution = $api->airPollution()->getCurrent(50, 50);
 getForecast(float $latitude, float $longitude): AirPollutionCollection
 ```
 
-Get air pollution forecast data per hour.
+Get access to air pollution forecast data per hour.
 
 Returns a [`AirPollutionCollection`](05-entities.md#airpollutioncollection) object:
 
@@ -141,7 +136,7 @@ $airPollutionForecast = $api->airPollution()->getForecast(50, 50);
 getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \DateTimeInterface $endDate): AirPollutionCollection
 ```
 
-Get air pollution history data per hour between two dates.
+Get access to historical air pollution data per hour between two dates.
 
 Returns a [`AirPollutionCollection`](05-entities.md#airpollutioncollection) object:
 
@@ -164,7 +159,7 @@ $airPollutionHistory = $api->airPollution()->getHistory(50, 50, $startDate, $end
 getByLocationName(string $locationName, int $numResults = 5): array
 ```
 
-Get locations by location name. 
+Get geographical coordinates (latitude, longitude) by using the name of the location (city name or area name). 
 
 Returns an array of [`Location`](05-entities.md#location) entities.
 
@@ -181,7 +176,7 @@ $locations = $api->geocoding()->getByLocationName('lisbon');
 getByCoordinate(float $latitude, float $longitude, int $numResults = 5): array
 ```
 
-Get locations by coordinate. 
+Get name of the location (city name or area name) by using geographical coordinates (latitude, longitude). 
 
 Returns an array of [`Location`](05-entities.md#location) entities.
 
@@ -195,7 +190,7 @@ $locations = $api->geocoding()->getByCoordinate(50, 50);
 getByZipCode(string $zipCode, string $countryCode): ZipLocation
 ```
 
-Get location by zip code. 
+Get geographical coordinates (latitude, longitude) by using the zip/postal code. 
 
 Returns a [`ZipLocation`](05-entities.md#ziplocation) object.
 

docs/05-entities.md

@@ -1,12 +1,16 @@
 # Entities
 
 - [One Call](#one-call)
-  - [Alert](#alert)
-  - [MinuteForecast](#minuteforecast)
-  - [OneCall](#onecall)
   - [Weather](#weather)
-  - [WeatherAggregate](#weatheraggregate)
-  - [WeatherLocation](#weatherlocation)
+  - [WeatherMoment](#weathermoment)
+  - [WeatherSummary](#weathersummary)
+  - [WeatherData](#weatherdata)
+  - [MinuteData](#minutedata)
+  - [HourData](#hourdata)
+  - [DayData](#daydata)
+  - [Alert](#alert)
+  - [MoonPhase](#moonphase)
+  - [Temperature](#temperature)
 - [Weather](#weather-1)
   - [Weather](#weather-2)
   - [WeatherCollection](#weathercollection)
@@ -30,54 +34,41 @@
 
 ## One Call
 
-### Alert
-
-- `getSenderName()`: `string`
-- `getEventName()`: `string`
-- `getStartsAt()`: `\DateTimeImmutable`
-- `getEndsAt()`: `\DateTimeImmutable`
-- `getDescription()`: `string`
-- `getTags()`: `array`
-
-### MinuteForecast
-
-- `getDateTime()`: `\DateTimeImmutable`
-- `getPrecipitation()`: `float`
-
-### OneCall
+### Weather
 
 - `getCoordinate()`: [`Coordinate`](#coordinate)
 - `getTimezone()`: [`Timezone`](#timezone)
-- `getCurrent()`: [`Weather`](#weather)
-- `getMinutelyForecast()`: [`?MinuteForecast[]`](#minuteforecast)
-- `getHourlyForecast()`: [`Weather[]`](#weather)
-- `getDailyForecast()`: [`Weather[]`](#weather)
+- `getCurrent()`: [`WeatherData`](#weatherdata)
+- `getMinutelyForecast()`: [`?MinuteData[]`](#minutedata)
+- `getHourlyForecast()`: [`HourData[]`](#hourdata)
+- `getDailyForecast()`: [`DayData[]`](#daydata)
 - `getAlerts()`: [`?Alert[]`](#alert)
 
-### Weather
+### WeatherMoment
 
+- `getCoordinate()`: [`Coordinate`](#coordinate)
+- `getTimezone()`: [`Timezone`](#timezone)
 - `getDateTime()`: `\DateTimeImmutable`
-- `getSunriseAt()`: `?\DateTimeImmutable`
-- `getSunsetAt()`: `?\DateTimeImmutable`
-- `getMoonriseAt()`: `?\DateTimeImmutable`
-- `getMoonsetAt()`: `?\DateTimeImmutable`
-- `getMoonPhase()`: [`?MoonPhase`](#moonphase)
-- `getTemperature()`: `float`|[`Temperature`](#temperature)
-- `getTemperatureFeelsLike()`: `float`|[`Temperature`](#temperature)
-- `getDescription()`: `?string`
+- `getTemperature()`: `float`
+- `getTemperatureFeelsLike()`: `float`
 - `getAtmosphericPressure()`: `int`
 - `getHumidity()`: `int`
-- `getDewPoint()`: `?float`
+- `getDewPoint()`: `float`
 - `getUltraVioletIndex()`: `?float`
 - `getCloudiness()`: `int`
 - `getVisibility()`: `?int`
 - `getWind()`: [`Wind`](#wind)
-- `getPrecipitationProbability()`: `?int`
-- `getRain()`: `null`|`float`|[`Rain`](#rain)
-- `getSnow()`: `null`|`float`|[`Snow`](#snow)
-- `getWeatherConditions()`: [`WeatherCondition[]`](#weathercondition)
+- `getConditions()`: [`Condition[]`](#condition)
+- `getSummary()`: `?string`
+- `getRainVolume()`: `?float`
+- `getSnowVolume()`: `?float`
+- `getMoonPhase()`: [`?MoonPhase`](#moonphase)
+- `getSunriseAt()`: `?\DateTimeImmutable`
+- `getSunsetAt()`: `?\DateTimeImmutable`
+- `getMoonriseAt()`: `?\DateTimeImmutable`
+- `getMoonsetAt()`: `?\DateTimeImmutable`
 
-### WeatherAggregate
+### WeatherSummary
 
 - `getCoordinate()`: [`Coordinate`](#coordinate)
 - `getTimezone()`: [`Timezone`](#timezone)
@@ -89,30 +80,91 @@
 - `getAtmosphericPressure()`: `int`
 - `getWind()`: [`Wind`](#wind)
 
-### WeatherLocation
+### WeatherData
 
-- `getCoordinate()`: [`Coordinate`](#coordinate)
-- `getTimezone()`: [`Timezone`](#timezone)
 - `getDateTime()`: `\DateTimeImmutable`
+- `getTemperature()`: `float`
+- `getTemperatureFeelsLike()`: `float`
+- `getAtmosphericPressure()`: `int`
+- `getVisibility()`: `?int`
+- `getHumidity()`: `int`
+- `getDewPoint()`: `float`
+- `getUltraVioletIndex()`: `?float`
+- `getCloudiness()`: `int`
+- `getWind()`: [`Wind`](#wind)
+- `getConditions()`: [`Condition[]`](#condition)
+- `getRainVolume()`: `?float`
+- `getSnowVolume()`: `?float`
 - `getSunriseAt()`: `?\DateTimeImmutable`
 - `getSunsetAt()`: `?\DateTimeImmutable`
-- `getMoonriseAt()`: `?\DateTimeImmutable`
-- `getMoonsetAt()`: `?\DateTimeImmutable`
-- `getMoonPhase()`: [`?MoonPhase`](#moonphase)
-- `getTemperature()`: `float`|[`Temperature`](#temperature)
-- `getTemperatureFeelsLike()`: `float`|[`Temperature`](#temperature)
-- `getDescription()`: `?string`
+
+### MinuteData
+
+- `getDateTime()`: `\DateTimeImmutable`
+- `getPrecipitation()`: `float`
+
+### HourData
+
+- `getDateTime()`: `\DateTimeImmutable`
+- `getTemperature()`: `float`
+- `getTemperatureFeelsLike()`: `float`
+- `getVisibility()`: `int`
+- `getPrecipitationProbability()`: `int`
 - `getAtmosphericPressure()`: `int`
 - `getHumidity()`: `int`
-- `getDewPoint()`: `?float`
+- `getDewPoint()`: `float`
 - `getUltraVioletIndex()`: `?float`
 - `getCloudiness()`: `int`
-- `getVisibility()`: `?int`
 - `getWind()`: [`Wind`](#wind)
-- `getPrecipitationProbability()`: `?int`
-- `getRain()`: `null`|`float`|[`Rain`](#rain)
-- `getSnow()`: `null`|`float`|[`Snow`](#snow)
-- `getWeatherConditions()`: [`WeatherCondition[]`](#weathercondition)
+- `getConditions()`: [`Condition[]`](#condition)
+- `getRainVolume()`: `?float`
+- `getSnowVolume()`: `?float`
+
+### DayData
+
+- `getDateTime()`: `\DateTimeImmutable`
+- `getTemperature()`: [`Temperature`](#temperature)
+- `getTemperatureFeelsLike()`: [`Temperature`](#temperature)
+- `getPrecipitationProbability()`: `int`
+- `getAtmosphericPressure()`: `int`
+- `getHumidity()`: `int`
+- `getDewPoint()`: `float`
+- `getUltraVioletIndex()`: `?float`
+- `getCloudiness()`: `int`
+- `getWind()`: [`Wind`](#wind)
+- `getConditions()`: [`Condition[]`](#condition)
+- `getRainVolume()`: `?float`
+- `getSnowVolume()`: `?float`
+- `getSummary()`: `string`
+- `getMoonPhase()`: [`MoonPhase`](#moonphase)
+- `getSunriseAt()`: `\DateTimeImmutable`
+- `getSunsetAt()`: `\DateTimeImmutable`
+- `getMoonriseAt()`: `\DateTimeImmutable`
+- `getMoonsetAt()`: `\DateTimeImmutable`
+
+### Alert
+
+- `getSenderName()`: `string`
+- `getEventName()`: `string`
+- `getStartsAt()`: `\DateTimeImmutable`
+- `getEndsAt()`: `\DateTimeImmutable`
+- `getDescription()`: `string`
+- `getTags()`: `array`
+
+### MoonPhase
+
+- `getValue()`: `float`
+- `getName()`: `string`
+- `getSystemName()`: `string`
+
+### Temperature
+
+- `getMorning()`: `float`
+- `getDay()`: `float`
+- `getEvening()`: `float`
+- `getNight()`: `float`
+- `getMin()`: `?float`
+- `getMax()`: `?float`
 
 ## Weather
 
@@ -138,7 +190,7 @@
 
 - `getNumResults()`: `int`
 - `getLocation()`: [`Location`](#location)
-- `getData()`: [`WeatherData[]`](#weatherdata)
+- `getData()`: [`WeatherData[]`](#weatherdata-1)
 
 ### WeatherData
 
@@ -240,21 +292,6 @@
 - `getSunriseAt()`: `?\DateTimeImmutable`
 - `getSunsetAt()`: `?\DateTimeImmutable`
 
-### MoonPhase
-
-- `getValue()`: `float`
-- `getName()`: `string`
-- `getSysName()`: `string`
-
-### Temperature
-
-- `getMorning()`: `float`
-- `getDay()`: `float`
-- `getEvening()`: `float`
-- `getNight()`: `float`
-- `getMin()`: `?float`
-- `getMax()`: `?float`
-
 ### Timezone
 
 - `getOffset()`: `int`

src/Resource/AirPollutionResource.php

@@ -33,7 +33,7 @@ public function getCurrent(float $latitude, float $longitude): AirPollution
     }
 
     /**
-     * Get access to air pollution forecast data
+     * Get access to air pollution forecast data per hour
      *
      * @throws ValidationException
      * @throws ClientExceptionInterface
@@ -55,7 +55,7 @@ public function getForecast(float $latitude, float $longitude): AirPollutionColl
     }
 
     /**
-     * Get access to historical air pollution data
+     * Get access to historical air pollution data per hour between two dates
      *
      * @throws ValidationException
      * @throws ClientExceptionInterface