ThinAir Geo

geocode

Read-onlyIdempotent

Convert an address, place name, street, or intersection into coordinates and structured location results. Use when input is text and you need coordinates before routing, weather, or search. Supports street-level resolution and proximity biasing.

Input Schema

TableJSON Schema

Name	Required	Description
`size`	No	Number of candidates to return (default 5, max 40)
`query`	Yes	Address, place name, street, intersection (e.g. 'Broadway and 42nd Street New York'), or free-form location text
`layers`	No	Restrict to: address, street, venue, locality. Use layers=street when user clearly wants a street entity. Use layers=venue for stadiums, monuments, parks, and named POIs (e.g. 'Minute Maid Park', 'Lambeau Field', 'Statue of Liberty') — bypasses address-parser tokenization that otherwise resolves venue+state to the state region centroid
`focus_lat`	No	Bias results near this latitude — use when user says 'near me' or 'close to'
`focus_lon`	No	Bias results near this longitude
`boundary_country`	No	ISO country code to reduce ambiguity (alpha-2 or alpha-3)

Output Schema

TableJSON Schema

Name	Required	Description
`items`	No
`geojson`	No
`metrics`	No
`summary`	No	Map of scalar facts the LLM should surface verbatim
`precision`	No
`display_hint`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 13, 2026

changedOutput schema / properties / items / items / properties / postal_code / description

Previous value: -"An eligible US ZIP5 normalized from the selected native result's available postal-code field; direct address-record origin is not yet guaranteed. Not checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."New value: +"An eligible US ZIP5 read from the selected result's own postal-code field. While origin enforcement is active this field is emitted ONLY when the engine stamped the value as coming from the address record itself (`source_record` provenance); a value inherited from a parent area, or a result cached before that evidence existed, is omitted rather than emitted without provenance — so an absent ZIP under enforcement means \"not proven for this record\", not \"no such ZIP\". Provenance describes only WHERE the value came from. It is not a postal operator check of any kind — no certification, no address-quality rating, and no statement about whether mail would arrive — so a syntactically correct, correctly-sourced value can still be wrong for the address. Also omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."

Changed2 schema fields changedSep 13, 2026

addedOutput schema / properties / items / items / properties / address_components / properties / region_name
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / items / items / properties / postal_input_match

Added value: +{
+  "description": "STRUCTURED GEOCODING ONLY (`geocode_structured` / `POST /v1/search/structured`); absent from free-text geocoding. Whether the postcode YOU SUBMITTED agrees with this candidate's own postcode — `match` (same five-digit value), `conflict` (they differ), `unavailable` (no comparison was possible). This compares two values already in hand: no lookup, no external reference, and your query text is never parsed to find one. `conflict` does NOT say which side is wrong — your input may name a neighbouring area, the candidate may be a near-miss, or the record's own value may be stale; treat it as a prompt to ask a human, never as a correction to apply automatically. The candidate side counts only when its postcode came from the address record itself; one inherited from a parent area yields `unavailable` rather than a misleading verdict. `unavailable` also covers: nothing submitted, a submitted value not readable as a US five-digit code, and results cached before this field existed.",
+  "enum": [
+    "match",
+    "conflict",
+    "unavailable"
+  ],
+  "type": "string"
+}

Changed5 schema fields changedSep 12, 2026

addedOutput schema / properties / items / items / properties / address_components

