Browse Source

Merge pull request #143 from pelias/unified-keys

add unified keys
pull/147/head
Rhonda Glennon 8 years ago committed by GitHub
parent
commit
dfd47ff983
  1. 12
      add-search-to-a-map.md
  2. 6
      api-keys-rate-limits.md
  3. 10
      autocomplete.md
  4. 4
      place.md
  5. 4
      response.md
  6. 20
      reverse.md
  7. 30
      search.md
  8. 10
      transition-from-beta.md
  9. 4
      use-cors.md

12
add-search-to-a-map.md

@ -8,11 +8,11 @@ In this walkthrough, you will learn how to make a map with a search box that all
## Sign up for a Mapzen Search API key
To use the geocoding service, you must first get a Mapzen Search [API key](https://en.wikipedia.org/wiki/Application_programming_interface_key). Because the search service is shared among many users, an API key is a way to make sure that the performance is acceptable for everyone. Sign in at https://mapzen.com/developers to create and manage your API keys.
To use the geocoding service, you must first get a Mapzen [API key](https://en.wikipedia.org/wiki/Application_programming_interface_key). Because the search service is shared among many users, an API key is a way to make sure that the performance is acceptable for everyone. Sign in at https://mapzen.com/developers to create and manage your API keys.
1. Go to https://mapzen.com/developers.
2. Sign in with your [GitHub account](https://help.github.com/articles/signing-up-for-a-new-github-account/). If you have not done this before, you need to agree to the terms first.
3. Create a new key for Search, and optionally, give it a project name so you can remember the purpose of the key.
3. Create a new key for this project and, optionally, give it a project name so you can remember the purpose of the key.
4. Keep the web page open so you can copy the key into the source code later.
## Create an index page
@ -189,13 +189,13 @@ At this point, you have a map! You should see a map with OpenStreetMap tiles, zo
So far, you have referenced the necessary files, initialized Leaflet with a map container on the page, and added data to the map. Now, you are ready to add the Search box from the Mapzen Search plug-in.
1. Go back to the https://mapzen.com/developers page and copy your API key to the clipboard.
2. Inside the same `<script>` tag, start a new line after the `}).addTo(map);` line. Initialize a search box with the following code and your own API key substituted for the placeholder text of `search-xxxxxx`.
2. Inside the same `<script>` tag, start a new line after the `}).addTo(map);` line. Initialize a search box with the following code and your own API key substituted for the placeholder text of `mapzen-xxxxxx`.
```js
var geocoder = L.control.geocoder('search-xxxxxx').addTo(map);
var geocoder = L.control.geocoder('mapzen-xxxxxx').addTo(map);
```
The `search-xxxxxx` text is the Mapzen Search API key; paste your own API key inside the single quotes.
The `mapzen-xxxxxx` text is the Mapzen Search API key; paste your own API key inside the single quotes.
3. Save your edits and refresh the browser. You should see a small magnifying glass icon in the left corner, near the zoom controls.
@ -273,7 +273,7 @@ You can refer to this HTML if you want to review your work or troubleshoot an er
}).addTo(map);
//Use your own API key in place of this one. Get a key at mapzen.com/developers.
var geocoder = L.control.geocoder('search-xxxxxx').addTo(map);
var geocoder = L.control.geocoder('mapzen-xxxxxx').addTo(map);
</script>
</body>
</html>

6
api-keys-rate-limits.md

@ -6,7 +6,7 @@ To use the Mapzen Search service, you must first get a developer API key. Sign i
1. Go to https://mapzen.com/developers.
2. Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first.
3. Create a new key for Mapzen Search, and optionally, give it a name so you can remember the purpose of the project.
3. Create a new key and optionally, give it a name so you can remember the purpose of the project.
4. Copy the key into your code.
## Rate limits
@ -62,7 +62,7 @@ Mapzen Search uses caching to serve commonly requested content as quickly as pos
Queries that are served from the edge cache do not count toward your limit of queries per second or queries per day, although you will still see them listed in your [dashboard](https://mapzen.com/developers/).
When you send a request to Mapzen Search, it first goes to the CDN server that is the closest path from your internet service provider before it is forwarded onto a Mapzen Search application server. Mapzen Search uses [Fastly](https://www.fastly.com) for its CDN; you can look at this [network map](https://www.fastly.com/network-map) to see where your requests are likely being sent.
When you send a request to Mapzen Search, it first goes to the CDN server that is the closest path from your internet service provider before it is forwarded onto a Mapzen Search application server. Mapzen Search uses [Fastly](https://www.fastly.com) for its CDN; you can look at this [network map](https://www.fastly.com/network-map) to see where your requests are likely being sent.
If your request is not found in the current CDN cache, the CDN server then passes it to one of the Mapzen Search application servers. When it comes back with a response to your API call, the CDN server keeps a copy of that response (minus any personal data to your application, including your API key). If you or another nearby user makes the identical API call, you will likely be sent to the same CDN server, which has the response in its local cache. From tests in the Mapzen offices in New York, this has the effect of shortening a query from 190ms to 21ms. Your speed improvements may vary, as requests from other locations and internet providers may be served by different edge cache servers. The Mapzen Search cache is updated on the CDN at least once a week.
@ -73,4 +73,4 @@ Unless you have recently made a particular API call, you will not know ahead of
These header entries are most helpful to determine whether caching was used:
- `X-Cache` indicates if your request was served from the Mapzen Search application server (`MISS`) or the cache server (`HIT`). This header should be there for any query you make to the Mapzen Search API. Any query with `X-Cache: MISS` is a query that counts toward your rate limit.
- `X-ApiaxleProxy-Qps-Left` is the number of queries per second remaining on your API key, and `X-ApiaxleProxy-Qpd-Left` is the remaining queries per day. These headers are only present when you see `X-Cache: MISS`.
- `X-ApiaxleProxy-Qps-Left` is the number of queries per second remaining on your API key, and `X-ApiaxleProxy-Qpd-Left` is the remaining queries per day. These headers are only present when you see `X-Cache: MISS`.

10
autocomplete.md

@ -19,7 +19,7 @@ To focus your search based upon a geographical area, such as the center of the u
From San Francisco:
>
[/v1/autocomplete?api_key=search-TeXrSTX&__focus.point.lat=37.7&focus.point.lon=-122.4&text=union square__](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&focus.point.lat=37.7&focus.point.lon=-122.4&text=union square)
[/v1/autocomplete?api_key=mapzen-xxxxxx&__focus.point.lat=37.7&focus.point.lon=-122.4&text=union square__](https://search.mapzen.com/v1/autocomplete?focus.point.lat=37.7&focus.point.lon=-122.4&text=union square)
```
1) Union Square, San Francisco County, CA
@ -29,7 +29,7 @@ From San Francisco:
From New York City:
>
[/v1/autocomplete?api_key=search-TeXrSTX&__focus.point.lat=40.7&focus.point.lon=-73.9&text=union square__](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&focus.point.lat=40.7&focus.point.lon=-73.9&text=union square)
[/v1/autocomplete?api_key=mapzen-xxxxxx&__focus.point.lat=40.7&focus.point.lon=-73.9&text=union square__](https://search.mapzen.com/v1/autocomplete?focus.point.lat=40.7&focus.point.lon=-73.9&text=union square)
```
1) Union Square, New York County, NY
@ -38,7 +38,7 @@ From New York City:
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 `hard rock cafe` with a focus on Berlin:
> [/v1/autocomplete?api_key=search-TeXrSTX&__focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe__](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe)
> [/v1/autocomplete?api_key=mapzen-xxxxxx&__focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe__](https://search.mapzen.com/v1/autocomplete?focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe)
with `focus.point` you will find the Berlin restaurant first:
```
@ -65,7 +65,7 @@ The `sources` parameter allows you to specify from which data sources you'd like
* `geonames` or `gn`
* `whosonfirst` or `wof`
> [/v1/autocomplete?api_key=search-TeXrSTX&__sources=openaddresses__&text=pennsylvania](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&sources=openaddresses&text=pennsylvania)
> [/v1/autocomplete?api_key=mapzen-xxxxxx&__sources=openaddresses__&text=pennsylvania](https://search.mapzen.com/v1/autocomplete?sources=openaddresses&text=pennsylvania)
with `sources=openaddresses` you will only find addresses on Pennsylvania Ave or Street:
```
@ -100,7 +100,7 @@ The type of record is referred to as its `layer`. All records are indexed into t
|`neighbourhood`|social communities, neighbourhoods|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
> [/v1/autocomplete?api_key=search-TeXrSTX&__layers=coarse__&text=starbuck](https://search.mapzen.com/v1/autocomplete?api_key=search-TeXrSTX&layers=coarse&text=starbuck)
> [/v1/autocomplete?api_key=mapzen-xxxxxx&__layers=coarse__&text=starbuck](https://search.mapzen.com/v1/autocomplete?layers=coarse&text=starbuck)
with `layers=coarse` you will see only administrative areas with names containing Starbuck

4
place.md

@ -9,13 +9,13 @@ These `gid` strings should not be built manually, but rather used directly as-is
For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM):
> [/v1/place?api_key=search-TeXrSTX&__ids=openstreetmap:venue:way:5013364__](https://search.mapzen.com/v1/place?api_key=search-TeXrSTX&ids=openstreetmap:venue:way:5013364)
> [/v1/place?api_key=mapzen-xxxxxx&__ids=openstreetmap:venue:way:5013364__](https://search.mapzen.com/v1/place?ids=openstreetmap:venue:way:5013364)
## Search for multiple places in a query
To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap and the borough of Manhattan in Who's on First:
> [/v1/place?api_key=search-TeXrSTX&__ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771__](https://search.mapzen.com/v1/place?api_key=search-TeXrSTX&ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771)
> [/v1/place?api_key=mapzen-xxxxxx&__ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771__](https://search.mapzen.com/v1/place?ids=openstreetmap:venue:way:5013364,whosonfirst:borough:421205771)
The results are returned in the order requested.

4
response.md

@ -99,8 +99,8 @@ By default, Mapzen Search results 10 places, unless otherwise specified. If you
| `text` | YMCA |
| `size` | 1 |
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=1)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?text=YMCA&size=1)
If you want 25 results, you can build the query where `size` is 25.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=25)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?text=YMCA&size=25)

20
reverse.md

@ -14,7 +14,7 @@ With reverse geocoding with Mapzen Search, you can look up all sorts of informat
To get started with reverse geocoding, you need a [developer API key](https://mapzen.com/developers) and a latitude, longitude pair in decimal degrees specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France, is located at `48.858268,2.294471`. The reverse geocode query for this would be:
>[/v1/reverse?api_key=search-TeXrSTX&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471)
>[/v1/reverse?api_key=mapzen-xxxxxx&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?point.lat=48.858268&point.lon=2.294471)
Notice that the first result is the Eiffel Tower (well, _Tour Eiffel_). The output is the standard GeoJSON format.
@ -36,7 +36,7 @@ Parameter | Type | Required | Default | Example
A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the earlier request that returned the Eiffel Tower (or 'Tour Eiffel', to be exact), notice that other results were returned including "Bureau de Gustave Eiffel" (a museum) and "Le Jules Verne" (a restaurant). To limit a reverse geocode to only the first result, pass the `size` parameter:
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&size=1)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?point.lat=48.858268&point.lon=2.294471&size=1)
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.
@ -51,7 +51,7 @@ By default, reverse geocoding returns results from any [data source](data-source
| [Who's on First](https://whosonfirst.mapzen.com) | `whosonfirst` | `wof` |
| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&sources=osm)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?point.lat=48.858268&point.lon=2.294471&sources=osm)
### Filter by layers (data type)
@ -74,13 +74,13 @@ Without specifying further, reverse geocoding doesn't restrict results to a part
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=48.858268&point.lon=2.294471&layers=locality)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?point.lat=48.858268&point.lon=2.294471&layers=locality)
### Filter by country
If you are performing a reverse geocode near a country boundary, and are only interested in results from one country and not the other, you can specify a country code. You can set the `boundary.country` parameter value to the alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). For example, the latitude,longitude pair `47.270521,9.530846` is on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country`, the first 10 results returned may come from all three countries. By including `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action:
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=47.270521&point.lon=9.530846&boundary.country=LIE)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?point.lat=47.270521&point.lon=9.530846&boundary.country=LIE)
Note that `UK` is not a valid ISO 3166-1 alpha-2 country code.
@ -102,16 +102,16 @@ Distance from `point.lat`/`point.lon` | Confidence score
This section shows how the various parameters can be combined to form complex use cases.
* All results near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493)
* Only OpenStreetMap results near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&sources=osm)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&sources=osm)
* Only street addresses near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address)
* Only OpenStreetMap street addresses near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm)
* Only the first OpenStreetMap address near the Tower of London
>[/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?api_key=search-TeXrSTX&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)
>[/v1/reverse?api_key=mapzen-xxxxxx&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)

