Rhonda Glennon
9 years ago
9 changed files with 220 additions and 127 deletions
@ -1,28 +1,113 @@
|
||||
# Search with autocomplete |
||||
|
||||
If you are building an end-user application, you can enable `/autocomplete` alongside the `/search` to add real-time feedback to help users find what they are looking for more easily, without requiring them to type the entire search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list. |
||||
If you are building an end-user application, you can use the `/autocomplete` endpoint alongside `/search` to enable real-time feedback. This type-ahead functionality helps users find what they are looking for more easily, without requiring them to fully specify their search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list below. |
||||
|
||||
To get started with autocomplete, you need only a developer key and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify the number of results to return and where the search should be centered. |
||||
To build a query with autocomplete, you need [a free, API developer key](https://mapzen.com/developers) and a `text` parameter, representing what a user has typed into your application so far. Optionally, you can specify a geographic point where the search is focused, this will allow users to see more local places in the results. |
||||
|
||||
In the interest of not overloading Mapzen search, please allow a reasonable amount of time between user keystrokes before querying. That is, a fast typer may have only milliseconds between keystrokes. Querying Mapzen search on every keystroke would result in a number of requests that would not respond in time to display results before the next request was sent. A good rule of thumb is to allow a delay of `x` milliseconds before sending the entered text. |
||||
## User experience guidelines |
||||
|
||||
### Size |
||||
There are two user experience pitfalls to watch out for when implementing a client-side typeahead solution: |
||||
|
||||
The default number of results that an autocomplete request will return is 10, but this can be overridden using the `size` parameter. The default value for `size` is `10` and the maximum value is `40`. Specifying a value greater than `40` will override to `40` and return a warning in the response metadata. |
||||
**Requests must be throttled.** The client must only send a maximum of one or two requests per second. Sending requests more frequently than this will result in a sluggish network and laggy user interface for mobile consumers. A general rule is to account for fast typers by batching their keystrokes and sending the input text no more than twice per second. Mapzen Search limits the amount of requests per second (per api key), so be sure to account for those limits in your throttle code. [Learn more in this interactive demo.](http://jsfiddle.net/missinglink/19e2r2we/) |
||||
|
||||
### Focus.point.lat and Focus.point.lon |
||||
**Responses are asynchronous.** There is no guarantee that responses will be returned in the same order they were requested. If you were to send two queries synchronously, first `'Lo'` then `'London'`, you may find the `'London'` response would arrive before the `'Lo'` response. This will result in a quick flash of `'London'` results followed by the results for `'Lo'`, which can confuse the user. You must account for this behavior by storing the `requested_at` timestamps for each request and discarding older responses when they arrive late. |
||||
|
||||
To center your search based upon a geographical area, such as a map or the user's current location, supply the parameters `focus.point.lat` and `focus.point.lon`. The following request is centered on northeastern France and is searching for `Strasb`: |
||||
## Global scope, local focus |
||||
|
||||
http://search.mapzen.com/v1/autocomplete?api_key=search-XXXXXXX&text=strasb&focus.point.lat=48.581755&focus.point.lon=7.745843 |
||||
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. For example, if you search for `Union Square`: |
||||
|
||||
From San Francisco: |
||||
|
||||
### Parameters |
||||
> /v1/autocomplete?api_key=search-XXXXXXX&text=union%20square&focus.point.lat=37.7&focus.point.lon=-122.4 |
||||
|
||||
Parameter | Type | Required | Default | Example |
||||
--- | --- | --- | --- | --- |
||||
`api_key` | string | yes | none | [get yours here!](https://mapzen.com/developers) |
||||
`text` | string | yes | none | `Strasbour` |
||||
`focus.point.lat` | floating point number | yes | none | `48.581755` |
||||
`focus.point.lon` | floating point number | yes | none | `7.745843` |
||||
`size` | integer | no | `10` | `3` |
||||
```json |
||||
{ |
||||
"type": "Feature", |
||||
"properties": { |
||||
"label": "Union Square, San Francisco, CA" |
||||
}, |
||||
"geometry": { |
||||
"type": "Point", |
||||
"coordinates": [ |
||||
-122.40776, |
||||
37.78576 |
||||
] |
||||
} |
||||
} |
||||
``` |
||||
|
||||
From New York City: |
||||
|
||||
> /v1/autocomplete?api_key=search-XXXXXXX&text=union%20square&focus.point.lat=40.7&focus.point.lon=-73.9 |
||||
|
||||
```json |
||||
{ |
||||
"type": "Feature", |
||||
"properties": { |
||||
"label": "Union Square, Manhattan, NY" |
||||
}, |
||||
"geometry": { |
||||
"type": "Point", |
||||
"coordinates": [ |
||||
-73.99027, |
||||
40.73624 |
||||
] |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The `/autocomplete` endpoint can promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. For example, searching `McDonalds` with a focus on Berlin may result in other global locations being returned. |
||||
|
||||
> /v1/autocomplete?api_key=search-XXXXXXX&text=McDonalds&focus.point.lat=52.5&focus.point.lon=13.3 |
||||
|
||||
```json |
||||
{ |
||||
"type": "Feature", |
||||
"properties": { |
||||
"label": "McDonald County, MO" |
||||
}, |
||||
"geometry": { |
||||
"type": "Point", |
||||
"coordinates": [ |
||||
-94.348365135014, |
||||
36.628682617601 |
||||
] |
||||
} |
||||
}, |
||||
{ |
||||
"type": "Feature", |
||||
"properties": { |
||||
"label": "McDonald's, Berlin, Germany" |
||||
}, |
||||
"geometry": { |
||||
"type": "Point", |
||||
"coordinates": [ |
||||
13.33236, |
||||
52.504232 |
||||
] |
||||
} |
||||
}, |
||||
{ |
||||
"type": "Feature", |
||||
"properties": { |
||||
"label": "McDonald's, Berlin, Germany" |
||||
}, |
||||
"geometry": { |
||||
"type": "Point", |
||||
"coordinates": [ |
||||
13.306792, |
||||
52.500007 |
||||
] |
||||
} |
||||
} |
||||
[...] |
||||
``` |
||||
|
||||
## Available autocomplete parameters |
||||
|
||||
| Parameter | Type | Required | Default | Example | |
||||
| --- | --- | --- | --- | --- | |
||||
| `api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) | |
||||
| `text` | string | yes | none | `Union Square` | |
||||
| `focus.point.lat` | floating point number | no | none | `48.581755` | |
||||
| `focus.point.lon` | floating point number | no | none | `7.745843` | |
||||
|
||||
@ -1,8 +1,26 @@
|
||||
Data Sources |
||||
============= |
||||
# Data sources in Mapzen Search |
||||
|
||||
Mapzen Search is powered by several major open data sets and owes a tremendous debt of gratitude to the individuals and communities which produced them. |
||||
|
||||
# Data Sources |
||||
## OpenStreetMap |
||||
|
||||
# Licensing & Attribution |
||||
[OpenStreetMap](https://www.openstreetmap.org/) is a community-driven, editable map of the world. It prioritizes local knowledge and individual contributions over bulk imports, which often means it has excellent coverage even in remote areas. OpenStreetMap contains information on landmarks, buildings, roads, and much more. |
||||
|
||||
## Quattroshapes |
||||
|
||||
[Quattroshapes](http://quattroshapes.com/) provides global coverage of location data for: |
||||
- countries |
||||
- regions (states/provinces) |
||||
- counties |
||||
- localities (cities, towns, hamlets, villages) |
||||
- neighborhoods (in many places) |
||||
|
||||
Originally assembled by Foursquare, Quattroshapes provides not only the organizational hierarchy for nearly any point or address worldwide (town > local government > province > country), but also the borders for each of these places. Mapzen Search uses data from Quattroshapes to apply a consistent hierarchy to our data from other sources, so you can be sure that points of interest have consistent data about the cities, regions, and countries in which they are located. |
||||
|
||||
## OpenAddresses |
||||
|
||||
[OpenAddresses](http://openaddresses.io/) is a collection of authoritatively sourced data for addresses around the world, with currently over 200 million addresses. OpenAddresses data comes exclusively from regional authorities such as federal, state, or local governments. Because it consists of entirely bulk imports, OpenAddresses is a large, global, and rapidly growing dataset. Many countries, particularly in Europe, now have every address represented in OpenAddresses. |
||||
|
||||
## Geonames |
||||
|
||||
[Geonames](http://www.geonames.org/) is an aggregation of numerous authoritative and non-authoritative datasets. It contains information on everything from country borders to airport names to geographical features. Geonames represents all places as a single point (not shapes encompassing their geography), and carries with it its own distinct hierarchy data that is not uniformly compatible with all data from other sources. Don't worry, as this should be resolved in the near future. |
||||
|
||||
Loading…
Reference in new issue