The Content-Location
header indicates an alternate location for the returned data. The principal use is to indicate the URL of a resource transmitted as the result of content negotiation.
Location
and Content-Location
are different. Location
indicates the URL of a redirect, while Content-Location
indicates the direct URL to use to access the resource, without further content negotiation in the future. Location
is a header associated with the response, while Content-Location
is associated with the data returned. This distinction may seem abstract without examples.
Header type | Entity header |
---|---|
Forbidden header name | no |
Syntax
Content-Location: <url>
Directives
Examples
Requesting data from a server in different formats
Let's say a site's API can return data in JSON, XML, or CSV formats. If the URL for a particular document is at https://example.com/documents/foo
, the site could return different URLs for Content-Location
depending on the request's Accept
header:
Request header | Response header |
---|---|
Accept: application/json, text/json |
Content-Location: /documents/foo.json |
Accept: application/xml, text/xml |
Content-Location: /documents/foo.xml |
Accept: text/plain, text/* |
Content-Location: /documents/foo.txt |
These URLs are examples — the site could serve the different filetypes with any URL patterns it wishes, such as a query string parameter: /documents/foo?format=json
, /documents/foo?format=xml
, and so on.
Then the client could remember that the JSON version is available at that particular URL, skipping content negotation the next time it requests that document.
The server could also consider other content negotiation headers, such as Accept-Language
.
Pointing to a new document (HTTP 201 Created)
Say you're creating a new blog post through a site's API:
PUT /new/post Host: example.com Content-Type: text/markdown # My first blog post! I made this through `example.com`'s API. I hope it worked.
The site returns a generic success message confirming the post was published. The server specifies where the new post is with Content-Location
:
HTTP/1.1 201 Created Content-Type: text/plain; charset=utf-8 Content-Location: /my-first-blog-post ✅ Success!
Indicating the URL of a transaction's result
Say you have a <form>
for sending money to another user of a site.
<form action="/send-payment" method="post"> <p> <label>Who do you want to send the money to? <input type="text" name="recipient"> </label> </p> <p> <label>How much? <input type="number" name="amount"> </label> </p> <button type="submit">Send Money</button> </form>
When the form is submitted, the site generates a receipt for the transaction. The server could use Content-Location
to indicate that receipt's URL for future access.
HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Content-Location: /my-receipts/38 <!doctype html> (Lots of HTML…) <p>You sent $38.00 to ExampleUser.</p> (Lots more HTML…)
Specifications
Specification | Title |
---|---|
RFC 7231, section 3.1.4.2: Content-Location | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content |
Browser compatibility
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Content-Location | Chrome Full support Yes | Edge Full support 12 | Firefox Full support Yes | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
Legend
- Full support
- Full support