Added value: +{
+  "additionalProperties": false,
+  "description": "The same US components the formatted string is built from. Every field is source-established or absent; nothing is inferred or back-filled.",
+  "properties": {
+    "country_code": {
+      "type": "string"
+    },
+    "house_number": {
+      "type": "string"
+    },
+    "locality": {
+      "type": "string"
+    },
+    "postal_code": {
+      "type": "string"
+    },
+    "region_code": {
+      "type": "string"
+    },
+    "street": {
+      "type": "string"
+    },
+    "unit": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / items / items / properties / address_line1

Added value: +{
+  "description": "House number and street for an eligible US address result, composed from the result's own components — never parsed from the display label. Absent when the result is not a US street address.",
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / address_line2

Added value: +{
+  "description": "Unit or suite, only when the source record carries one. A unit supplied in your request is never echoed back here.",
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / formatted_address

Added value: +{
+  "description": "Single-line US display form, e.g. `1600 Pennsylvania Avenue NW, Washington, DC 20500, USA`. The postal segment is present only when an eligible ZIP is; its absence never suppresses the street address.",
+  "type": "string"
+}

changedOutput schema / properties / items / items / properties / postal_code / description

Previous value: -"Five-digit ZIP taken from the postcode supplied with this address record. It is reported by that record's own data source and has not been checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."New value: +"An eligible US ZIP5 normalized from the selected native result's available postal-code field; direct address-record origin is not yet guaranteed. Not checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."

Changed1 schema field changedSep 11, 2026

addedOutput schema / properties / items / items / properties / postal_code

Added value: +{
+  "description": "Five-digit ZIP taken from the postcode supplied with this address record. It is reported by that record's own data source and has not been checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied.",
+  "pattern": "^[0-9]{5}$",
+  "type": "string"
+}

Changed2 schema fields changedSep 10, 2026

addedOutput schema / properties / items / items / properties / address_evidence

Added value: +{
+  "additionalProperties": false,
+  "description": "What THIS CANDIDATE carries, component by component — `matched` (a real value is present), `partial` (only a coarser or derived stand-in, e.g. an interpolated house number or a locality falling back to its administrative parent), `absent` (nothing). This describes the result, NOT a comparison against your query: the engine returns no per-component match data, and re-parsing your text here would mean two parsers disagreeing about the same string. Derived from the feature, never from `confidence`.",
+  "properties": {
+    "house_number": {
+      "enum": [
+        "matched",
+        "partial",
+        "absent"
+      ],
+      "type": "string"
+    },
+    "locality": {
+      "$ref": "#/properties/items/items/properties/address_evidence/properties/house_number"
+    },
+    "postal_code": {
+      "description": "Whether the candidate carries a postal code. Presence only — this states what the result has, and makes no claim about its correctness.",
+      "enum": [
+        "matched",
+        "partial",
+        "absent"
+      ],
+      "type": "string"
+    },
+    "region": {
+      "$ref": "#/properties/items/items/properties/address_evidence/properties/house_number"
+    },
+    "street": {
+      "$ref": "#/properties/items/items/properties/address_evidence/properties/house_number"
+    }
+  },
+  "required": [
+    "house_number",
+    "street",
+    "locality",
+    "region",
+    "postal_code"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / items / items / properties / confidence_scope

Added value: +{
+  "const": "query_to_candidate",
+  "description": "What `confidence` is scoped to. `query_to_candidate` means it scores how well this candidate matches the submitted query — it is NOT a probability that the place is real, that the address is correct, or that mail would arrive. Fixed value today; treat it as a closed set that may gain members.",
+  "type": "string"
+}

Changed21 schema fields changedAug 17, 2026

changedInput schema / properties / boundary_country / description

Previous value: -"ISO country code to reduce ambiguity"New value: +"ISO country code to reduce ambiguity (alpha-2 or alpha-3)"

addedInput schema / properties / boundary_country / maxLength
```
Added value: +3
```
addedInput schema / properties / focus_lat / maximum
```
Added value: +90
```
addedInput schema / properties / focus_lat / minimum
```
Added value: +-90
```
addedInput schema / properties / focus_lon / maximum
```
Added value: +180
```
addedInput schema / properties / focus_lon / minimum
```
Added value: +-180
```
addedInput schema / properties / layers / maxLength
```
Added value: +200
```
addedInput schema / properties / query / maxLength
```
Added value: +2000
```

changedInput schema / properties / size / description

Previous value: -"Number of candidates to return (default 5)"New value: +"Number of candidates to return (default 5, max 40)"

addedInput schema / properties / size / maximum
```
Added value: +40
```
addedInput schema / properties / size / minimum
```
Added value: +1
```
changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

addedOutput schema / properties / items / items / properties / cross_street_kind

Added value: +{
+  "enum": [
+    "street",
+    "route"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / cross_street_route

Added value: +{
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / id
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / items / items / properties / intersection_precision

Added value: +{
+  "enum": [
+    "geometric_crossing",
+    "tangent_intersection",
+    "centroid_cluster",
+    "approximate"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / intersection_type

Added value: +{
+  "enum": [
+    "corner",
+    "interchange"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / street_kind

Added value: +{
+  "enum": [
+    "street",
+    "route"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / items / items / properties / street_route

Added value: +{
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / metrics
```
Added value: +{}
```

addedOutput schema / properties / precision

Added value: +{
+  "additionalProperties": true,
+  "properties": {
+    "class": {
+      "type": "string"
+    },
+    "learning_overlay": {
+      "additionalProperties": true,
+      "properties": {
+        "actions": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "applied": {
+          "type": "boolean"
+        },
+        "rule_ids": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "applied"
+      ],
+      "type": "object"
+    },
+    "required_context": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "risk_flags": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "class",
+    "risk_flags",
+    "required_context",
+    "learning_overlay"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 10, 2026

changedInput schema / properties / layers / description

Previous value: -"Restrict to: address, street, venue, locality. Use layers=street when user clearly wants a street entity"New value: +"Restrict to: address, street, venue, locality. Use layers=street when user clearly wants a street entity. Use layers=venue for stadiums, monuments, parks, and named POIs (e.g. 'Minute Maid Park', 'Lambeau Field', 'Statue of Liberty') — bypasses address-parser tokenization that otherwise resolves venue+state to the state region centroid"

Changed1 schema field changedMay 1, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "display_hint": {
+      "additionalProperties": true,
+      "properties": {
+        "layout": {
+          "anyOf": [
+            {
+              "enum": [
+                "summary",
+                "table",
+                "summary+table",
+                "map",
+                "chart+table"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "map_layers": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "preferred_charts": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "sections": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "layout"
+      ],
+      "type": "object"
+    },
+    "geojson": {
+      "additionalProperties": true,
+      "properties": {
+        "features": {
+          "items": {
+            "additionalProperties": true,
+            "properties": {
+              "geometry": {
+                "anyOf": [
+                  {
+                    "additionalProperties": true,
+                    "properties": {
+                      "coordinates": {},
+                      "geometries": {
+                        "items": {},
+                        "type": "array"
+                      },
+                      "type": {
+                        "anyOf": [
+                          {
+                            "enum": [
+                              "Point",
+                              "LineString",
+                              "Polygon",
+                              "MultiPoint",
+                              "MultiLineString",
+                              "MultiPolygon",
+                              "GeometryCollection"
+                            ],
+                            "type": "string"
+                          },
+                          {
+                            "type": "string"
+                          }
+                        ]
+                      }
+                    },
+                    "required": [
+                      "type"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number"
+                ]
+              },
+              "properties": {
+                "additionalProperties": {},
+                "type": "object"
+              },
+              "type": {
+                "const": "Feature",
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "geometry"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "type": {
+          "const": "FeatureCollection",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "features"
+      ],
+      "type": "object"
+    },
+    "items": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "confidence": {
+            "type": "number"
+          },
+          "label": {
+            "type": "string"
+          },
+          "lat": {
+            "type": "number"
+          },
+          "layer": {
+            "type": "string"
+          },
+          "lon": {
+            "type": "number"
+          },
+          "method": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "place_type": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "summary": {
+      "additionalProperties": {},
+      "description": "Map of scalar facts the LLM should surface verbatim",
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedApr 29, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
First observedApr 28, 2026

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds behavioral capability context ('street-level resolution and proximity biasing'), which is useful, but says nothing about result ordering, fallback behavior when no match, or accuracy/rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core operation before usage and capabilities. Compact and no filler, though the capability sentence is somewhat redundant with the schema's parameter descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. The description covers what the tool does, when to use it, and its resolution capability, which is enough for a geocoding call. The main gap is lack of sibling differentiation in a crowded geocoding family.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are already richly documented in the schema (including the detailed layers guidance and focus_lat/lon biasing). The description only gestures at 'proximity biasing,' which the schema already explains, so it adds little beyond the structured fields. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Convert') and resource ('address, place name, street, or intersection into coordinates'). This implicitly distinguishes it from reverse_geocode (the inverse operation), though it never names siblings like geocode_structured or batch_geocode for explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides usage context ('Use when input is text and you need coordinates before routing, weather, or search'), which implies when the tool is needed. However, it does not distinguish this tool from near-siblings such as geocode_structured, batch_geocode, or resolve_intersection, leaving the agent to infer which one to pick.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ThinAir Geo tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?