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"
+}