find_active_locations
ChatGPTFinds AuroraReach-tracked locations with a currently open/flagged aurora sighting event (status=active), optionally restricted to a country or a lat/lng radius. This is a narrower signal than a forecast score - most places, most of the time, have nothing formally flagged even when their forecast score is reasonable, so an empty result is common and expected, not broken. For "should I go look" or a ranked comparison of nearby options regardless of whether anything is formally flagged, use find_best_viewing_locations instead.
find_best_viewing_locations
ChatGPTAuroraReach's opinionated answer to "where nearby should I drive?" - evaluates AuroraReach-tracked locations near an origin using the real forecast engine (same as get_aurora_forecast) for the requested date/time, and returns them ranked with score, conditions, distance, and a why explaining how each one compares to the top pick. Bounded to a small number of forecast lookups regardless of radius/limit to avoid excess upstream load. Includes relevant offers by default.
get_aurora_activity_history
ChatGPTReturns AuroraReach's historical aurora activity for a location over a date range: how many community sighting reports were recorded and when the earliest/latest ones were. Built on the same activity stats behind AuroraReach's public stats endpoint. For a month/week/weekday/hour breakdown ("best time to visit") use get_best_aurora_times instead.
get_aurora_forecast
ChatGPTAuroraReach's primary forecast tool: returns AuroraReach's own interpreted forecast for a location (not raw upstream NOAA/weather data) - a 0-100 score, a yes/maybe/no recommendation, a heuristic confidence, the best viewing window in the next 24h, cloud/weather impact, darkness/viewing suitability, and the individual signals behind the score. Optionally target a specific future date/time (within AuroraReach's ~3-day coverage window); omit it for the current hour. Includes a few relevant bookable offers by default. Use should_i_go_outside instead for a single opinionated yes/no answer, or plan_aurora_experience for a full evening plan.
get_best_aurora_times
ChatGPTAnswers "when is the best month/week/weekday/hour to visit <place> for aurora?" using AuroraReach's historical sighting-report activity grouped by the requested time bucket. Explicitly a historical pattern, not a forecast or a guarantee - always presented with that caveat.
get_country_aurora_summary
ChatGPTCountry-level aurora intelligence: top AuroraReach-tracked locations (ranked by observation/activity volume, the most consistently available popularity signal), an aggregate kp range, active_sighting_score_range (null when nothing is currently formally flagged anywhere in the country - that is expected, not broken), a recent community-sighting count, the canonical AuroraReach country page, and (by default) relevant offers. Use this for "where in <country> should I look" or "tell me about aurora in <country>" questions; use find_active_locations or find_best_viewing_locations for a live/forecast-based comparison instead of the observation-based ranking here.
get_current_conditions
ChatGPTAnswers "can I see the aurora right now?" for a location - a concise snapshot of AuroraReach's current score, yes/maybe/no recommendation, live aurora activity signals (kp gap, Bz, solar wind), current cloud/visibility conditions, darkness state, the reasoning behind the recommendation, a link to the live AuroraReach page for this location, and (by default) a few relevant bookable offers. For a forward-looking forecast (best time tonight, future dates) use get_aurora_forecast instead.
get_global_activity
ChatGPTReturns AuroraReach's current worldwide aurora activity: the strongest continents, currently-active countries and cities (with scores, using the same threshold AuroraReach's public /highlights pages use), and any upcoming global geomagnetic storm windows (NOAA G-scale). Use this for "where is the aurora active right now?" or "is anything happening globally?" rather than iterating find_active_locations per country.
get_location
ChatGPTGet everything AuroraReach knows about a single location in one call: basic metadata, its current aurora condition/score, a historical sighting-report summary, nearby AuroraReach-tracked locations, a link to the full AuroraReach page for this location (more photos, detail and booking options live there), and (by default) a few relevant bookable offers. Use this for "tell me about <place>" or as a follow-up after search_locations. For a dedicated "can I see it right now" answer use get_current_conditions instead; for the full forward-looking forecast use get_aurora_forecast.
get_location_checkins
ChatGPTReturns AuroraReach community check-ins reported specifically at one location within an explicit time window, e.g. to answer "are people actually seeing auroras around Rovaniemi right now?". Only public fields are returned - no private user data or exact device GPS. For a wider area or country-level view use get_recent_checkins instead.
get_map_conditions
ChatGPTReturns the structured data behind AuroraReach's map view for a bounded circular area: AuroraReach-tracked locations and their current scores within radius_km of a centre point. Always requires a bounded scope (centre + radius, capped) - never returns an unbounded global dataset. Does not include per-point cloud cover or light pollution (not available at this scale/AuroraReach does not model light pollution) - use get_aurora_forecast for weather-level detail on one location.
get_nearby_locations
ChatGPTGiven an AuroraReach location, returns other AuroraReach-tracked locations near it - distance, compass direction, current score and canonical URL for each. Use this for "what else is nearby" or as an input to travel-planning questions. For an opinionated ranked recommendation of where to actually go tonight, use find_best_viewing_locations instead.
get_offers
ChatGPTReturns bookable aurora experiences/tours through AuroraReach's existing commercial offers integration (AuroraReach Partner Services, Viator, GetYourGuide, and AuroraReach's own activity/trip offers). Use this whenever booking/commercial intent is central, e.g. "find me an aurora tour in Levi". Affiliate URLs are AuroraReach's own tracked links, returned unmodified - never reconstruct a direct provider URL. Returns an empty offers array (not an error) when nothing is available. Provide location or country for relevant results - without either, results reflect the server's own location, not the user's.
get_recent_checkins
ChatGPTReturns recent AuroraReach community check-ins (public sighting reports only - no private user data) within an explicit time window (since/until in the response), scoped to a location, an optional radius around it, a country, or globally if neither is given. Answers "are people currently seeing auroras near X?" with real community reports rather than a forecast. Each check-in includes only the public fields AuroraReach's own API returns - never exact device GPS or contact details.
get_viewing_hotspots
ChatGPTSurfaces AuroraReach-tracked locations (towns/cities, not individual lookout points or photo spots) near a destination that are historically well-regarded for aurora viewing (ranked by rating and observation volume), plus a count of recent community aurora check-ins nearby as a real-activity signal, with an explicit date range and radius. Never fabricates hotspot data - everything returned already exists in AuroraReach's places/checkins data. Includes relevant offers by default.
plan_aurora_experience
ChatGPTThe flagship AuroraReach planning tool - answers "help me maximize my chance of seeing the northern lights tonight/tomorrow and show me something I can book" in one call. Combines AuroraReach's forecast (score, recommendation, best window, weather), an opinionated ranking of nearby viewing locations and alternatives, recent community sightings, historical context, the canonical AuroraReach page, and (by default) relevant bookable offers matched to the plan's destination and timing. Everything is drawn from AuroraReach's existing forecast/location/community/offers REST endpoints - nothing here is fabricated.
search_locations
ChatGPTResolve a place name (or browse a country) into AuroraReach location ids. Use this FIRST whenever a user gives a place by name (e.g. "Rovaniemi", "Tromso", "somewhere in Iceland") before calling any other AuroraReach tool - every other tool that takes a "location" accepts the id this returns. Returns each match's id, name, region/country/continent, coordinates, timezone, canonical AuroraReach URL, and a few relevant offers for the top match.
should_i_go_outside
ChatGPTA single opinionated yes/maybe/no answer to "should I go outside for the aurora tonight?" for a location, built entirely from AuroraReach's own forecast engine (same as get_aurora_forecast) - not a separate scoring system. Includes the score, a confidence estimate, tonight's best viewing window, plain-language reasoning, the underlying conditions, and (by default) relevant offers in case the answer is "yes, and here is something to book". Prefer this over manually combining get_aurora_forecast + get_current_conditions for a direct recommendation.
where_should_i_go
ChatGPTRanks nearby destinations for aurora viewing from an origin and explains why each one outranks the alternatives, using the same forecast-based ranking as find_best_viewing_locations. Prefer this framing for "where should I go" style questions where the traveller is deciding between destinations rather than just wanting a ranked list; includes relevant offers by default.
