This documentation is a work in progress and subject to change.

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.

All GeoSearch requests share the same format:

https://geosearch.planninglabs.nyc/v1/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/v1/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/v1/search?text=120 Bro&size=1
https://geosearch.planninglabs.nyc/v1/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:


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/v1/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.

This query for 100 Broadway returns Manhattan first:
https://geosearch.planninglabs.nyc/v1/autocomplete?text=100 East Broadway
And this query for 100 Broadway returns Staten Island first:
https://geosearch.planninglabs.nyc/v1/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

ParameterTypeRequiredExample
textstring Yes120 Broadway
focus.point.latfloating point number No48.581755
focus.point.lonfloating point number No7.745843
boundary.rect.min_lonfloating point number No139.2794
boundary.rect.max_lonfloating point number No140.1471
boundary.rect.min_latfloating point number No35.53308
boundary.rect.max_latfloating point number No35.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 name is a short description of the location—either the house number and street, or name of the non-addressable place.

  • Label – The label is a human-friendly representation of the place, with the most complete details, that is ready to be displayed to an end user.

  • Confidence – The confidence score in the /search endpoint 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.