get_location_at_time
Retrieve user location data for a specific time from Context By Fulcra, using nearest available sample within a configurable time window.
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 |
|---|---|---|---|
| time | Yes | ||
| window_size | No | ||
| reverse_geocode | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- fulcra_mcp/main.py:460-492 (handler)The main handler function for the 'get_location_at_time' tool. It is decorated with @mcp.tool() which registers it with the FastMCP server. The function retrieves the user's location at a specified time using the FulcraAPI, with options for window size and reverse geocoding. Type hints define the input schema.
@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)