Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
Create Map (gmaps_create)
| Field | Value |
|---|---|
| Category | chat_utility (grouping) / location (functional domain) |
| Backend handler | server/nodes/location/gmaps_create/__init__.py — dispatch via BaseNode.execute() + @Operation("create") → server/nodes/location/_service.py::MapsService.create_map |
| Tests | server/tests/nodes/test_chat_utility.py |
| Skill (if any) | - |
| Dual-purpose tool | no (display-only; gmaps_locations and gmaps_nearby_places are the dual-purpose pair) |
Purpose
Builds a Google Maps configuration (center, zoom, map type) and a Static Maps
URL for display on the canvas or downstream consumers. The node does NOT hit
the Maps API - it assembles the URL from parameters and tracks a
static_map usage cost of $0.002 per execution.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream lat/lng via templates |
Parameters
Params model (GmapsCreateParams):
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
center_lat |
number | 0.0 |
no | - | Map center latitude |
center_lng |
number | 0.0 |
no | - | Map center longitude |
zoom |
number | 10 |
no | - | Zoom level, ge=1, le=20 (1=world, 20=street) |
map_type |
enum | roadmap |
no | - | One of roadmap, satellite, hybrid, terrain |
options |
object | {} |
no | - | Map customization (disable_default_ui, zoom_control, street_view_control, map_type_control, fullscreen_control); 4 rows |
The Google Maps API key is NOT a node Param — MapsService.create_map reads it
from parameters.get("api_key") (absent here) falling back to
settings.google_maps_api_key. The GoogleMapsCredential (google_maps) is
declared on the node for credential-modal visibility.
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Map config + static URL |
Output payload (TypeScript shape)
{
map_config: {
center: { lat: number; lng: number };
zoom: number;
mapTypeId: "ROADMAP" | "SATELLITE" | "HYBRID" | "TERRAIN";
};
static_map_url: string; // https://maps.googleapis.com/maps/api/staticmap?...
status: "OK";
}
Logic Flow
flowchart TD
A[Receive params] --> B{api_key present?}
B -- no --> E[Return error: Google Maps API key is required]
B -- yes --> C[Validate lat/lng, zoom, map_type]
C -- invalid --> E
C -- ok --> D[Compose map_config + static_map_url]
D --> F[_track_maps_usage: static_map, 1]
F --> G[Return success envelope]
Decision Logic
- Validation (inside
MapsService.create_map):api_keyrequired (fromparameters.get("api_key"), elsesettings.google_maps_api_key).lat/lngvalidated viavalidate_coordinates.zoomvalidated viavalidate_zoom_level(0-21).map_typerestricted to["ROADMAP", "SATELLITE", "HYBRID", "TERRAIN"](uppercase).
- Branches: success envelope vs error envelope.
- Fallbacks: when
lat/lng/zoom/map_type_idkeys are absent in the dumped params, the service centres on New York City (40.7128, -74.0060), zoom 13,ROADMAP(see the key-mismatch note under Edge cases). - Error paths: on
not response.successthe op raisesNodeUserError(response.error or "Map create failed")(single WARN line, no traceback);BaseNode.execute()builds the structured error envelope.
Side Effects
- Database writes:
api_usage_metricsrow via_track_maps_usagewithoperation=static_map,resource_count=1,total_cost=0.002. - Broadcasts: none.
- External API calls: none. The URL is assembled locally and meant to be
fetched by the frontend or downstream
httpRequestnode. - File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials:
GoogleMapsCredential(google_maps); the service resolves the key fromparameters.get("api_key")elsesettings.google_maps_api_key(envGOOGLE_MAPS_API_KEY). - Services:
MapsServiceobtained viaservices.plugin.deps.get_maps_service(). - Python packages: stdlib only for this path (googlemaps is used by other map handlers, not this one).
- Environment variables:
GOOGLE_MAPS_API_KEY(fallback).
Edge cases & known limits
- Param/service key mismatch: the plugin Params are
center_lat/center_lng/map_type, butMapsService.create_mapreadslat/lng/map_type_id. With the currentparams.model_dump()wiring the service falls back to its NYC / ROADMAP defaults regardless of the configured center / map type. (Documented, not fixed here.) - The static map URL embeds the API key in plain text - any downstream node or log that captures the output leaks the key. Treat the output as sensitive.
- Size is hard-coded to
600x400; there is no parameter to override. map_typevalidation is case-sensitive (uppercaseROADMAP...); the lowercase enum values the Params expose would be rejected if they reached the service.- Cost tracking is optimistic: the $0.002 is charged even if the frontend never actually fetches the static map URL.
Related
- Skills using this as a tool: none (display-only node).
- Other nodes that consume this output: downstream map-display components
on the frontend, or
httpRequestfor server-side image fetch. - Architecture docs:
docs-internal/pricing_service.mdfor API cost tracking.