Skip to main content

Weather Service

|

The WeatherService class contains methods for getting the current, hourly and daily forecasts.

Get Current Weather Forecast​

To retrieve the current weather forecast, use the getCurrent method of the WeatherService class. Provide the coordinates for the desired location, and the forecast will be returned through the callback. The following example demonstrates how to fetch the current forecast for Paris coordinates.

val weatherService = WeatherService()

val locationCoordinates = Coordinates().apply {
    latitude = 48.864716
    longitude = 2.349014
}

val coordinatesList = CoordinatesList().apply {
    add(locationCoordinates)
}

 weatherService.getCurrent(coordinatesList, onCompleted = { results, error, message ->
    if (error == GemError.NoError) {
        // Process the current forecast results
        Log.d("Weather", "Forecast list size: ${results.size}")

        results.firstOrNull()?.let { locationForecast ->
            // Access forecast data
            locationForecast.forecast?.forEach { condition ->
                Log.d("Weather", "Condition: ${condition.description}")
            }
        }
    } else {
        Log.e("Weather", "Error getting current forecast: $message")
    }
})
danger

The API user is responsible for verifying whether the LocationForecast contains any Conditions, and whether each Condition includes a WeatherParameter. If data is unavailable for the specified location and time, the API may return empty lists ofConditions or WeatherParameters.

info

The result will contain as many LocationForecast objects as the list size of given coordinates to coords parameter.

Get Hourly Weather Forecast​

To retrieve the hourly weather forecast, use the getHourlyForecast method of the WeatherService class. Provide the coordinates for the desired location, and the forecast will be returned through the callback. The following example demonstrates how to fetch the hourly forecast for Paris coordinates.

val weatherService = WeatherService()

val locationCoordinates = Coordinates().apply {
    latitude = 48.864716
    longitude = 2.349014
}

val coordinatesList = CoordinatesList().apply {
    add(locationCoordinates)
}

weatherService.getHourlyForecast(24, coordinatesList, onCompleted =  { results, error, message ->
    if (error == GemError.NoError) {
        // Process the hourly forecast results
        Log.d("Weather", "Hourly forecast list size: ${results.size}")

        results.firstOrNull()?.forecast?.forEach { condition ->
            // Process each hourly condition
            val timestamp = condition.timestamp
            val description = condition.description

            condition.parameters?.forEach { parameter ->
                when (parameter.type) {
                    "Temperature" -> {
                        Log.d("Weather", "Temperature: ${parameter.value}${parameter.unit}")
                    }
                    "Humidity" -> {
                        Log.d("Weather", "Humidity: ${parameter.value}${parameter.unit}")
                    }
                }
            }
        }
    } else {
        Log.e("Weather", "Error getting hourly forecast: $message")
    }
})

You'll need to provide the number of hours for which the forecast is requested.

danger

The number of requested hours must not exceed 240. Exceeding this limit will result in an empty response and an error of type GemError.outOfRange.

Get the Daily Forecast​

To retrieve the daily weather forecast, use the getDailyForecast method of the WeatherService class. Provide the coordinates for the desired location, and the forecast will be returned through the callback. The following example demonstrates how to fetch the daily forecast for Paris coordinates.

val weatherService = WeatherService()

val locationCoordinates = Coordinates().apply {
    latitude = 48.864716
    longitude = 2.349014
}

val coordinatesList = CoordinatesList().apply {
    add(locationCoordinates)
}

weatherService.getDailyForecast(10, coordinatesList, onCompleted =  { results, error, message ->
    if (error == GemError.NoError) {
        // Process the daily forecast results
        Log.d("Weather", "Daily forecast list size: ${results.size}")

        results.firstOrNull()?.forecast?.forEach { condition ->
            // Process each daily condition
            val description = condition.description
            val daylight = condition.daylight

            condition.parameters?.forEach { parameter ->
                when (parameter.type) {
                    "TemperatureHigh" -> {
                        Log.d("Weather", "High temp: ${parameter.value}${parameter.unit}")
                    }
                    "TemperatureLow" -> {
                        Log.d("Weather", "Low temp: ${parameter.value}${parameter.unit}")
                    }
                    "Sunrise" -> {
                        // Convert timestamp to readable time
                        val sunriseTime = Date((parameter.value * 1000).toLong())
                        Log.d("Weather", "Sunrise: $sunriseTime")
                    }
                    "Sunset" -> {
                        // Convert timestamp to readable time
                        val sunsetTime = Date((parameter.value * 1000).toLong())
                        Log.d("Weather", "Sunset: $sunsetTime")
                    }
                }
            }
        }
    } else {
        Log.e("Weather", "Error getting daily forecast: $message")
    }
})

You'll need to provide the number of days for which the forecast is requested.

danger

The number of requested days must not exceed 10. Exceeding this limit will result in an empty response and an error of type GemError.outOfRange.

Get the Weather Forecast​

To retrieve the weather forecast at a specific time and coordinates, use the getForecast method of WeatherService class. You'll need to provide a list of TimeDistanceCoordinate, and the callback will retrieve as many LocationForecast objects as the size of the coordinate list.

val weatherService = WeatherService()

// Create coordinates for Paris
val coordinates = Coordinates().apply {
    latitude = 48.864716
    longitude = 2.349014
}

// Create time-distance coordinate for forecast 2 days in the future
val timeDistanceCoordinate = TimeDistanceCoordinate().also {
    it.coordinates = coordinates
    // Set duration to 2 days in the future (duration in seconds)
    it.timestamp = 2 * 24 * 60 * 60L // 2 days in seconds
}

val coordinatesList = TimeDistanceCoordinateList().also { it.add(0,timeDistanceCoordinate) }

weatherService.getForecast(coordinatesList, onCompleted =  { results, error, message ->
    if (error == GemError.NoError) {
        // Process the forecast results
        Log.d("Weather", "Forecast list size: ${results.size}")

        results.forEach { locationForecast ->
            locationForecast.forecast?.forEach { condition ->
                Log.d("Weather", "Forecast condition: ${condition.description}")

                // Process weather parameters
                condition.parameters?.forEach { parameter ->
                    Log.d("Weather", "${parameter.name}: ${parameter.value}${parameter.unit}")
                }
            }
        }
    } else {
        Log.e("Weather", "Error getting forecast: $message")
    }
})
info

The duration parameter in TimeDistanceCoordinate specifies the relative time offset into the future (in seconds) for which the forecast is requested.

Working with Weather Images​

Weather condition images are provided as Image objects. Here's how to convert them to Android Bitmaps for display:

condition.image?.let { weatherImage ->
    // Convert Image to Bitmap
    val bitmap = weatherImage.asBitmap(100,100)

    // Use the bitmap in your ImageView
    //imageView.setImageBitmap(bitmap)
}
Last updated on