nobody is looking at this yet so may as well experiment

getting-started/00-getting-started.md

@@ -0,0 +1,12 @@
+Getting Started with Mapzen Search
+===================================
+
+Mapzen Search is a modern geocoding and place search service based on [Pelias](https://github.com/pelias/pelias), an experimental open geocoder from [Mapzen](https://mapzen.com) and powered by open data. It's used to transform the way people talk about places - with names and addresses - into geographic coordinates.
+
+[REWRITE]
+Mapzen Search can be used to:
+- geocode addresses, points of interest, neighborhoods, cities, and regions
+- power real-time search autocomplete for places
+- turn a list of addresses into coordinates to plot
+- Take location coordinates and turn them into human readable places, like an address
+- find the neighborhoods, cities, states, and countries of location coordinates to quickly classify where your data is coming from

getting-started/002-search.md

@@ -0,0 +1,73 @@
+Search
+=======
+Turning place names we can say into geographic coordinates computers can use
+_____________________________________________________________________________________
+
+Geocoding is the process of matching an address to its corresponding geographic coordinates. There's nothing inherent in the words "10 Downing Street, London, United Kingdom" that inherently conveys its location at the coordinates 51.503396, -0.12764. Instead this process [...].
+
+
+# Using Search
+## Looking For Places - Getting Started
+{search text, global, no options}
+
+`https://search.mapzen.com/v1/search?text={123 Fake Street, Springfield}&api_key={YOUR_API_KEY}`
+
+- Response is GeoJSON FeatureCollection
+ - The FeatureCollection is an ordered array, ranked in order of likleyhood
+ - Use directly in your application or test at GeoJSON.io
+
+## Sizing Your Results
+ - Example: size=1 for batch geocoding
+ - Example: size=40 to store lots of results
+
+## Looking in a Particular Place (Using Boundaries)
+[Means to limit the scope of where you're looking, and to look only within a particular area. This can be useful if you're looking for places in a particular region, or country, or only want to look in the immediate viscinity of a user with a known location.]
+
+Boundaries are mutually exclusive
+
+- Country (country code)
+- Rectangle (bbox)
+- Circle (point, radius)
+
+All results outside of the area will be discarded.
+
+## Focusing Results Near Your End-Users
+Mapzen Search can let your users search globally, while providing them with search results for the closest matching places first. All you have to do is provide Mapzen Search with some location context about where the search should be focused.
+
+In many cases, you may have the location of the user's device (either through Device Location APIs or the HTML5 Location API) or the area of a map that the user is looking at (the map viewport).
+
+- focus viewport api example (e.g. union square)
+- focus point api example (NY union square)
+
+
+### Combining Focused Results with Boundaries
+- Focus within country example
+
+- Focus within large bounding box example (e.g. maximum distance a user is willing to travel)
+
+
+## Selecting Datasets
+
+Mapzen search offers two types of options for selecting the dataset you want back:
+1. the originating source of the data (`sources`)
+2. the kind of place you're looking to geocode against (`layers`)
+
+### Selecting `Sources`
+{list sources, not different licenses}
+{combine source listing, e.g. open addresses + Geonames}
+
+### Selecting Layers
+
+### Coarse Geocoding (Neighborhoods, Cities, States, Countries)
+There are many cases where you're after not a point, but a general area, whether it's the name of a town, a neighborhood, a county, or a country.
+
+
+
+
+
+
+
+
+
+
+# Using Autocomplete & Search Together

getting-started/api.md

@@ -0,0 +1,23 @@
+API Keys
+=========
+
+# Obtaining an API Key
+
+To use the Mapzen Search service, you must first obtain a free developer API key from Mapzen. Sign in at https://mapzen.com/developers to create and manage your API keys.
+
+Mapzen Search is a free, shared geocoding service. As such, there are limitations on requests to prevent individual users from degrading the overall system performance.
+
+Go to https://mapzen.com/developers.
+Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first.
+Create a new key for Mapzen Search, and optionally, give it a name so you can remember the purpose of the project.
+Keep the web page open so you can copy the key into the code later.
+
+
+# Rate Limits
+As Mapzen Search is a free, shared service, we have rate limits that restrict the maximum number of requests per second and per day.
+
+Our free API keys allow you a maximum of:
+- 3 requests per second
+- 30,000 requests per day
+
+If you need more capacity, you can get in touch with [search@mapzen.com](mailto:search@mapzen.com), or set up your own instance of [Pelias](https://github.com/pelias/pelias), which we provide with access to all of the same data we use to power Mapzen Search.

getting-started/data.md

@@ -0,0 +1,8 @@
+Data
+====
+
+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
+
+# Licensing & Attribution

index.md

@@ -0,0 +1,10 @@
+Mapzen Search Documentation V1
+===========================
+Geocoding service powered by [Pelias](https://github.com/pelias/pelias) and open data
+_____________________________________________________________________________________
+
+These pages offer an introduction to the API and terminology used in Mapzen Search and the accompanying experimental open source geocoder, Pelias which powers it.
+
+- Getting Started
+- API Specification
+- Transitioning From Beta to 1.0

swagger-docs/overview.md

@@ -0,0 +1,24 @@
+# Mapzen Search API
+
+## Overview
+Searching the world with the Mapzen Search API, powered by [Pelias](https://github.com/pelias/pelias).
+----------
+
+Pelias is an experimental, open geocoder from [Mapzen](https://mapzen.com). It's built from the ground up as an open source and open data-friendly geocoder that's designed to operate on top of any new
+
+This documentation refers specifically to Mapzen Search (//TODO: do we want to call this Mapzen Place Search?), powered by Pelias, but is mirrored in the API of the [Pelias code](https://github.com/pelias/pelias).
+
+
+### Version information
+Version: 1.0.0
+
+### URI scheme
+Host: pelias.mapzen.com
+BasePath: /v1
+Schemes: HTTP, HTTPS
+
+### Produces
+
+* application/vnd.geo+json
+
+

swagger-docs/paths.md

@@ -0,0 +1,122 @@
+## Paths
+### Fast response endpoint to provide an end-user suggestions of matching places as they're typing the search string. Returns 10 matching places. Intended for use while the user is typing a response. For searching a complete query (if autocomplete doesn't deliver a match), use the /search endpoint.
+```
+GET /autocomplete
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|text|User's search string|true|string (string)||
+|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point (like the center of their view). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)||
+|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)||
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|A GeoJSON FeatureCollection array of geocoded places.|No Content|
+|400|Invalid request. Check that you are passing along valid parameters without conflicting options.|No Content|
+
+
+#### Tags
+
+* search
+* forward geocoding
+
+### Retrieves the full GeoJSON record for a given place. ID determined from the results of a `/search`, `/autocomplete`, or `/reverse` response.
+```
+GET /place
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|ids|Place ID from Mapzen Search.|false|string (string)||
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|ok|No Content|
+
+
+### Takes the coordinates of a location and searches for the name or address of the place it's from.
+```
+GET /reverse
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|point.lon||true| (float)||
+|QueryParameter|point.lat||true| (float)||
+|QueryParameter|boundary.circle.lon||false|number (float)||
+|QueryParameter|boundary.circle.lat||false|number (float)||
+|QueryParameter|boundary.circle.radius|bounding circle radius (in KM).|false|number (float)||
+|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.|false|string (string)||
+|QueryParameter|layer||false|||
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|All Good.|No Content|
+
+
+### Geocodes a user's search query
+```
+GET /search
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|text|User's search string|true|string (string)||
+|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)||
+|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)||
+|QueryParameter|focus.viewport.min_lon|`focus.viewport` provides focus to user's viewable map area, using the viewable screen to calibrate results relevant for an end-user's area of interest based on what's on screen, where that is located, and the level of zoom.
+
+This parameter limits the user's viewport latitude (furthest bottom coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+
+Accepts only WGS84 longitudes.
+|false|number (float)||
+|QueryParameter|focus.viewport.min_lat|This parameter limits the user's viewport longitude (furthest left coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+Accepts only WGS84 latitudes.
+|false|number (float)||
+|QueryParameter|focus.viewport.max_lon|This parameter limits the user's viewport latitude (furthest right coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+
+Accepts only WGS84 longitudes.
+|false|number (float)||
+|QueryParameter|focus.viewport.max_lat|This parameter limits the user's viewport longitude (furthest top coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+Accepts only WGS84 latitudes.
+|false|number (float)||
+|QueryParameter|layers|For more than one layer, accepts a comma separated list of valid layers. If any of those layers is invalid, the request will still be honored, but a warning will be thrown in the `geocoding` block of the response.
+|false|string (string)||
+|QueryParameter|sources|tk|false|string||
+|QueryParameter|boundary.circle.lon|tk|false|number (float)||
+|QueryParameter|boundary.circle.lat|tk|false|number (float)||
+|QueryParameter|boundary.circle.radius|Maximum distance in meters from the centroid to search from. Forms the radius of a bounding circle.|false|number (float)||
+|QueryParameter|boundary.rect.min_lon||false|number (float)||
+|QueryParameter|boundary.rect.min_lat||false|number (float)||
+|QueryParameter|boundary.rect.max_lon||false|number (float)||
+|QueryParameter|boundary.rect.max_lat||false|number (float)||
+|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.
+|false|string (string)||
+|QueryParameter|size|Maximum number of possible matching places to be returned|false|integer (int32)|10|
+|QueryParameter|private|Option to disable query logging in Mapzen Search. Defaults to False.|false|boolean|false|
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|a GeoJSON FeatureCollection array of geocoded places|No Content|
+|400|invalid request. Check that you are passing along valid parameters|No Content|
+|403|invalid API key. Register for a valid API key at the [Mapzen Developer Portal](https://mapzen.com/developer).|No Content|
+
+
+#### Tags
+
+* forward geocoding
+* search
+