addedInput schema / properties / city
Added value: +{
+ "description": "Structured component: town or city, e.g. \"London\". Matches the\ncontaining city as well as the immediate locality, so a suburb name\nworks here too.",
+ "type": [
+ "string",
+ "null"
+ ]
+}
addedInput schema / properties / country
Added value: +{
+ "description": "Structured component: ISO 3166-1 alpha-2 code or country name —\n\"GB\", \"gb\", \"United Kingdom\" and \"UK\" all mean the same country.\nA value naming no country is refused rather than quietly applied as\na filter that matches nothing.",
+ "type": [
+ "string",
+ "null"
+ ]
+}
addedInput schema / properties / housenumber
Added value: +{
+ "description": "Structured component: house number, e.g. \"10\" or \"221B\". Only\nmeaningful alongside `street` — a house number on its own excludes\nnearly everything and identifies nothing.",
+ "type": [
+ "string",
+ "null"
+ ]
+}
addedInput schema / properties / postcode
Added value: +{
+ "description": "Structured component: postcode in any spacing or case — \"SW1A 2AA\"\nand \"sw1a2aa\" are one query. A bare UK outward code (\"SW1A\")\nselects the whole district.",
+ "type": [
+ "string",
+ "null"
+ ]
+}
changedInput schema / properties / query / description
Previous value: -"Free-text place query, e.g. \"Dover ferry terminal\"."New value: +"Free-text place query, e.g. \"Dover ferry terminal\". Required unless\nat least one structured component is supplied."
changedInput schema / properties / query / type
Previous value: -"string"New value: +[
+ "string",
+ "null"
+]
addedInput schema / properties / street
Added value: +{
+ "description": "Structured component: street name, e.g. \"Downing Street\". Matches\nthe street of addresses and POIs (transliterated street names\nincluded) as well as the street itself.",
+ "type": [
+ "string",
+ "null"
+ ]
+}
removedInput schema / required
Removed value: -[
- "query"
-]
addedOutput schema / $defs / GeocodeHit / properties / match
Added value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/GeocodeMatch"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "How far this hit can be trusted to be the place that was asked\nfor — see [`GeocodeMatch`]. Present whenever the MapMap gateway\nanswered; absent on a deployment falling back to the direct Photon\ngeocoder, and absent on the gateway's own fast paths (a pasted\ncoordinate pair, a bare UK outward code, a category browse), which\nanswer without a ranking to report on."
+}
addedOutput schema / $defs / GeocodeMatch
Added value: +{
+ "description": "How well one geocoding result answers what was actually asked.\n\nGeocoding's real failure mode is not \"no answer\" but a confident answer\nto a different question: a plausible row on the wrong street, with\nnothing in the response to say so. This object is that missing say-so,\nand an agent should read it before acting on an address.\n\nHow to read it:\n\n* Any component `unmatched` or `inferred` on the TOP hit means the\n answer does not carry the address that was asked for — an `unmatched`\n postcode means the result has no postcode at all, `inferred` means it\n has a different one. Neither is a match. Say so rather than presenting\n the hit as the address, and reach for `verify_places` when the address\n came from a model or a user and needs checking rather than using.\n* A small `score_gap` means the ranking barely chose between this hit\n and the runner-up, which is exactly when to show the alternatives\n instead of picking one for the user.",
+ "properties": {
+ "components": {
+ "$ref": "#/$defs/GeocodeMatchComponents",
+ "description": "Per-component verdict on this hit: one entry for each structured\ncomponent supplied, and empty when the query was free text only."
+ },
+ "score_gap": {
+ "description": "The top result's score minus the runner-up's, rounded to 3 decimal\nplaces. `0` for a single result, and `0` from the `photon` source,\nwhich publishes no per-result score — so a `0` is \"no signal\", not\n\"a tie\".",
+ "format": "double",
+ "type": "number"
+ },
+ "source": {
+ "description": "Which backend answered: \"mapmap-index\" (the first-party index) or\n\"photon\".",
+ "type": "string"
+ }
+ },
+ "required": [
+ "components",
+ "score_gap",
+ "source"
+ ],
+ "type": "object"
+}
addedOutput schema / $defs / GeocodeMatchComponents
Added value: +{
+ "description": "Per-component verdicts inside a [`GeocodeMatch`]. Each is one of\n\"matched\", \"inferred\" or \"unmatched\"; a component that was not supplied\nis absent entirely.\n\n* \"matched\" — the result's own field carries the value asked for (case-\n and accent-insensitive, and by containment, so `city: \"London\"`\n matches \"City of London\").\n* \"inferred\" — the result carries a value for that component, but not\n the one asked for. It reached the page through ranking, as when a\n street is found by its transliterated name and displayed under its\n canonical one.\n* \"unmatched\" — the result carries no value for that component at all.",
+ "properties": {
+ "city": {
+ "description": "Verdict on the supplied `city`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "country": {
+ "description": "Verdict on the supplied `country`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "housenumber": {
+ "description": "Verdict on the supplied `housenumber`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "postcode": {
+ "description": "Verdict on the supplied `postcode`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "street": {
+ "description": "Verdict on the supplied `street`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}