{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/microsoft-azure-maps/json-schema/microsoft-azure-maps-geocoding-response-schema.json",
  "title": "GeocodingResponse",
  "description": "The successful response body returned by `Get Geocoding` and `Get Reverse Geocoding`, and\nthe per-batch-item success shape carried inside `GeocodingBatchResponse.batchItems`.\nEncoded as a [`GeoJSON FeatureCollection`](https://www.rfc-editor.org/rfc/rfc7946) whose\n`features` array contains one `Feature` per geocoded location.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/microsoft-azure-maps-geocode-api-openapi.yml#/components/schemas/GeocodingResponse",
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/$defs/FeatureCollectionEnum",
      "description": "The `GeoJSON` object type of a successful `Get Geocoding` or `Get Reverse Geocoding`\nresponse body. Always `FeatureCollection`, as defined in\n[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946)."
    },
    "features": {
      "type": "array",
      "description": "The array of `GeoJSON Feature` objects returned by the query. Each `Feature` represents a\nsingle geocoded location: its address components, match-quality indicators, and geocode\npoints are exposed via `properties`, and its primary coordinate via `geometry`.",
      "items": {
        "$ref": "#/$defs/FeaturesItem"
      }
    },
    "nextLink": {
      "type": "string",
      "description": "Contains the URL to fetch the next page of results if the response is paginated. This is\nuseful when the response is too large to be returned in a single call, allowing users to\nnavigate through multiple pages of results."
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "The address of a geocoded or autocomplete-suggested location, parsed into structured fields.\nSparseness is normal: only the fields that the resolved entity supplies are populated. For\nexample, `streetName` and `streetNumber` appear only for street-level addresses, and\n`intersection` appears only for road-intersection results.",
      "properties": {
        "addressLine": {
          "type": "string",
          "description": "The first line of the address, typically the street name and number. For example,\n`\"15127 NE 24th St\"`."
        },
        "locality": {
          "type": "string",
          "description": "The locality the address falls within: usually a city, town, or village. For example:\n`\"Redmond\"`."
        },
        "neighborhood": {
          "type": "string",
          "description": "The named neighborhood within the locality, when one is identified."
        },
        "adminDistricts": {
          "type": "array",
          "description": "The administrative subdivisions that contain the address, ordered from coarsest to finest.\nThe first entry is typically the first-order subdivision (such as a U.S. state or a\nCanadian province); subsequent entries cover finer divisions where the country, dependency,\nor region defines them (such as a county at index 1).",
          "items": {
            "$ref": "#/$defs/AddressAdminDistrictsItem"
          }
        },
        "postalCode": {
          "type": "string",
          "description": "The postal code for the address, when one is defined. Example: `\"98052\"`."
        },
        "countryRegion": {
          "$ref": "#/$defs/AddressCountryRegion",
          "description": "The country or region that contains the address, with its display name and ISO 3166-1\nAlpha-2 country code."
        },
        "formattedAddress": {
          "type": "string",
          "description": "The full address rendered as a single human-readable string, with the components joined\naccording to the conventions of the address's country or region. Example:\n`\"15127 NE 24th St, Redmond, WA 98052\"`."
        },
        "streetName": {
          "type": "string",
          "description": "The street name component of the address, when the resolved entity is a street-level\naddress. Example: `\"NE 24th St\"`."
        },
        "streetNumber": {
          "type": "string",
          "description": "The house or building number on the street, when the resolved entity is a street-level\naddress. Example: `\"15127\"`."
        },
        "intersection": {
          "$ref": "#/$defs/Intersection",
          "description": "The intersecting-street details for the address, populated when the resolved entity is a\n`RoadIntersection` (such as the corner of two named streets)."
        }
      }
    },
    "AddressAdminDistrictsItem": {
      "type": "object",
      "description": "An administrative subdivision that contains an address. For example, a state, province, or\ncounty. Returned as one entry in the parent `Address.adminDistricts` array, where entries are\nordered from coarsest to finest.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The full name of the subdivision. For example, `\"Washington\"` for a U.S. state, or\n`\"King County\"` for a county."
        },
        "shortName": {
          "type": "string",
          "description": "The short or abbreviated form of the subdivision name, when one is defined. For example,\n`\"WA\"` for a U.S. state. Finer subdivisions often have no distinct short form, in which case\n`shortName` repeats `name` (such as `\"King County\"`)."
        }
      }
    },
    "AddressCountryRegion": {
      "type": "object",
      "description": "The country or region that contains the address, identified by its display name and ISO 3166-1\nAlpha-2 country code. Either field may be omitted in a given response.",
      "properties": {
        "ISO": {
          "type": "string",
          "description": "The ISO 3166-1 Alpha-2 country code for the country or region. For example, `\"US\"` for the\nUnited States, or `\"GB\"` for the United Kingdom."
        },
        "name": {
          "type": "string",
          "description": "The display name of the country or region. For example, `\"United States\"`."
        }
      }
    },
    "CalculationMethodEnum": {
      "type": "string",
      "description": "The method that was used to compute the geocode point.",
      "enum": [
        "Interpolation",
        "InterpolationOffset",
        "Parcel",
        "Rooftop"
      ],
      "x-ms-enum": {
        "name": "CalculationMethodEnum",
        "modelAsString": true,
        "values": [
          {
            "name": "Interpolation",
            "value": "Interpolation",
            "description": "The geocode point was matched to a point on a road using interpolation."
          },
          {
            "name": "InterpolationOffset",
            "value": "InterpolationOffset",
            "description": "The geocode point was matched to a point on a road using interpolation with an additional\noffset to shift the point to the side of the street."
          },
          {
            "name": "Parcel",
            "value": "Parcel",
            "description": "The geocode point was matched to the center of a parcel."
          },
          {
            "name": "Rooftop",
            "value": "Rooftop",
            "description": "The geocode point was matched to the rooftop of a building."
          }
        ]
      }
    },
    "ConfidenceEnum": {
      "type": "string",
      "description": "The level of confidence that the geocoded location result is a match. Use this value together\nwith the match codes to obtain more complete information about the match.\n\nThe confidence of a geocoded location is based on many factors, including the relative\nimportance of the geocoded location and the user's location, if specified.",
      "enum": [
        "High",
        "Medium",
        "Low"
      ],
      "x-ms-enum": {
        "name": "ConfidenceEnum",
        "modelAsString": true,
        "values": [
          {
            "name": "High",
            "value": "High",
            "description": "If the confidence is set to `High`, one or more strong matches were found. Multiple `High`\nconfidence matches are sorted in ranked order by importance when applicable. For example,\nlandmarks have importance but addresses do not.\n\nIf a request includes a location or a view, then the ranking may change accordingly. For\nexample, a location query for \"Paris\" returns both \"Paris, France\" and \"Paris, TX\" with\n`High` confidence. \"Paris, France\" is always ranked first due to importance, unless a user\nlocation indicates that the user is in or very close to Paris, TX, or the map view indicates\nthat the user is searching in that area."
          },
          {
            "name": "Medium",
            "value": "Medium",
            "description": "In some situations, the returned match may not be at the same level as the information\nprovided in the request. For example, a request may specify address information and the\ngeocode service may only be able to match a postal code. In this case, if the geocode\nservice has confidence that the postal code matches the data, the confidence is set to\n`Medium` and the match code is set to `UpHierarchy` to indicate that the service could not\nmatch all of the information and had to search up-hierarchy.\n\nIf the location information in the query is ambiguous, and there is no additional information\nto rank the locations (such as user location or the relative importance of the location), the\nconfidence is set to `Medium`. For example, a location query for \"148th Ave, Bellevue\" may\nreturn both \"148th Ave SE\" and \"148th Ave NE\" with `Medium` confidence.\n\nIf the location information in the query does not provide enough information to geocode a\nspecific location, a less precise location value may be returned and the confidence is set to\n`Medium`. For example, if an address is provided but a match is not found for the house\nnumber, the geocode result with a `RoadBlock` entity type may be returned."
          },
          {
            "name": "Low",
            "value": "Low",
            "description": "Low confidence in the match."
          }
        ]
      }
    },
    "FeatureCollectionEnum": {
      "type": "string",
      "description": "The `GeoJSON` object type used at the root of successful responses from the forward\ngeocoding, reverse geocoding, and autocomplete operations (including their batch\nvariants). The only value is `FeatureCollection`, as defined in\n[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). `Get Polygon` is the one exception:\nits response root is a `GeoJSON Feature`, see `FeatureTypeEnum`.",
      "enum": [
        "FeatureCollection"
      ],
      "x-ms-enum": {
        "name": "FeatureCollectionEnum",
        "modelAsString": true,
        "values": [
          {
            "name": "FeatureCollection",
            "value": "FeatureCollection",
            "description": "The `GeoJSON FeatureCollection` object type. Appears as the root of every successful\ngeocoding, reverse geocoding, and autocomplete response body. `Get Polygon` uses a\n`Feature` root instead."
          }
        ]
      }
    },
    "FeatureTypeEnum": {
      "type": "string",
      "description": "The `GeoJSON` object type for `Feature` objects. Tags each entry inside the `features`\narray of a `FeatureCollection` response (geocoding, reverse geocoding, autocomplete) and\nappears at the root of the `Get Polygon` response. The only value is `Feature`, as\ndefined in [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946).",
      "enum": [
        "Feature"
      ],
      "x-ms-enum": {
        "name": "FeatureTypeEnum",
        "modelAsString": true,
        "values": [
          {
            "name": "Feature",
            "value": "Feature",
            "description": "The `GeoJSON Feature` object type. Appears on every Feature inside a `FeatureCollection`\nresponse, and at the root of the `Get Polygon` response."
          }
        ]
      }
    },
    "FeaturesItem": {
      "type": "object",
      "description": "A single entry in the `features` array of a `GeocodingResponse`, conforming to the\n[`GeoJSON Feature`](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) object shape.\nRepresents one geocoded location: structured data on `properties`, a representative\ncoordinate on `geometry`, and an optional bounding box on `bbox`.",
      "properties": {
        "type": {
          "$ref": "#/$defs/FeatureTypeEnum",
          "description": "The `GeoJSON` object type. Always `Feature`, as defined in\n[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946)."
        },
        "id": {
          "type": "string",
          "description": "An optional service-assigned identifier for the feature, when one is available."
        },
        "properties": {
          "$ref": "#/$defs/FeaturesItemProperties",
          "description": "Structured data about the geocoded location, including its entity type, match-quality\nindicators, address components, and one or more geocode points."
        },
        "geometry": {
          "$ref": "#/$defs/GeoJsonPoint",
          "description": "The primary [`GeoJSON Point`](https://tools.ietf.org/html/rfc7946#section-3.1.2)\nrepresenting the geocoded location, with coordinates in WGS 84 longitude/latitude order."
        },
        "bbox": {
          "type": "array",
          "description": "The smallest axis-aligned rectangle that contains the feature's geometry, in WGS 84\nlongitude/latitude order. Encoded as `[westLon, southLat, eastLon, northLat]` per\n[RFC 7946, Section 5](https://datatracker.ietf.org/doc/html/rfc7946#section-5).",
          "items": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "required": [
        "geometry"
      ]
    },
    "FeaturesItemProperties": {
      "type": "object",
      "description": "The `properties` payload of a feature in a `GeocodingResponse`. Carries the entity type and\nmatch-quality indicators for the geocoded location, its parsed address components, and one or\nmore geocode points that pin the location to specific coordinates.",
      "properties": {
        "type": {
          "type": "string",
          "description": "The entity type that the geocoded location resolved to. One of: `Address`, `RoadBlock`,\n`RoadIntersection`, `Neighborhood`, `PopulatedPlace`, `Postcode1`, `AdminDivision1`,\n`AdminDivision2`, or `CountryRegion`."
        },
        "confidence": {
          "$ref": "#/$defs/ConfidenceEnum",
          "description": "How strongly the geocoded location matches the request. Use together with `matchCodes` for a\ncomplete picture of match quality. See `ConfidenceEnum` for the value list and the factors\nthat influence the rating."
        },
        "matchCodes": {
          "type": "array",
          "description": "How the geocoding service produced this result relative to the query: a direct match at the\nrequested specificity (`Good`), one of several candidates (`Ambiguous`), or a fallback to a\nless precise level of the geographic hierarchy (`UpHierarchy`). Multiple values may be\npresent. For example, an `Ambiguous` plus `UpHierarchy` pairing indicates that the service\ncould not match the requested specificity and found multiple matches at a coarser level. See\n`MatchCodesEnum` for per-value descriptions; combine with `confidence` for a complete\npicture of match quality.",
          "items": {
            "$ref": "#/$defs/MatchCodesEnum"
          }
        },
        "address": {
          "$ref": "#/$defs/Address",
          "description": "The address of the geocoded location, parsed into structured fields such as locality, postal\ncode, country/region, and (when available) street name and number."
        },
        "geocodePoints": {
          "type": "array",
          "description": "One or more geocode points for the location, each marked with how it was derived\n(`calculationMethod`) and what it is best suited for (`usageTypes`). For example, `Display`\nfor visual placement on a map, or `Route` for use as a navigation destination.",
          "items": {
            "$ref": "#/$defs/GeocodePointsItem"
          }
        }
      }
    },
    "GeoJsonGeometry": {
      "type": "object",
      "description": "A valid `GeoJSON` geometry object. The type must be one of the seven valid\nGeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString,\nPolygon, MultiPolygon and GeometryCollection. Please refer to [RFC\n7946](https://tools.ietf.org/html/rfc7946#section-3.1) for details.",
      "properties": {
        "type": {
          "$ref": "#/$defs/GeoJsonObjectType",
          "description": "Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object\ntypes - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon,\nGeometryCollection, Feature and FeatureCollection."
        },
        "bbox": {
          "type": "array",
          "description": "Bounding box. Projection used - EPSG:3857. Please refer to [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946#section-5) for details.",
          "minItems": 4,
          "maxItems": 4,
          "items": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "required": [
        "type"
      ]
    },
    "GeoJsonObjectType": {
      "type": "string",
      "description": "Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object\ntypes - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon,\nGeometryCollection, Feature and FeatureCollection.",
      "enum": [
        "Point",
        "MultiPoint",
        "LineString",
        "MultiLineString",
        "Polygon",
        "MultiPolygon",
        "GeometryCollection",
        "Feature",
        "FeatureCollection"
      ],
      "x-ms-enum": {
        "name": "GeoJsonObjectType",
        "modelAsString": false,
        "values": [
          {
            "name": "GeoJsonPoint",
            "value": "Point",
            "description": "`GeoJSON Point` geometry."
          },
          {
            "name": "GeoJsonMultiPoint",
            "value": "MultiPoint",
            "description": "`GeoJSON MultiPoint` geometry."
          },
          {
            "name": "GeoJsonLineString",
            "value": "LineString",
            "description": "`GeoJSON LineString` geometry."
          },
          {
            "name": "GeoJsonMultiLineString",
            "value": "MultiLineString",
            "description": "`GeoJSON MultiLineString` geometry."
          },
          {
            "name": "GeoJsonPolygon",
            "value": "Polygon",
            "description": "`GeoJSON Polygon` geometry."
          },
          {
            "name": "GeoJsonMultiPolygon",
            "value": "MultiPolygon",
            "description": "`GeoJSON MultiPolygon` geometry."
          },
          {
            "name": "GeoJsonGeometryCollection",
            "value": "GeometryCollection",
            "description": "`GeoJSON GeometryCollection` geometry."
          },
          {
            "name": "GeoJsonFeature",
            "value": "Feature",
            "description": "`GeoJSON Feature` object."
          },
          {
            "name": "GeoJsonFeatureCollection",
            "value": "FeatureCollection",
            "description": "`GeoJSON FeatureCollection` object."
          }
        ]
      }
    },
    "GeoJsonPoint": {
      "type": "object",
      "description": "A valid `GeoJSON Point` geometry type. Please refer to [RFC\n7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details.",
      "properties": {
        "coordinates": {
          "type": "array",
          "description": "A `Position` is an array of numbers with two or more elements. The first two\nelements are _longitude_ and _latitude_, precisely in that order.\n_Altitude/Elevation_ is an optional third element. Please refer to [RFC\n7946](https://tools.ietf.org/html/rfc7946#section-3.1.1) for details.",
          "items": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "required": [
        "coordinates"
      ],
      "allOf": [
        {
          "$ref": "#/$defs/GeoJsonGeometry"
        }
      ],
      "x-ms-discriminator-value": "Point"
    },
    "GeocodePointsItem": {
      "type": "object",
      "description": "One geocode point for a location: a coordinate plus metadata describing how the point was\ncomputed (`calculationMethod`) and what it is best suited for (`usageTypes`). A single feature\ntypically returns separate `Display` and `Route` points so callers can pick the one that fits\nthe task.",
      "properties": {
        "geometry": {
          "$ref": "#/$defs/GeoJsonPoint",
          "description": "The coordinate of this geocode point as a\n[`GeoJSON Point`](https://tools.ietf.org/html/rfc7946#section-3.1.2), with values in WGS 84\nlongitude/latitude order."
        },
        "calculationMethod": {
          "$ref": "#/$defs/CalculationMethodEnum",
          "description": "How the point was computed. For example, snapped to the rooftop of a building or\ninterpolated along a road centerline. See `CalculationMethodEnum` for the value list."
        },
        "usageTypes": {
          "type": "array",
          "description": "What the geocode point is best suited for — `Display` for visual placement on a map, or\n`Route` as a routing destination. A point may carry both. See `UsageTypeEnum` for the\nper-value details, including how each is positioned for features with non-trivial extent.",
          "items": {
            "$ref": "#/$defs/UsageTypeEnum"
          }
        }
      }
    },
    "Intersection": {
      "type": "object",
      "description": "Intersection details for an address resolved as a road intersection — the corner where two or\nmore named streets meet. Populated only when the resolved entity is a `RoadIntersection`; the\nparent `Address.intersection` is otherwise omitted.",
      "properties": {
        "baseStreet": {
          "type": "string",
          "description": "The primary street of the intersection — typically the street the address number references."
        },
        "secondaryStreet1": {
          "type": "string",
          "description": "The first cross street that meets `baseStreet` at the intersection."
        },
        "secondaryStreet2": {
          "type": "string",
          "description": "The second cross street at the intersection, when one is present. Populated only for\nintersections of three or more streets."
        },
        "intersectionType": {
          "type": "string",
          "description": "A short label describing the form of the intersection. For example, distinguishing an\nat-grade crossroads from a grade-separated crossing such as a bridge or overpass."
        },
        "displayName": {
          "type": "string",
          "description": "A human-readable name for the intersection that combines the cross streets, such as\n`\"5th Avenue & Main Street\"`."
        }
      }
    },
    "MatchCodesEnum": {
      "type": "string",
      "description": "A match-code value indicating how the geocoding service produced a particular location\nresult. The `matchCodes` field on a feature is an array of these values; combine them with\n`confidence` and `type` to evaluate match quality.",
      "enum": [
        "Good",
        "Ambiguous",
        "UpHierarchy"
      ],
      "x-ms-enum": {
        "name": "MatchCodesEnum",
        "modelAsString": true,
        "values": [
          {
            "name": "Good",
            "value": "Good",
            "description": "The geocoding service produced this candidate without broadening the query: the result\nmatches the query at the specificity that was requested."
          },
          {
            "name": "Ambiguous",
            "value": "Ambiguous",
            "description": "The location is one of a set of possible matches. For example, when querying for the\nstreet address \"128 Main St.\", the response may return two locations for \"128 North Main\nSt.\" and \"128 South Main St.\" because there is not enough information to determine which\noption to choose."
          },
          {
            "name": "UpHierarchy",
            "value": "UpHierarchy",
            "description": "The location represents a move up the geographic hierarchy. This occurs when a match for\nthe location request was not found, so a less precise result is returned."
          }
        ]
      }
    },
    "UsageTypeEnum": {
      "type": "string",
      "description": "The intended use for a geocode point. A geocode point returned by the service carries one or\nmore usage types that indicate how a client application should consume the point: for\nexample, displaying the location on a map versus routing a vehicle to it.",
      "enum": [
        "Display",
        "Route"
      ],
      "x-ms-enum": {
        "name": "UsageTypeEnum",
        "modelAsString": true,
        "values": [
          {
            "name": "Display",
            "value": "Display",
            "description": "The geocode point is suitable for displaying the location on a map. For a feature with\nnon-trivial extent (such as a park or building), the `Display` point is typically near the\nvisual center of the feature."
          },
          {
            "name": "Route",
            "value": "Route",
            "description": "The geocode point is suitable as the destination of a route. For a feature with\nnon-trivial extent (such as a park or building), the `Route` point is typically positioned\nat a vehicle-accessible entrance rather than at the visual center."
          }
        ]
      }
    }
  }
}