AMP documents are often served from a third-party cache; this means it’s not always clear how to support dynamic or personalized content. There are a range of components and techniques to achieve many of these use cases (amp-list, amp-state, amp-form, and amp-iframe just to name a few), but there are some common cases the AMP team can make a lot easier.

In particular, businesses often want to vary content by the geographic location of the user. The best way to do this for pages in different languages is to use the hreflang attribute, but this isn’t the best solution for pages with just a small geo-dependent variation, like a promotion for a particular locale. This is why we’ve created the amp-geo component, which is ready for testing, and targeting a full release next week.


amp-geo makes it easy to vary small sections of web content for users based on an approximation of the users’ country-level location, similar to the level of an ISO Country Code. As a developer, there are just a few steps:

1. Include the amp-geo script

In the document <head>:

<script async custom-element="amp-geo" src=""></script>

2. Include the amp-geo tag

In the document <body>:

<amp-geo layout=”nodisplay”></amp-geo>

3. Mark up your document with CSS to alter content based on the user’s approximate location

In the <style amp-custom> tag:

/* defaults */
.flag { background-image: "./starsandstripes.png"; }
/* override */
.amp-iso-country-ca .flag { background-image: "./mapleleaf.png"; }

In the document <body>:

<div height=”300” width=”500” layout=”responsive” class=”flag”>

Groups in amp-geo

Here’s a slightly more advanced case, where you can take advantage of the grouping feature in amp-geo to vary an aspect of English dialect by geo.

1. As above, include the amp-geo script in theof your document

2. Instead of just including an empty amp-geo tag, configure ISOCountryGroups to reduce the amount of code you have to write to specify behaviors across multiple locales.

In the document <body>:

<amp-geo layout=”nodisplay”>
  <script type="application/json">
    “ISOCountryGroups”: {
      "soccer": [ "au", "ca", "ie", "nz", "us", "za" ],
      "football": [ "unknown" ]

3. As in the previous example, mark up the document with CSS to alter content based on the user’s approximate location

In the <style amp-custom> tag:

/* defaults */
.football:after { content: 'football';}
/* override */
.amp-geo-group-soccer .football:after { content: 'soccer' }

In the document <body>:

The game is called <span class='football'></span>!

If the user is in any of the locales configured for “soccer”, then the text will read “The game is called soccer!” Otherwise, the text will read “The game is called football!”

You can find another, more complex example at AMP by Example, and learn about more extended capabilities of the feature in the official documentation; for instance, you can integrate amp-geo with your analytics through variable substitution, or use it in more complex interactions through amp-bind.

Try it out

amp-geo is targeting a full production release next week, but as of today you can test it on your site and tell us what you think. You can file bugs and requests in Github, and feel free to reach out and chat on Slack. We look forward to hearing from you!

Posted by Eric Lindley, AMP Product Manager