***
title: DataMap
slug: /reference/python/agents/data-map
description: Fluent builder for server-side API tools that execute without webhooks.
max-toc-depth: 3
---------------------
For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt
[swaigfunction]: /docs/server-sdks/reference/python/agents/swaig-function
[functionresult]: /docs/server-sdks/reference/python/agents/function-result
[data-map]: /docs/swml/reference/ai/swaig/functions/data-map
[swml-data-map-reference]: /docs/swml/reference/ai/swaig/functions/data-map
[body]: /docs/server-sdks/reference/python/agents/data-map/body
[errorkeys]: /docs/server-sdks/reference/python/agents/data-map/error-keys
[expression]: /docs/server-sdks/reference/python/agents/data-map/expression
[foreach]: /docs/server-sdks/reference/python/agents/data-map/foreach
[helper-functions]: /docs/server-sdks/reference/python/agents/data-map/helper-functions
[output]: /docs/server-sdks/reference/python/agents/data-map/output
[parameter]: /docs/server-sdks/reference/python/agents/data-map/parameter
[purpose]: /docs/server-sdks/reference/python/agents/data-map/purpose
[toswaigfunction]: /docs/server-sdks/reference/python/agents/data-map/to-swaig-function
[webhook]: /docs/server-sdks/reference/python/agents/data-map/webhook
[webhookexpressions]: /docs/server-sdks/reference/python/agents/data-map/webhook-expressions
DataMap builds SWAIG function definitions that execute REST API calls directly on
SignalWire's infrastructure -- no webhook endpoint required on your server. This
reduces latency, simplifies deployment, and is ideal for straightforward
API-to-response integrations.
Use DataMap when you need to call an external REST API and format the response
with simple variable substitution. For complex business logic, database access,
or multi-step processing, use a standard SWAIG function with a handler instead.
See [`SWAIGFunction`][swaigfunction] for
handler-based tool definitions, and
[`FunctionResult`][functionresult] for the
response builder used in DataMap outputs.
DataMap generates a SWML [`data_map`][data-map] object
within a SWAIG function definition. See the
[SWML data\_map reference][swml-data-map-reference] for the
full specification.
## **Properties**
Name of the SWAIG function this DataMap will create.
## **Variable Substitution Patterns**
| Pattern | Description |
| ---------------------- | ------------------------------------------ |
| `${args.param}` | Function argument value |
| `${enc:args.param}` | URL-encoded argument (use in webhook URLs) |
| `${lc:args.param}` | Lowercase argument value |
| `${fmt_ph:args.phone}` | Format as phone number |
| `${response.field}` | API response field |
| `${response.arr[0]}` | Array element in response |
| `${global_data.key}` | Global session data |
| `${meta_data.key}` | Call metadata |
| `${this.field}` | Current item in foreach |
Modifiers are applied right-to-left: `${enc:lc:args.param}` lowercases first,
then URL-encodes.
## **Methods**
Set the request body for a webhook.
Alias for purpose — set the function description.
Set error detection keys for webhook responses.
Add a pattern-based response without an API call.
Process an array from the webhook response.
Convenience functions for creating common DataMap patterns.
Set the output template for a webhook.
Set the fallback output when no webhook or expression matches.
Set top-level error detection keys.
Set query or form parameters for a webhook.
Add a function parameter to the tool definition.
Set the function description shown to the AI.
Convert the DataMap to a SWAIG function definition dictionary.
Add an API call to the DataMap.
Add post-processing expressions for a webhook response.
***
## **Examples**
### Weather lookup
```python {11}
from signalwire import AgentBase, DataMap
from signalwire import FunctionResult
class WeatherAgent(AgentBase):
def __init__(self):
super().__init__(name="weather-agent")
self.add_language("English", "en-US", "rime.spore")
self.prompt_add_section("Role", "You help users check the weather.")
weather = (
DataMap("get_weather")
.description("Get current weather for a city")
.parameter("city", "string", "City name", required=True)
.webhook(
"GET",
"https://api.weatherapi.com/v1/current.json"
"?key=YOUR_API_KEY&q=${enc:args.city}"
)
.output(FunctionResult(
"Current weather in ${args.city}: "
"${response.current.condition.text}, "
"${response.current.temp_f} degrees Fahrenheit"
))
.fallback_output(FunctionResult(
"Sorry, I couldn't get weather data for ${args.city}"
))
)
self.register_swaig_function(weather.to_swaig_function())
if __name__ == "__main__":
WeatherAgent().run()
```
### Expression-based control
```python {5}
from signalwire import AgentBase, DataMap
from signalwire import FunctionResult
volume_control = (
DataMap("set_volume")
.purpose("Control audio volume")
.parameter("level", "string", "Volume level", required=True)
.expression(
"${args.level}", r"high|loud|up",
FunctionResult("Volume increased")
)
.expression(
"${args.level}", r"low|quiet|down",
FunctionResult("Volume decreased")
)
.expression(
"${args.level}", r"mute|off",
FunctionResult("Audio muted")
)
)
agent = AgentBase(name="media-agent")
agent.set_prompt_text("You are a helpful assistant.")
agent.register_swaig_function(volume_control.to_swaig_function())
if __name__ == "__main__":
agent.run()
```
### POST with body and foreach
```python {5}
from signalwire import DataMap
from signalwire import FunctionResult
search_docs = (
DataMap("search_docs")
.purpose("Search documentation")
.parameter("query", "string", "Search query", required=True)
.webhook(
"POST",
"https://api.docs.example.com/search",
headers={"Authorization": "Bearer TOKEN"}
)
.body({"query": "${args.query}", "limit": 3})
.foreach({
"input_key": "results",
"output_key": "formatted_results",
"max": 3,
"append": "- ${this.title}: ${this.summary}\n"
})
.output(FunctionResult("Found:\n${formatted_results}"))
.fallback_output(FunctionResult("Search is currently unavailable."))
)
print(search_docs.to_swaig_function())
```