Skip to content

Latest commit

 

History

History
80 lines (68 loc) · 3.85 KB

carmen-geojson.md

File metadata and controls

80 lines (68 loc) · 3.85 KB

carmen geojson

Carmen returns results as a GeoJSON FeatureCollection:

{
    "type": "FeatureCollection",
    "query": ["austin"],
    "features": [
        {
            "type": "Feature",
            "id": "place.4201",
            "text": "Austin",
            "place_name": "Austin, Texas, United States",
            "place_type": [ "place" ],
            "bbox": [-97.9383829999999, 30.098659, -97.5614889999999, 30.516863],
            "center": [-97.7559964, 30.3071816],
            "geometry": {
                "type": "Point",
                "coordinates": [-97.7559964, 30.3071816]
            },
            "properties": {
                "title": "Austin",
                "type": "city",
                "score": 600000790107194.8
            },
            "context": [
                {
                    "id": "province.293",
                    "text": "Texas"
                },
                {
                    "id": "country.51",
                    "text": "United States"
                }
            ]
        },
        ...
    ]
}

The GeoJSON object contains the following additional keys:

key description
query Array of tokens from input query.
attribution Optional. any source attribution for result set.

Each feature in the FeatureCollection has the following additional keys:

key description
id Id of the feature of the form {index}.{id} where index is the id/handle of the datasource that contributed the result.
text Text representing the feature (e.g. "Austin").
language Optional. The language code of the text returned in text.
place_name Human-readable text representing the full result hierarchy (e.g. "Austin, Texas, United States").
place_type An array of index types that this feature may be returned as. Most features have only one type matching its id.
bbox Optional. Array bounding box of the form [minx,miny,maxx,maxy].
address Where applicable. Contains the housenumber for the returned feature
center Array of the form [lon,lat].
context Array representing a hierarchy of parents. Each parent includes id, text keys.
routable_points Optional. Closest point on the relevant road, if the feature has an associated road. Will be returned if routing: true on request, and the feature's source is flagged as geocoder_routable in the tile json.
routable_points.points Optional. Array of points in the form of [{ coordinates: [lon, lat] }] or null if none were found.

For geocodes that include one or more language codes set by options.language, the following keys will also be returned for each language requested:

key description
text_{code} The text best suitable for display in the language {code}. This is often text in the language requested but may be retrieved from a closely related language if no value in the requested language is available but a fallback value is.
language_{code} The language code of the text returned in text_{code}. The value matches {code} unless language fallback has occurred.
place_name_{code} Full place name text, formatted to be suitable for display in the language {code}.

Feature properties

Carmen makes no specifications nor guarantees about the properties of each feature object. Feature properties are passed directly from indexes and may vary by feature and datasource.

Additional notes

  • Forward geocodes return features ordered by most relevant to least relevant to the input query.
  • Reverse geocodes return features in order of index hierarchy, usually ordered from most specific features to least specific features that overlap with the queried lon,lat pair.