Enrich your journal entries with location and weather data to create more detailed memories of your experiences.

Journiv supports location tagging and weather information for your entries, helping you remember not just what happened, but where you were and what the weather was like. This feature integrates with OpenWeather API to fetch accurate weather data based on your entry's location and time.

What You Can Do

Add Location to Entries

Use your current location - Automatically detect where you are
Search for places - Find and select any location worldwide
View location details - See full address, coordinates, and place information

Add Weather to Entries

Fetch current weather - Get real-time weather conditions for your location
Get historical weather - Retrieve weather data for past entries (requires OpenWeather 3.0 API)
View weather details - Temperature, conditions, humidity, wind speed, and more

How Location Works

Location data helps you remember where you wrote each entry. Journiv stores:

Place name - The name of the location (e.g., "Central Park")
Address - Full address information when available
Coordinates - Latitude and longitude for precise location
Display information - Formatted location text for easy reading

Adding Location to an Entry

Note: Location permissions are required on mobile devices. If permission is denied, you can manually search for your location instead.

Method 1: Use Current Location: By clicking the "Use Current Location" button
Method 2: Search for a Location: Type a place name in the search box (e.g., "Paris, France" or "Times Square")
Method 3: Manually enter coordinates: Enter the latitude and longitude manually (e.g., 40.7128, -74.0060)

Viewing Location Details

After adding a location, you can:

View location card - See the location name displayed in the entry
Tap location card - Open a dialog with full location details
Remove location - Click "Remove Location" to delete it from the entry

How Weather Works

Weather data enriches your entries with atmospheric conditions. Journiv fetches weather information from OpenWeather API based on:

Location coordinates - Weather is fetched for the location you've added
Entry date and time - Weather matches the time when your entry was created
Historical support - Past entries can retrieve weather from that specific time

Weather Data Included

When you fetch weather, Journiv includes:

Temperature - Current temperature in Celsius and Fahrenheit
Feels like - Perceived temperature
Condition - Weather condition (Clear, Cloudy, Rain, etc.)
Description - Detailed weather description
Humidity - Humidity percentage
Wind speed - Wind speed in meters per second
Pressure - Atmospheric pressure in hPa
Visibility - Visibility in meters
Weather icon - Visual representation of conditions

Adding Weather to an Entry

Prerequisites:

You must add a location to the entry first
Your Journiv instance must have OpenWeather API keys configured (see Configuration below)

Steps to Add Weather

Add a location to your entry (see Adding Location above)
Click "Fetch Weather"
Weather data will be fetched and displayed

Weather for Different Times

Current entries - Fetches current weather conditions
Past entries - Retrieves historical weather for the entry's date/time (requires OpenWeather 3.0 API key)
Future entries - Uses current weather conditions (weather predictions not available)

Refreshing Weather

If you change the entry's date or time, you may see a prompt to refetch weather
Click "Refetch for new time" to get weather matching the updated time
Click "Refresh Weather" to update current weather data

Viewing Weather Information

After fetching weather, you'll see:

Weather card - Displays temperature, condition, and weather icon
Entry time - Shows the date/time the weather corresponds to
Current conditions badge - Indicates if weather is current vs. historical
Observation time - When the weather data was actually observed

Removing Weather

To remove weather from an entry:

Scroll to the Weather section
Click "Remove Weather"
Weather data will be removed from the entry

Configuration

Weather features require OpenWeather API keys to be configured on your Journiv backend instance.

Getting an OpenWeather API Key

Visit OpenWeatherMap
Sign up for a free account
Navigate to your API keys section
Generate a new API key
It can take up to 1 hour for the API key to be activated. You will receive an email when it is activated.

Note: Free tier includes:

Current weather API (2.5) - 60 calls per minute.
Historical weather API (3.0) - Requires credit card to sign up. First 1000 calls per day are free, then API calls are charged. After signing up, you must add credit card details and enable OpenWeather 3.0 API to use it.

Configuring API Keys

Add the following environment variables to your Journiv backend .env file:

