KosmoKrator

data

OpenStreetMap Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the OpenStreetMap KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.openstreetmap.*. Use lua_read_doc("integrations.openstreetmap") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic OpenStreetMap workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.openstreetmap.nominatim_search({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("openstreetmap"))' --json
kosmo integrations:lua --eval 'print(docs.read("openstreetmap.nominatim_search"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local openstreetmap = app.integrations.openstreetmap
local result = openstreetmap.nominatim_search({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.openstreetmap, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.openstreetmap.default.* or app.integrations.openstreetmap.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need OpenStreetMap, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

OpenStreetMap

Namespace: openstreetmap

Use this integration for public OpenStreetMap workflows: Nominatim geocoding, Nominatim lookup/details, Overpass QL data queries, service status checks, and stable OSM object/map URLs.

Authentication

The read-only public APIs used by this integration require no credentials. Requests include a descriptive User-Agent header.

Tools

  • openstreetmap_nominatim_search: forward geocode free-form or structured addresses.
  • openstreetmap_nominatim_reverse: reverse geocode latitude/longitude.
  • openstreetmap_nominatim_lookup: look up N123,W456,R789 object IDs.
  • openstreetmap_nominatim_details: inspect a Nominatim place.
  • openstreetmap_nominatim_status: check Nominatim status.
  • openstreetmap_overpass_query: run Overpass QL. Include [out:json] when you want JSON parsed into tool output.
  • openstreetmap_overpass_status: check Overpass status.
  • openstreetmap_object_url: build node/way/relation URLs.
  • openstreetmap_map_url: build coordinate map URLs.

Usage Notes

Nominatim public instances have usage-policy limits. Keep requests specific, cache results in host applications when appropriate, and pass email for heavy or repeated use. Overpass query results can be large; always bound queries by area, bounding box, or limit.

Examples

local places = tools.openstreetmap_nominatim_search({
  q = "Brandenburg Gate Berlin",
  limit = 3,
  addressdetails = true,
  extratags = true
})

local reverse = tools.openstreetmap_nominatim_reverse({
  lat = 52.5163,
  lon = 13.3777,
  zoom = 18,
  addressdetails = true
})

local cafes = tools.openstreetmap_overpass_query({
  query = [[
    [out:json][timeout:25];
    node["amenity"="cafe"](52.51,13.37,52.52,13.39);
    out center 20;
  ]]
})
Raw agent markdown 
# OpenStreetMap

Namespace: `openstreetmap`

Use this integration for public OpenStreetMap workflows: Nominatim geocoding,
Nominatim lookup/details, Overpass QL data queries, service status checks, and
stable OSM object/map URLs.

## Authentication

The read-only public APIs used by this integration require no credentials.
Requests include a descriptive `User-Agent` header.

## Tools

- `openstreetmap_nominatim_search`: forward geocode free-form or structured
  addresses.
- `openstreetmap_nominatim_reverse`: reverse geocode latitude/longitude.
- `openstreetmap_nominatim_lookup`: look up `N123,W456,R789` object IDs.
- `openstreetmap_nominatim_details`: inspect a Nominatim place.
- `openstreetmap_nominatim_status`: check Nominatim status.
- `openstreetmap_overpass_query`: run Overpass QL. Include `[out:json]` when
  you want JSON parsed into tool output.
- `openstreetmap_overpass_status`: check Overpass status.
- `openstreetmap_object_url`: build node/way/relation URLs.
- `openstreetmap_map_url`: build coordinate map URLs.

## Usage Notes

Nominatim public instances have usage-policy limits. Keep requests specific,
cache results in host applications when appropriate, and pass `email` for
heavy or repeated use. Overpass query results can be large; always bound
queries by area, bounding box, or limit.

## Examples

```lua
local places = tools.openstreetmap_nominatim_search({
  q = "Brandenburg Gate Berlin",
  limit = 3,
  addressdetails = true,
  extratags = true
})

local reverse = tools.openstreetmap_nominatim_reverse({
  lat = 52.5163,
  lon = 13.3777,
  zoom = 18,
  addressdetails = true
})

local cafes = tools.openstreetmap_overpass_query({
  query = [[
    [out:json][timeout:25];
    node["amenity"="cafe"](52.51,13.37,52.52,13.39);
    out center 20;
  ]]
})
```
Metadata-derived Lua example 
local result = app.integrations.openstreetmap.nominatim_search({})
print(result)

Functions

nominatim_reverse Read

Reverse geocode latitude and longitude.

Lua path
app.integrations.openstreetmap.nominatim_reverse
Full name
openstreetmap.openstreetmap_nominatim_reverse
ParameterTypeRequiredDescription
No parameters.
nominatim_lookup Read

Look up address details by OSM object IDs.

Lua path
app.integrations.openstreetmap.nominatim_lookup
Full name
openstreetmap.openstreetmap_nominatim_lookup
ParameterTypeRequiredDescription
No parameters.
nominatim_details Read

Get detailed Nominatim place information.

Lua path
app.integrations.openstreetmap.nominatim_details
Full name
openstreetmap.openstreetmap_nominatim_details
ParameterTypeRequiredDescription
No parameters.
nominatim_status Read

Check Nominatim service status.

Lua path
app.integrations.openstreetmap.nominatim_status
Full name
openstreetmap.openstreetmap_nominatim_status
ParameterTypeRequiredDescription
No parameters.
overpass_query Read

Execute an Overpass QL query.

Lua path
app.integrations.openstreetmap.overpass_query
Full name
openstreetmap.openstreetmap_overpass_query
ParameterTypeRequiredDescription
No parameters.
overpass_status Read

Check Overpass API status.

Lua path
app.integrations.openstreetmap.overpass_status
Full name
openstreetmap.openstreetmap_overpass_status
ParameterTypeRequiredDescription
No parameters.
object_url Read

Build a stable OpenStreetMap node, way, or relation URL.

Lua path
app.integrations.openstreetmap.object_url
Full name
openstreetmap.openstreetmap_object_url
ParameterTypeRequiredDescription
No parameters.
url Read

Build a stable OpenStreetMap map URL for coordinates.

Lua path
app.integrations.openstreetmap.url
Full name
openstreetmap.openstreetmap_map_url
ParameterTypeRequiredDescription
No parameters.