30
search.md

@ -9,7 +9,7 @@ Making the leap from text to coordinates is an intricate and challenging process
All Mapzen Search requests share the same format:
```
https://search.mapzen.com/v1/search?text=London&api_key=search-xxxxxx
https://search.mapzen.com/v1/search?text=London&api_key=mapzen-xxxxxx
\___/ \_______________/\__/\_____/\__________/\___________________/
| | / | | |
scheme domain version path query authentication token
@ -23,7 +23,7 @@ In the simplest search, you can provide only one parameter, the text you want to
For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`.
> [/v1/search?api_key=search-TeXrSTX&___text=YMCA___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA)
> [/v1/search?api_key=mapzen-xxxxxx&___text=YMCA___](https://search.mapzen.com/v1/search?text=YMCA)
Note the parameter values are set as follows:
@ -51,7 +51,7 @@ In the example above, you will find the name of each matched locations in a prop
Spelling matters, but not capitalization when performing a query with Mapzen Search. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the earlier search to the following:
> [/v1/search?api_key=search-TeXrSTX&___text=yMcA___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=yMcA)
> [/v1/search?api_key=mapzen-xxxxxx&___text=yMcA___](https://search.mapzen.com/v1/search?text=yMcA)
Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search.
@ -65,11 +65,11 @@ By default, Mapzen Search results 10 places, unless otherwise specified. If you
| `text` | YMCA |
| `size` | 1 |
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=1)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=1___](https://search.mapzen.com/v1/search?text=YMCA&size=1)
If you want 25 results, you can build the query where `size` is 25.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&size=25)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___size=25___](https://search.mapzen.com/v1/search?text=YMCA&size=25)
## Narrow your search
@ -83,7 +83,7 @@ Sometimes your work might require that all the search results be from a particul
Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is GBR and set the parameters like this:
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___boundary.country=GBR___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&boundary.country=GBR)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___boundary.country=GBR___](https://search.mapzen.com/v1/search?text=YMCA&boundary.country=GBR)
| parameter | value |
| :--- | :--- |
@ -106,7 +106,7 @@ Note that all the results are within Great Britain:
If you try the same search request with different country codes, the results change to show YMCA locations within this region.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___boundary.country=USA___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&boundary.country=USA)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___boundary.country=USA___](https://search.mapzen.com/v1/search?text=YMCA&boundary.country=USA)
Results in the United States:
@ -131,7 +131,7 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/).
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://search.mapzen.com/v1/search?text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51)
| parameter | value |
| :--- | :--- |
@ -161,7 +161,7 @@ Sometimes you don't have a rectangle to work with, but rather you have a point o
In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` is your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://search.mapzen.com/v1/search?api_key=mapzen-xxxxxx&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
| parameter | value |
| :--- | :--- |
@ -197,7 +197,7 @@ By specifying a `focus.point`, nearby places will be scored higher depending on
To find YMCA again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use `focus.point`.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value |
| :--- | :--- |
@ -226,7 +226,7 @@ Now that you have seen how to use boundary and focus to narrow and sort your res
Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. You can combine that same focus point in Sydney with the country boundary of Australia like this.
> [/v1/search?api_key={YOUR-KEY}&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value |
| :--- | :--- |
@ -253,7 +253,7 @@ The results below look different from the ones you saw before with only a focus
If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&___boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&___boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50___](https://search.mapzen.com/v1/search?text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50)
| parameter | value |
| :--- | :--- |
@ -295,7 +295,7 @@ The search examples so far have returned a mix of results from all the data sour
If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___sources=oa___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&sources=oa)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___sources=oa___](https://search.mapzen.com/v1/search?text=YMCA&sources=oa)
| parameter | value |
| :--- | :--- |
@ -318,7 +318,7 @@ Because OpenAddresses is, as the name suggests, only address data, here's what y
If you wanted to combine several data sources together, set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results; they are still sorted based on the linguistic match quality to `text` and distance from `focus`, if you specified one.
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___sources=osm,gn___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&sources=oa)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___sources=osm,gn___](https://search.mapzen.com/v1/search?text=YMCA&sources=oa)
| parameter | value |
| :--- | :--- |
@ -347,7 +347,7 @@ In Mapzen Search, place types are referred to as `layers`, ranging from fine to
|`neighbourhood`|social communities, neighbourhoods|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
> [/v1/search?api_key=search-TeXrSTX&text=YMCA&___layers=venue,address___](https://search.mapzen.com/v1/search?api_key=search-TeXrSTX&text=YMCA&layers=venue,address)
> [/v1/search?api_key=mapzen-xxxxxx&text=YMCA&___layers=venue,address___](https://search.mapzen.com/v1/search?text=YMCA&layers=venue,address)
| parameter | value |
| :--- | :--- |

10
transition-from-beta.md

@ -16,7 +16,7 @@ Mapzen Search API keys allow you:
* 6 requests per second
* 30,000 requests per day
To start using an API key, append `&api_key=search-xxxxxx` to all API calls to all endpoints (aside from `/attribution`, which requires no key).
To start using an API key, append `&api_key=mapzen-xxxxxx` to all API calls to all endpoints (aside from `/attribution`, which requires no key).
Your API usage limits are displayed in the HTTP headers of any API call, such as in this example:
@ -126,7 +126,7 @@ A former query for a coarse geocode may have been:
`https://pelias.mapzen.com/search/coarse?input=<search-text>`
That same query would now be written as:
`https://search.mapzen.com/v1/search?text=<search-text>&layers=coarse&api_key=<search-xxxxxx>`
`https://search.mapzen.com/v1/search?text=<search-text>&layers=coarse&api_key=<mapzen-xxxxxx>`
You can also call the coarse layers directly, namely, `country`, `region`, `county`, `locality`, `neighbourhood`, to restrict the kinds of results you'll get back.
@ -154,7 +154,7 @@ The `/autocomplete` endpoint serves as a renamed `/suggest` to show that these a
Reverse geocoding finds the places closest to geospatial coordinates.
```
https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key=search-xxxxxx
https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key=mapzen-xxxxxx
```
Used to be (Beta) | New parameter (V1) | New behavior (if any) |
@ -169,7 +169,7 @@ New parameters:
### Reverse coarse geocoding
Reverse coarse geocoding is not a point-in-polygon lookup (finding the hierarchy for the polygon that the point falls in), but instead looks for the hierarchy of points nearby. To use reverse coarse geocoding, use:
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key=search-xxxxxx
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key=mapzen-xxxxxx
```
## `/place` (formerly `/doc`)
@ -177,7 +177,7 @@ Reverse coarse geocoding is not a point-in-polygon lookup (finding the hierarchy
If a search returns `id: "geonames:3544:adm1:fr:fra:paris"` as the matching ID for a record, the complete underlying place record can be returned with:
```
https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=search-xxxxxx
https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=mapzen-xxxxxx
```
## Security

4
use-cors.md

@ -27,7 +27,7 @@ $.ajax({
dataType: "json",
data: {
"text": "London, UK",
"api_key": "search-EEgHGcM"
"api_key": "mapzen-xxxxxx"
},
success: function( data, status, jqxhr ){
console.log( "Request received:", data );
@ -49,7 +49,7 @@ $http({
headers: { "Accept": "application/json" },
params: {
"text": "London, UK",
"api_key": "search-EEgHGcM"
"api_key": "mapzen-xxxxxx"
},
})
.success(function( data, status ) {

Loading…
Cancel
Save