--- title: "Structured Geocoding" method: GET path: "/search/structured" tags: ["Search / Forward Geocoding"] --- # Structured Geocoding `GET /search/structured` Structured Query offers a more specific way to search for locations. Instead of using a single text string, you can provide distinct address components in a structured format. This includes specifying elements like street, neighborhood, city, state, country, and postal code, each sent as separate API parameters. ## Query parameters - `street` string - `city` string - `county` string - `state` string - `country` string - `postalcode` string - `format` 'xml' | 'json' | 'xmlv1.1' - `addressdetails` 0 | 1 - `statecode` 0 | 1 - `viewbox` string - `bounded` 0 | 1 - `limit` integer - `accept-language` string - `countrycodes` string - `normalizeaddress` 0 | 1 - `normalizecity` 0 | 1 - `postaladdress` 0 | 1 - `matchquality` 0 | 1 - `source` string - `normalizeimportance` 0 | 1 - `dedupe` 0 | 1 - `namedetails` 0 | 1 - `extratags` 0 | 1 - `polygon_geojson` 0 | 1 - `polygon_kml` 0 | 1 - `polygon_svg` 0 | 1 - `polygon_text` 0 | 1 - `json_callback` string ## Response `200` OK - object[] - `place_id` string, required — Unique identifier for the place. - `licence` string, required — License information for the data. - `osm_type` string — Type of OpenStreetMap object. - `osm_id` string — Unique identifier for the OpenStreetMap object. - `lat` string, required — Latitude of the location. - `lon` string, required — Longitude of the location. - `display_name` string, required — Formatted address for display. - `class` string — The category of this result - `type` string — The 'type' of the class/category of this result - `importance` number, float — Calculated importance of this result compared to the search query the user has provided. Ranges between 0 and 1. - `address` union - Address — Breakdown of the address into elements. All these elements are optional and only those elements that are available for a given location will be returned. - `house_number` string — House number - `road` string — Road name - `neighbourhood` string — Neighbourhood - `hamlet` string — Hamlet - `suburb` string — Suburb - `village` string — Village name - `town` string — Town name - `city_district` string — Administrative area between city level and town level - `city` string — City name - `region` string — Region name - `county` string — County name - `state_district` string — District name - `state` string — State name - `state_code` string — State code - `postcode` string — Postal code - `country` string — Country name - `country_code` string — Country code - `name` string — Name of the entity/road in the given location - `water` string — The name of an ocean or sea, if the location falls within a body of water outside any country's administrative regions. - AddressNormalized — The default address section returns a wide range of elements - from common ones such as `road` and `country` to obscure ones such as `hamlet`, `cycleway`, `park`. This was done to maintain backward compatibility with OpenStreetMap's Nominatim. To make parsing easier for developers, the `normalizeaddress` parameter rolls up elements in the `address` section of the response to the list of elements defined below. - `name` string — House name or Point of Interest (POI) - `house_number` string — House or Building number - `road` string — Roads, Highways, Freeways, Motorways - `neighbourhood` string — Neighbourhoods, Allotments, Quarters, Communities - `suburb` string — Suburbs, Subdivisions - `island` string — Islands, Islets - `city` string — Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets - `county` string — Counties - `state` string — States, Provinces, Regions, State Districts - `state_code` string — State or Province Code - `postcode` string — Postal Codes, Zipcodes - `country` string — Countries, Nation-states - `country_code` string — Country Code - 2 letter (ISO 3166-1 alpha-2) - `boundingbox` string[], required — List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon]. - `namedetails` Namedetails — The dictionary with full list of available names including ref etc. Returned when `namedetails=1` is set in the request. - `name` string - `extratags` Extratags — The dictionary with additional useful tags like website or maxspeed. Returned when `extratags=1` is set in the request. - `geojson` Geojson — Output geometry of results in geojson format. Returned when `polygon_geojson=1` is set in the request. - `type` string - `coordinates` number[] - `geokml` string — Output geometry of results in kml format. Returned when `polygon_kml=1` is set in the request. - `svg` string — Output geometry of results in svg format. Returned when `polygon_svg=1` is set in the request. - `geotext` string — Output geometry of results as a WKT. Returned when `polygon_text=1` is set in the request. - `icon` string — The URL of an icon representing this result, if applicable. - `matchquality` Matchquality — An additional object `matchquality` for every result in the response, containing the following elements: `matchcode`, `matchtype`, `matchlevel`. - `matchcode` string — Specifies the quality of the returned address. matchcode | description ------------|--------------- exact | The result matches the input query with a high level of probability. fallback | The result does not exactly match the input but is closely related to it provided there is direct a heierarchial relation. approximate| The result matches the input query with a medium to low level of probability. - `matchtype` string — Specifies quality of the returned location match matchtype | description --------------|--------------- point | The coordinate returned is a point address, typically with rooftop accuracy. centroid | The coordinate returned is a centroid of a road or administrative boundary. interpolated | The coordinate returned is a point determined by interpolation. - `matchlevel` string — Specifies the most granular address element that matches the geocoding query. matchlevel | details -----------------|--------------- venue | The returned address is of a Point of Interest (PoI) level. building | The returned address is of a house level. street | The returned address is on a street level. neighbourhood | The returned address is on a neighbourhood level. island | The returned address is on a island level. borough | The returned address is on a borough level. city | The returned address is on a city level. county | The returned address is on a county level. state | The returned address is on a state level. country | The returned address is on a country level. marine | The returned address is on a marine level. postalcode | The returned address is on a postalcode level. - `postaladdress` string — Returns address specifically formatted for each country. Returned when `postaladdress` is set in the request ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — The request has been made from an unauthorized domain. - `404` — No location or places were found for the given input. - `429` — Request exceeded the rate-limits set on your account. - `500` — Internal Server Error --- [API](https://skmtc.net/locationiq/apis/locationiq-api-reference.md) · [All operations](https://skmtc.net/locationiq/apis/locationiq-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/locationiq/locationiq-api-reference/versions/62f2eab3d1ff/schema)