@ -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:
Rhonda Glennon
9 years ago