API Documentation
GeoSearch Endpoints
- Search – Forward geocoding to find a place by address or name (more precise than autocomplete)
- Autocomplete – Real-time result suggestions without having to type the whole location (much faster than search)
Since GeoSearch is based on Pelias, see that documentation for more details.
- Pelias API documentation: github.com/pelias/documentation
- General Pelias info: github.com/pelias/pelias/
All GeoSearch requests share the same format:
https://geosearch.planninglabs.nyc/v2/search?text=120 broadway
\______/\________________________/\__/\____/\________________/
| | / \ |
scheme domain version path query
Which endpoint should I use?
Use the /autocomplete endpoint when the UI detects a user is typing. When a user pastes a complete address, the more precise /search endpoint should be used.
Search
Search only requires one parameter, the text you want to match in an address or place name. Just build a query where the text parameter is set to the place you want to find.
https://geosearch.planninglabs.nyc/v2/search?text=120 Bro
The example above returns a GeoJSON file containing the best matching results for the text 120 Bro. You’ll find the name of each matched locations in a property named label.
Spelling matters, but not capitalization. You can type broadway, Broadway, or even bRoAdWaY.
Results count
By default, the /search endpoint return 10 places. If you want a different number of results, set the size parameter to the desired number.
https://geosearch.planninglabs.nyc/v2/search?text=120 Bro&size=1
https://geosearch.planninglabs.nyc/v2/search?text=120 Bro&size=25
Other parameters
Since GeoSearch data is specific to New York City, not all parameters available in Pelias work the same. However, there are some other parameters that might be used to refine your search:
- Search within a rectangular region - Specify a boundary using the minimum and maximum latitude/longitude
- Search within a circular region - Specify a boundary using a maximum distance from a point
- Specify multiple boundaries - Results limited to the intersection of all specified boundaries
- Prioritize results by proximity - Prioritize results within geographic boundaries
Autocomplete
You can use the /autocomplete endpoint alongside /search to enable real-time feedback, helping users quickly find what they are looking for without specifying their full search terms. This is typically implemented with a drop-down list allowing users to choose from a list of search options.
To build a query with autocomplete, you need a text parameter, representing what a user has typed into your application.
https://geosearch.planninglabs.nyc/v2/autocomplete?text=120 Bro
Local focus
The /autocomplete endpoint can promote nearby results to the top of the list, while still allowing matches from farther away to be visible.
To focus your search based upon a geographical area, such as the center of the user's map or at the device's GPS location, supply the parameters focus.point.lat and focus.point.lon. This boosts locally relevant results higher.
100 Broadway returns Manhattan first:https://geosearch.planninglabs.nyc/v2/autocomplete?text=100 East BroadwayAnd this query for
100 Broadway returns Staten Island first:https://geosearch.planninglabs.nyc/v2/autocomplete?text=100 East Broadway&focus.point.lat=40.5693781&focus.point.lon=-74.1322297
User Experience
There are pitfalls to watch out for when implementing a client-side typeahead solution:
Requests must be throttled
Since autocomplete requests generally correspond directly to user input, it’s important to account for fast typers and throttle requests when using the autocomplete endpoint. Some devices and networks (for example, mobile phones on a slow connection) may respond poorly when too many requests are sent too quickly, so be sure to do some testing on your own.
Responses are asynchronous
This means you cannot be sure responses will be returned in the same order they were requested. If you were to send two queries synchronously, first 'Bro' then 'Broadway', you may find the 'Broadway' response would arrive before the 'Bro' response. This will result in a quick flash of 'Broadway' results followed by the results for 'Bro', which can confuse the user.
Available autocomplete parameters
| Parameter | Type | Required | Example |
|---|---|---|---|
text | string | Yes | 120 Broadway |
focus.point.lat | floating point number | No | 48.581755 |
focus.point.lon | floating point number | No | 7.745843 |
boundary.rect.min_lon | floating point number | No | 139.2794 |
boundary.rect.max_lon | floating point number | No | 140.1471 |
boundary.rect.min_lat | floating point number | No | 35.53308 |
boundary.rect.max_lat | floating point number | No | 35.81346 |
Results
Results from GeoSearch are GeoJSON. The top-level structure to every response looks like this:
{
"geocoding":{...},
"type":"FeatureCollection",
"features":[...],
"bbox":[...]
}Features
The features property is where you’ll find the list of places that best matched your input parameters. Each item in this list will contain human-readable information in its properties block, as well as computer-friendly coordinates in its geometry property (in longitude, latitude order).
Name – The
nameis a short description of the location—either the house number and street, or name of the non-addressable place.Label – The
labelis a human-friendly representation of the place, with the most complete details, that is ready to be displayed to an end user.Confidence – The
confidencescore in the/searchendpoint is an estimation of how accurately the result matches the query. It primarily takes into account how well properties in the result match what was expected from parsing the input text.
Bounding box
The bbox property describes the geographic extent of the entire FeatureCollection.