get_location_at_time
Retrieve a user's location at a specific time using ISO8601 timestamp. Searches for the closest available location sample within a defined window, including time zones. Ideal for analyzing movement or pinpointing past positions.
Instructions
Gets the user's location at the given time.
If no sample is available for the exact time, searches for the closest one up to window_size seconds back.
Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known.
Args: time: The point in time to get the user's location for. Must include tz (ISO8601). window_size: Optional. The size (in seconds) to look back (and optionally forward) for samples. Defaults to 14400. include_after: Optional. When true, a sample that occurs after the requested time may be returned if it is the closest one. Defaults to False. Returns: A JSON string representing the location data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reverse_geocode | No | ||
| time | Yes | ||
| window_size | No |
Implementation Reference
- fulcra_mcp/main.py:460-493 (handler)The handler function decorated with @mcp.tool() that implements the logic for retrieving the user's location at a specific time using FulcraAPI.@mcp.tool() async def get_location_at_time( time: datetime, window_size: int = 14400, reverse_geocode: bool | None = False, ) -> str: """Gets the user's location at the given time. If no sample is available for the exact time, searches for the closest one up to window_size seconds back. Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known. Args: time: The point in time to get the user's location for. Must include tz (ISO8601). window_size: Optional. The size (in seconds) to look back (and optionally forward) for samples. Defaults to 14400. include_after: Optional. When true, a sample that occurs after the requested time may be returned if it is the closest one. Defaults to False. Returns: A JSON string representing the location data. """ fulcra = get_fulcra_object() kwargs = {} if window_size is not None: kwargs["window_size"] = window_size kwargs["include_after"] = True kwargs["reverse_geocode"] = True location_data = fulcra.location_at_time( time=time, **kwargs, ) return f"Location info at {time}: " + json.dumps(location_data)