mapbox
Document "Carmen format" more precisely
The localGeocoder property is a function which returns results in the Carmen GeoJSON format. However, this statement is not enough to tell you which fields your function must provide.
It is also a bit loose, as the documentation for that format shows a FeatureCollection, whereas mapbox-gl-geocoder expects an array of Features.
The API doc links through to https://github.com/mapbox/carmen/blob/master/carmen-geojson.md which documents this, however you're right it doesn't show which fields are required. I think it's okay to document the required fields.
The API doc says "Expected to return an Array of GeoJSON Features" so it's clear it shouldn't be a FeatureCollection, feel free to suggest better wording if you think it could be made clearer.
I think a quick statement to the effect, "In particular, the center, place_name and text attributes are required".
I think a quick statement to the effect, "In particular, the center, place_name and text attributes are required".
I haven't checked but I think place_name is only required if you're using the default getItemValue option, if you supply your own getItemValue then place_name is not required.
Is text required? I did a quick look and didn't see where, I'm probably missing it.
I can help review a PR if you wanted to propose a change :wink:
The thought occurs to me that if so few fields are actually used, then it's probably just adding unnecessary complication to even refer to the Carmen format. It's probably simpler to simply document the three fields in question.
My thinking was the localGeocoder should return results in the same format as the Mapbox Geocoding API so that results could be consistently formatted together. I can't remember why I choose to mention carmen's documentation directly and not https://docs.mapbox.com/api/search/#geocoding-response-object.
I don't see any issue with changing it to document only what's required, and then also what's optional (eg. bbox is used if given but not required).
The link https://github.com/mapbox/carmen/blob/master/carmen-geojson.md is dead now.
The link https://github.com/mapbox/carmen/blob/master/carmen-geojson.md is dead now.
https://web.archive.org/web/20210224184722/https://github.com/mapbox/carmen/blob/master/carmen-geojson.md
