Special HTTP Response Headers¶

Custom Response Headers¶

Whenever GeoWebCache serves a tile request, it will write the following custom headers on the HTTP response:

• geowebcache-cache-result : one of HIT, MISS, WMS, OTHER. HIT means that the tile requested was found on the cache, MISS that the tile wasn’t found on the cache but was acquired from the layer’s data source, WMS indicates the request was proxied to the origin WMS verbatim (for example, for GetFeatureInfo requests), and OTHER is used when the response was the default white/transparent tile or an error occurred.

• geowebcache-tile-index : contains the three-dimensional tile index in x,y,z order of the returned tile image in the corresponding grid space (e.g. [1, 0, 0]).

• geowebcache-tile-bounds : the bounds of the returned tile in the corresponding coordinate reference system (e.g. -180,-90,0,90).

• geowebcache-gridset : the name of the gridset the tile belongs to (e.g. EPSG:900913, GoogleCRS84Scale, etc).

• geowebcache-crs : the code of the coordinate reference system of the matching gridset (e.g. EPSG:900913, EPSG:4326, etc).

This is a sample request/response using cURL:

curl -v "http://localhost:8080/geowebcache/service/wms?LAYERS=sde%3Abmworld&FORMAT=image%2Fpng&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&SRS=EPSG%3A4326&BBOX=-180,-38,-52,90&WIDTH=256&HEIGHT=256&tiled=true">/dev/null

< HTTP/1.1 200 OK
< geowebcache-tile-index: [0, 1, 2]
< geowebcache-cache-result: HIT
< geowebcache-tile-index: [0, 1, 2]
< geowebcache-tile-bounds: -180.0,-38.0,-52.0,90.0
< geowebcache-gridset: GlobalCRS84Pixel
< geowebcache-crs: EPSG:4326
< Content-Type: image/png
< Content-Length: 102860
< Server: Jetty(6.1.8)

Last-Modified and If-Modified-Since¶

Well behaved HTTP 1.1 clients and server applications can make use of this HTTP control mechanism to know when the locally cached content (like a tile image already downloaded by the browser) hasn’t changed on the server and hence it’s local copy is up to date, hence there’s no need to re-download the same content. This can result in considerable bandwidth savings.

The mechanism is explained in HTTP’s 1.1 RCF 2616, sections 14.29 and 14.25.

GeoWebCache will write a Last-Modified HTTP response header when serving a tile image as an RFC-1123 HTTP-Date (e.g. Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT). Clients can use the value of that response header in the following requests for the same tile using the If-Modified-Since request header. If the tile wasn’t modified after that instant, GeoWebCache will return a 304 status code (304) indicating that the conditional GET operation found that the resource was available and not modified.

Try it yourself:

curl -v "http://localhost:8080/geowebcache/service/wms?LAYERS=img%20states&FORMAT=image%2Fpng&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&EXCEPTIONS=application%2Fvnd.ogc.se_inimage&SRS=EPSG%3A4326&BBOX=-135,45,-90,90&WIDTH=256&HEIGHT=256">/dev/null

> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 200 OK
...
< Last-Modified: Wed, 25 Jul 2012 00:42:00 GMT
< Content-Type: image/png
< Content-Length: 31192

Now use the value of the returned Last-Modified response header in the request and check thre response code. No content is actually transferred, but the client is informed it’s copy of the tile is up to date:

curl --header "If-Modified-Since: Wed, 25 Jul 2012 00:42:00 GMT" -v "http://localhost:8080/geowebcache/service/wms?...">/dev/null

> Host: localhost:8080
> Accept: */*
> If-Modified-Since: Wed, 25 Jul 2012 00:42:00 GMT
>
< HTTP/1.1 304 Not Modified
< Last-Modified: Wed, 25 Jul 2012 00:42:00 GMT
< Content-Type: image/png
< Content-Length: 31192

Set the If-Modified-Since header to one second before, and you should get a 200 status code and the tile content instead:

curl --header "If-Modified-Since: Wed, 25 Jul 2012 00:41:59 GMT" -v "http://localhost:8080/geowebcache/service/wms?...">/dev/null

> Host: localhost:8080
> Accept: */*
> If-Modified-Since: Wed, 25 Jul 2012 00:41:59 GMT
>
< HTTP/1.1 200 OK
...
< Last-Modified: Wed, 25 Jul 2012 00:42:00 GMT
< Content-Type: image/png
< Content-Length: 31192