# Note: You can set the same API key for both 2.5 and 3.0 if you want to use the same API key for both.
# OpenWeather API 2.5 (Current Weather)
# Get your free API key at: https://openweathermap.org/api
OPEN_WEATHER_API_KEY_25=your-openweather-2-5-api-key-here

# OpenWeather API 3.0 (Historical Weather - Optional)
# Required for fetching weather for past entries
OPEN_WEATHER_API_KEY_30=your-openweather-3-0-api-key-here

API Key Options

You can configure one or both API keys:

Only OPEN_WEATHER_API_KEY_25:
- ✅ Current weather for new entries
- ❌ Historical weather for past entries
Only OPEN_WEATHER_API_KEY_30:
- ✅ Current weather for new entries
- ✅ Historical weather for past entries
Both keys configured:
- ✅ Current weather uses 2.5 API (more efficient)
- ✅ Historical weather uses 3.0 API (when entry is >1 hour old)

Restart Required

After adding API keys:

Save the .env file
Restart your Journiv backend service
Weather features will be enabled automatically

Verifying Configuration

If weather service is not configured, you'll see an error message when trying to fetch weather:

"Weather service is not configured. Please set OPEN_WEATHER_API_KEY_25 or OPEN_WEATHER_API_KEY_30 in environment variables of your Journiv backend."

This means your instance administrator needs to configure the API keys (see above).

How It Works Behind the Scenes

Weather Caching

Journiv caches weather data for 30 minutes to:

Reduce API calls to OpenWeather
Improve response times
Stay within API rate limits

Weather is cached by:

Location coordinates (rounded to ~1.1km precision)
Time bucket (hourly for historical weather)

API Selection

Journiv automatically chooses the best API:

Current weather (< 1 hour old): Uses OpenWeather 2.5 API (if available)
Historical weather (> 1 hour old): Uses OpenWeather 3.0 Time Machine API
Fallback: If only 3.0 key is available, it's used for all requests

Location Services

Mobile apps: Use device GPS with permission
Web apps: Use browser geolocation API (lacks high precision)
Search: Uses location search service to find places

Privacy & Data

Location Privacy

Location data is stored only in your entries on your server.
Coordinates are not shared with external services (except OpenWeather for weather)
You can remove location from any entry at any time

Weather Data

Weather requests include only coordinates (not your identity)
OpenWeather API terms apply to weather data usage
Weather data is cached locally to minimize external requests

Data Storage

Location and weather are stored as part of entry metadata on your server.
Included in Jouriv exports and PDFs.
Preserved when importing from other apps (e.g., Day One)

Tips & Best Practices

Location

Be specific: Search for exact locations rather than just cities
Use current location: Faster for entries you're writing in real-time
Review location: Check the location card to ensure accuracy

Weather

Add location first: Weather requires coordinates from location
Refresh when needed: Update weather if entry time changes significantly
Historical entries: Use OpenWeather 3.0 API key for past entry weather

Performance

Weather is cached, so repeated fetches for the same location/time are fast
Large numbers of weather requests may hit API rate limits. Note the API key is associated with your server and not per user account on your server. So if you have multiple users on your server, the API rate limits will be shared between them.

Troubleshooting

"Please add a location first to fetch weather"

Solution: Add a location to your entry before fetching weather. Weather requires coordinates to work.

"Weather service is not configured"

Solution: Your Journiv instance administrator needs to add OpenWeather API keys to the backend configuration. See Configuration above.

"Invalid OpenWeather API Key"

Solution: The API key in the backend configuration is incorrect or expired. Administrator should verify the key at OpenWeatherMap.

Location permission denied

Solution:

Mobile: Go to device Settings → Apps → Journiv → Permissions → Enable Location
Web: Check browser settings to allow location access for your Journiv domain

Weather not available for past entries

Solution: Historical weather requires OpenWeather 3.0 API key. Ask your administrator to configure OPEN_WEATHER_API_KEY_30.

Weather shows "Current conditions" for old entries

Solution: This happens when:

Entry time is in the future (weather predictions not available)
Only OpenWeather 2.5 API is configured (historical weather requires 3.0)
Entry time is very recent (< 1 hour old)

Location search not working