From 09e4e4882ba59b719e0c1d334f79d3afbe99afb0 Mon Sep 17 00:00:00 2001 From: Riordan Date: Tue, 1 Mar 2016 18:23:51 -0500 Subject: [PATCH 1/9] [work in progress] --- api-keys-rate-limits.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index d2976b0..4b2cf66 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -55,3 +55,16 @@ If you exceed your limits, the service will respond with the status code `429 To ## Security Mapzen Search works over HTTPS, in addition to HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. + +## Content Delivery Network, Edge Caching, and Rate Limit Count +Mapzen Search uses an "edge cache" in order to serve frequently requested content to our users as quickly as possible. This affects the way we calculate hits against your rate limit, as queries that are served out of the edge cache do not count against your limit of Requests per Second or Requests per Day (though they are reflected in your [Developer's Dashboard](https://mapzen.com/developers/)). + +An edge cache (also known as a "Content Delivery Network" or CDN) is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel from us to you so it can get there faster. If you've ever tried to access a common service on the other side of the world and wondered why its so slow, it's because the physical distance the information must travel is that much further. We use a content delivery network to help alleviate this effect and to limit the impact of common queries on our application servers. + +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 its forwarded onto a Mapzen Search application server (you can see a [map of locations](https://www.fastly.com/network-map) from our CDN, [Fastly](https://www.fastly.com) to see where your requests are likely being sent). If it's the first time that CDN server has seen that request in several days (we update our cache at least once every 7 days), the CDN server then passes your API call on to one of our Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, like your API key). If you or another nearby user makes that same API call, you'll likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From our offices in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary. + +What this means is, especially for common queries, like we see on `/autocomplete`, users will get a significant speed boost by sharing [...]. + +Because these cached queries are so much faster and don't increase the impact to our application servers, we do not count them as part of the + +We will do a "soft purge" of our cache at least once every 7 days as well as after every update to the service (//TODO DO WE DO THIS?). From 3ee181767b0a93f25281c46d8f387bd2b5237881 Mon Sep 17 00:00:00 2001 From: Riordan Date: Fri, 4 Mar 2016 14:51:14 -0500 Subject: [PATCH 2/9] first draft of cdn explainer --- api-keys-rate-limits.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 4b2cf66..1c7087b 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -1,8 +1,8 @@ # API keys and rate limits -## Obtain an API key +## Get an API key -To use the Mapzen Search service, you must first obtain a free developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. +To use the Mapzen Search service, you must first get a free developer API key. 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. If you have not done this before, you need to agree to the terms first. @@ -10,7 +10,7 @@ To use the Mapzen Search service, you must first obtain a free developer API key 4. Copy the key into your code. ## Rate limits -Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading the overall system performance. +Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance. Mapzen Search allows you a maximum of: @@ -54,17 +54,25 @@ If you exceed your limits, the service will respond with the status code `429 To ``` ## Security -Mapzen Search works over HTTPS, in addition to HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. +Mapzen Search works over HTTPS and HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. ## Content Delivery Network, Edge Caching, and Rate Limit Count -Mapzen Search uses an "edge cache" in order to serve frequently requested content to our users as quickly as possible. This affects the way we calculate hits against your rate limit, as queries that are served out of the edge cache do not count against your limit of Requests per Second or Requests per Day (though they are reflected in your [Developer's Dashboard](https://mapzen.com/developers/)). +Mapzen Search uses an "edge cache" to serve often requested content to our users as quickly as possible. This affects the way we calculate hits against your rate limit, as queries that are served out of the edge cache do not count against your limit of Requests per Second or Requests per Day (though they are reflected in your [Developer's Dashboard](https://mapzen.com/developers/)). -An edge cache (also known as a "Content Delivery Network" or CDN) is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel from us to you so it can get there faster. If you've ever tried to access a common service on the other side of the world and wondered why its so slow, it's because the physical distance the information must travel is that much further. We use a content delivery network to help alleviate this effect and to limit the impact of common queries on our application servers. +An edge cache (also known as a "Content Delivery Network" or CDN) is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel from us to you so it can get there faster. If you've ever tried to access a common service on the other side of the world and wondered why its so slow, it's because the physical distance the information must travel is that much further. We use a content delivery network to help reduce this effect and to limit the impact of common queries on our application servers. -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 its forwarded onto a Mapzen Search application server (you can see a [map of locations](https://www.fastly.com/network-map) from our CDN, [Fastly](https://www.fastly.com) to see where your requests are likely being sent). If it's the first time that CDN server has seen that request in several days (we update our cache at least once every 7 days), the CDN server then passes your API call on to one of our Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, like your API key). If you or another nearby user makes that same API call, you'll likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From our offices in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary. +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 its forwarded onto a Mapzen Search application server (you can see a [map of locations](https://www.fastly.com/network-map) from our CDN, [Fastly](https://www.fastly.com) to see where your requests are likely being sent). If it's the first time that CDN server has seen that request in several days (we update our cache at least once every 7 days), the CDN server then passes your API call on to one of our Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, like your API key). If you or another nearby user makes that same API call, you'll likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From our offices in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary. And they may vary from location to location, as requests from different places and different internet providers may be served by different edge cache servers. -What this means is, especially for common queries, like we see on `/autocomplete`, users will get a significant speed boost by sharing [...]. +What this means for most users is that for common searches like `/v1/search?text=new york`, there's a good chance your search will come back super-quick, and sometimes, not count against your rate limit. This comes especially in handy with Autocomplete, where many thousands of places all start with the same few root letters (Think `new` as the root of `new york` `newark` `new jersey`). [This would be a great place for a diagram] -Because these cached queries are so much faster and don't increase the impact to our application servers, we do not count them as part of the +Unless you've made a particular API call right before, you won't know ahead of time whether it'll be served from the edge cache. But once you make an API call, you can find out quite a bit in the HTTP headers of the response. HTTP headers are part of every request you make on the web, but aren't the core content itself. It's embedded metadata that tells your browser (or other software interpreting the reqest) how to make sense of it. -We will do a "soft purge" of our cache at least once every 7 days as well as after every update to the service (//TODO DO WE DO THIS?). +There are two sets of headers that will be extremely helpful here: + +The header `X-Cache` will tell you 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 against your rate limit. + +The headers `X-ApiaxleProxy-Qpd-Left` tells you the number of queries left per day and `X-ApiaxleProxy-Qps-Left` tells you the number of queries left per second. Importantly, these headers are only present on `X-Cache: MISS`es. + +In most cases, you should assume the default rate limits of 30,000 per day and 6 queries per seconed apply. But, if you keep track of the number of queries left per day in the `X-ApiaxleProxy-Qpd-Left` header, you can keep track of how many unique queries you can continue to make [this is terrible]. + +While it is safe to make more than 30,000 queries per day with the help of the cache, please keep to your default per-second rate. This ensures the service can run well for everyone [this is terrible too]. From 9278fab3c33f1c54654abbb03172cfe0437d7f05 Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 16:31:25 -0700 Subject: [PATCH 3/9] a few formatting and rewording things --- api-keys-rate-limits.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 1c7087b..8f8fddf 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -56,16 +56,19 @@ If you exceed your limits, the service will respond with the status code `429 To ## Security Mapzen Search works over HTTPS and HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. -## Content Delivery Network, Edge Caching, and Rate Limit Count -Mapzen Search uses an "edge cache" to serve often requested content to our users as quickly as possible. This affects the way we calculate hits against your rate limit, as queries that are served out of the edge cache do not count against your limit of Requests per Second or Requests per Day (though they are reflected in your [Developer's Dashboard](https://mapzen.com/developers/)). +## Caching to improve performance -An edge cache (also known as a "Content Delivery Network" or CDN) is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel from us to you so it can get there faster. If you've ever tried to access a common service on the other side of the world and wondered why its so slow, it's because the physical distance the information must travel is that much further. We use a content delivery network to help reduce this effect and to limit the impact of common queries on our application servers. +Mapzen Search uses caching to serve commonly requested content as quickly as possible. An edge cache, also known as a content delivery network (CDN), is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel to you so it can get there faster. If you have ever tried to access a common service and found that it is slow, it may be because the information must travel a large physical distance. Mapzen Search uses a CDN to help reduce this effect and limit the impact of common queries on its application servers. -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 its forwarded onto a Mapzen Search application server (you can see a [map of locations](https://www.fastly.com/network-map) from our CDN, [Fastly](https://www.fastly.com) to see where your requests are likely being sent). If it's the first time that CDN server has seen that request in several days (we update our cache at least once every 7 days), the CDN server then passes your API call on to one of our Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, like your API key). If you or another nearby user makes that same API call, you'll likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From our offices in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary. And they may vary from location to location, as requests from different places and different internet providers may be served by different edge cache servers. +Queries that are served out of the edge cache do not count against your limit of queries per second or queries per day, although this is not reflected in your [dashboard](https://mapzen.com/developers/). -What this means for most users is that for common searches like `/v1/search?text=new york`, there's a good chance your search will come back super-quick, and sometimes, not count against your rate limit. This comes especially in handy with Autocomplete, where many thousands of places all start with the same few root letters (Think `new` as the root of `new york` `newark` `new jersey`). [This would be a great place for a diagram] +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. -Unless you've made a particular API call right before, you won't know ahead of time whether it'll be served from the edge cache. But once you make an API call, you can find out quite a bit in the HTTP headers of the response. HTTP headers are part of every request you make on the web, but aren't the core content itself. It's embedded metadata that tells your browser (or other software interpreting the reqest) how to make sense of it. +If your request is the first time that CDN server has received that request in several days (the Mapzen Search cache is updated at least once a week), the CDN server then passes your API call to one of the Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, including your API key). If you or another nearby user makes that same API call, you will likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From tests in the Mapzen office in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary, and they may vary from location to location, as requests from different places and different internet providers may be served by different edge cache servers. + +For most users, common searches, such as `/v1/search?text=new york`, often come back quickly, and sometimes, not count toward your rate limit. This is especially useful with Autocomplete, where many places all start with the same few root letters, such as `new` as the start of `new york`, `newark`, and `new jersey`). + +Unless you have made a particular API call right before, you won't know ahead of time whether it'll be served from the edge cache. But once you make an API call, you can find out quite a bit in the HTTP headers of the response. HTTP headers are part of every request you make on the web, but aren't the core content itself. It's embedded metadata that tells your browser (or other software interpreting the reqest) how to make sense of it. There are two sets of headers that will be extremely helpful here: From bee33e27ae9f00f80d6ac8a68962a2e34054327f Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 16:40:00 -0700 Subject: [PATCH 4/9] change formatting, remove a few things --- api-keys-rate-limits.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 8f8fddf..5323d28 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -66,16 +66,9 @@ When you send a request to Mapzen Search, it first goes to the CDN server that i If your request is the first time that CDN server has received that request in several days (the Mapzen Search cache is updated at least once a week), the CDN server then passes your API call to one of the Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, including your API key). If you or another nearby user makes that same API call, you will likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From tests in the Mapzen office in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary, and they may vary from location to location, as requests from different places and different internet providers may be served by different edge cache servers. -For most users, common searches, such as `/v1/search?text=new york`, often come back quickly, and sometimes, not count toward your rate limit. This is especially useful with Autocomplete, where many places all start with the same few root letters, such as `new` as the start of `new york`, `newark`, and `new jersey`). +Common searches, such as `/v1/search?text=new york`, often come back quickly for most users, and sometimes, not count toward your rate limit. This is especially useful with Autocomplete, where many places all start with the same few root letters, such as `new` as the start of `new york`, `newark`, and `new jersey`). -Unless you have made a particular API call right before, you won't know ahead of time whether it'll be served from the edge cache. But once you make an API call, you can find out quite a bit in the HTTP headers of the response. HTTP headers are part of every request you make on the web, but aren't the core content itself. It's embedded metadata that tells your browser (or other software interpreting the reqest) how to make sense of it. +Unless you have made a particular API call right before, you won't know ahead of time whether it will be served from the edge cache. After you make an API call, you can get more information in the HTTP headers of the response. HTTP headers are embedded metadata that tells your browser (or other software) how to make sense of the request. -There are two sets of headers that will be extremely helpful here: - -The header `X-Cache` will tell you 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 against your rate limit. - -The headers `X-ApiaxleProxy-Qpd-Left` tells you the number of queries left per day and `X-ApiaxleProxy-Qps-Left` tells you the number of queries left per second. Importantly, these headers are only present on `X-Cache: MISS`es. - -In most cases, you should assume the default rate limits of 30,000 per day and 6 queries per seconed apply. But, if you keep track of the number of queries left per day in the `X-ApiaxleProxy-Qpd-Left` header, you can keep track of how many unique queries you can continue to make [this is terrible]. - -While it is safe to make more than 30,000 queries per day with the help of the cache, please keep to your default per-second rate. This ensures the service can run well for everyone [this is terrible too]. +* `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 against 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`. From deead42395719d88d8249568f3c252826a82b35f Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 16:45:28 -0700 Subject: [PATCH 5/9] formatting changes to bullets --- api-keys-rate-limits.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 5323d28..75d296a 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -2,7 +2,7 @@ ## Get an API key -To use the Mapzen Search service, you must first get a free developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. +To use the Mapzen Search service, you must first get a developer API key. 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. If you have not done this before, you need to agree to the terms first. @@ -10,7 +10,7 @@ To use the Mapzen Search service, you must first get a free developer API key. S 4. Copy the key into your code. ## Rate limits -Because Mapzen Search is a free, shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance. +Because Mapzen Search is a shared service, there are limitations on the numbers of requests to prevent individual users from degrading system performance. Mapzen Search allows you a maximum of: @@ -64,11 +64,13 @@ Queries that are served out of the edge cache do not count against your limit of 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 the first time that CDN server has received that request in several days (the Mapzen Search cache is updated at least once a week), the CDN server then passes your API call to one of the Mapzen Search application servers. When it comes back with a response to your API call, that nearby CDN server keeps a copy of that response around (minus any personal data to your application, including your API key). If you or another nearby user makes that same API call, you will likely be sent to the same CDN server, which has kept a copy of the response in its local cache. From tests in the Mapzen office in New York, this has the effect of shortening a query to Mapzen Search from 190ms to 21ms. Your speed improvements may vary, and they may vary from location to location, as requests from different places and different internet providers may be served by different edge cache servers. +If your request is the first one like that that CDN server has received in several days (the Mapzen Search cache is updated at least once a week), the CDN server then passes your API call to one of the Mapzen Search application servers. When it comes back with a response to your API call, that nearby 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 office 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. -Common searches, such as `/v1/search?text=new york`, often come back quickly for most users, and sometimes, not count toward your rate limit. This is especially useful with Autocomplete, where many places all start with the same few root letters, such as `new` as the start of `new york`, `newark`, and `new jersey`). +The result is that common searches, such as `/v1/search?text=new york`, often come back quickly for most users, and might not count toward your rate limit. This design is especially useful with Autocomplete, where many places all start with the same few root letters, such as `new` in `new york`, `newark`, and `new jersey`. -Unless you have made a particular API call right before, you won't know ahead of time whether it will be served from the edge cache. After you make an API call, you can get more information in the HTTP headers of the response. HTTP headers are embedded metadata that tells your browser (or other software) how to make sense of the request. +Unless you have recently made a particular API call, you won't know ahead of time whether it will be served from the edge cache. After you make an API call, you can get more information in the HTTP headers of the response. HTTP headers are embedded metadata that tells your browser (or other software) how to make sense of the request. -* `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 against 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`. +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`. From 86e0dffad14a0887f410c9f82df3193db741cf71 Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 16:55:09 -0700 Subject: [PATCH 6/9] trimming --- api-keys-rate-limits.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 75d296a..5932d47 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -20,7 +20,7 @@ Mapzen Search allows you a maximum of: If you need more capacity, contact [search@mapzen.com](mailto:search@mapzen.com). You can also set up your own instance of [Pelias](https://github.com/pelias/pelias), which has access to the same data used in Mapzen Search. ## Failing to provide an `api_key` -If you fail to supply the `api_key` parameter, the service will respond with the status code `403 Forbidden`: +If you fail to include the `api_key` parameter, the service will respond with the status code, `403 Forbidden`: ```bash { "meta": { @@ -36,7 +36,7 @@ If you fail to supply the `api_key` parameter, the service will respond with the } ``` -## Exceeding your limits +## Exceeding limits If you exceed your limits, the service will respond with the status code `429 Too Many Requests`: ```bash { @@ -60,15 +60,15 @@ Mapzen Search works over HTTPS and HTTP. You are strongly encouraged to use HTTP Mapzen Search uses caching to serve commonly requested content as quickly as possible. An edge cache, also known as a content delivery network (CDN), is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel to you so it can get there faster. If you have ever tried to access a common service and found that it is slow, it may be because the information must travel a large physical distance. Mapzen Search uses a CDN to help reduce this effect and limit the impact of common queries on its application servers. -Queries that are served out of the edge cache do not count against your limit of queries per second or queries per day, although this is not reflected in your [dashboard](https://mapzen.com/developers/). +Queries that are served from the edge cache do not count toward your limit of queries per second or queries per day, although this is not reflected 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. -If your request is the first one like that that CDN server has received in several days (the Mapzen Search cache is updated at least once a week), the CDN server then passes your API call to one of the Mapzen Search application servers. When it comes back with a response to your API call, that nearby 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 office 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. +If your request is not found in the current CDN cache, the CDN server then passes your 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. The Mapzen Search cache is updated at least once a week. 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 result is that common searches, such as `/v1/search?text=new york`, often come back quickly for most users, and might not count toward your rate limit. This design is especially useful with Autocomplete, where many places all start with the same few root letters, such as `new` in `new york`, `newark`, and `new jersey`. +Through edge caching, common searches, such as `/v1/search?text=new york`, often come back quickly for most users, and may not count toward your rate limit. This is especially useful with Autocomplete, where many places start with the same few root letters, such as the `new` in `new york`, `newark`, and `new jersey`. -Unless you have recently made a particular API call, you won't know ahead of time whether it will be served from the edge cache. After you make an API call, you can get more information in the HTTP headers of the response. HTTP headers are embedded metadata that tells your browser (or other software) how to make sense of the request. +Unless you have recently made a particular API call, you will not know ahead of time whether it will be served from the edge cache. After you make an API call, you can get more information in the HTTP headers of the response. HTTP headers are embedded metadata that tells your browser (or other software) how to make sense of the request. These header entries are most helpful to determine whether caching was used: From 54d1e5105c27155cd9dce3e170e1ce60e9528d11 Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 16:57:57 -0700 Subject: [PATCH 7/9] change sentence --- api-keys-rate-limits.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 5932d47..c35b454 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -60,11 +60,11 @@ Mapzen Search works over HTTPS and HTTP. You are strongly encouraged to use HTTP Mapzen Search uses caching to serve commonly requested content as quickly as possible. An edge cache, also known as a content delivery network (CDN), is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel to you so it can get there faster. If you have ever tried to access a common service and found that it is slow, it may be because the information must travel a large physical distance. Mapzen Search uses a CDN to help reduce this effect and limit the impact of common queries on its application servers. -Queries that are served from the edge cache do not count toward your limit of queries per second or queries per day, although this is not reflected in your [dashboard](https://mapzen.com/developers/). +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. -If your request is not found in the current CDN cache, the CDN server then passes your 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. The Mapzen Search cache is updated at least once a week. 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. +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. Through edge caching, common searches, such as `/v1/search?text=new york`, often come back quickly for most users, and may not count toward your rate limit. This is especially useful with Autocomplete, where many places start with the same few root letters, such as the `new` in `new york`, `newark`, and `new jersey`. From 839ca9d695446acc55cae196509d853eef27caf3 Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 17:05:07 -0700 Subject: [PATCH 8/9] pull in from master --- api-keys-rate-limits.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index c35b454..8fdf306 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -20,7 +20,7 @@ Mapzen Search allows you a maximum of: If you need more capacity, contact [search@mapzen.com](mailto:search@mapzen.com). You can also set up your own instance of [Pelias](https://github.com/pelias/pelias), which has access to the same data used in Mapzen Search. ## Failing to provide an `api_key` -If you fail to include the `api_key` parameter, the service will respond with the status code, `403 Forbidden`: +If you fail to supply the `api_key` parameter, the service will respond with the status code `403 Forbidden`: ```bash { "meta": { @@ -36,7 +36,7 @@ If you fail to include the `api_key` parameter, the service will respond with th } ``` -## Exceeding limits +## Exceeding your limits If you exceed your limits, the service will respond with the status code `429 Too Many Requests`: ```bash { From 45c0bd604844f01521fc360330ec9f7ba168b68a Mon Sep 17 00:00:00 2001 From: Rhonda Glennon Date: Fri, 29 Apr 2016 17:15:53 -0700 Subject: [PATCH 9/9] remove pushed head symbols --- api-keys-rate-limits.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index bff72ff..8fdf306 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -55,7 +55,6 @@ If you exceed your limits, the service will respond with the status code `429 To ## Security Mapzen Search works over HTTPS and HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query. -<<<<<<< HEAD ## Caching to improve performance @@ -75,5 +74,3 @@ 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`. -======= ->>>>>>> master