Share your feedback about the Google Ads (AdWords) API. Take the 2021 AdWords API and Google Ads API Annual Survey.

Serving URL Expansion Rules

When using Upgraded URLs, the serving URL for an ad or ad extension is constructed by combining various fields according to a set of rules. This section examines these rules in more detail.

Hierarchy of Google Ads entities

When resolving Upgraded URL fields, the following hierarchy (highest to lowest) is used by Google Ads:

Customer
    Campaign
        Ad Group
            Ad
                Ad Group Criterion
                    FeedItem (including sitelinks)

Which final URL is used?

The final URL is used by default when building the serving URL. If an supported entity is served on a mobile network and has a valid final mobile URL, then that is used instead of the final URL. Final app URL is currently supported only for app engagements ads.

How the system expands the serving URL

Here are the steps the system takes when expanding the serving URL:

  1. Determine which final URL to use.

    It starts by determining which final URL to use. This varies depending on the entity involved.

    Entity Which final URL to use?
    FeedItem (sitelink) Always use its own final URL.
    Ad X served on keyword Y If the keyword has its own final URL, use it.

    Otherwise use the ad’s final URL.

  2. Determine which tracking URL template to use.

    The tracking URL for an entity is determined by traversing its object hierarchy, and choosing the value from the entity lowest in the hierarchy. If no tracking URL template values can be found in the hierarchy, the tracking URL template's value is set to empty.

    For example, if an ad has tracking URL template values defined only at its parent ad group and account levels, the value from the parent ad group is used.

  3. Determine which custom parameter values to use.

    The value for a given custom parameter is resolved by traversing the object hierarchy, and choosing the value from the entity lowest in the hierarchy. If no value is defined for the custom parameter, an empty string is used as its value.

    For example, when determining the value for a particular custom parameter at the ad level, if that custom parameter has values defined at its parent ad group and at the account level, the value from the parent ad group is used.

  4. Expand the final URL.

    The system expands the final URL by performing the following three steps:

    1. Expand the custom parameter values.

      The system parses the final URL and substitutes the values for each custom parameter in the URL, using the values determined in step 3 above.

    2. Expand the ValueTrack tags in the URL.

      The system parses the final URL, and substitutes values for any ValueTrack tags present in the URL.

    3. Strip the {ignore} tag.

      Any {ignore} ValueTrack parameter in the expanded final URL is removed.

  5. Expand the tracking template.

    If there's an empty value for the tracking template (as determined above in step 2), this step is skipped. Otherwise, the tracking URL template is expanded as follows:

    1. Expand the custom parameter values.

      The system parses the tracking template URL, and substitutes the values for each custom parameter in the URL using the values determined in step 3.

    2. Expand the ValueTrack tags in the URL.

      The system parses the tracking template URL, and substitutes values for any ValueTrack tags present in the URL.

    3. Substitute {lpurl} parameter in tracking template.

      If the tracking template URL contains {lpurl} or one of its variants, it's replaced with the expanded final URL from step 4.

      • If {lpurl} is inserted at the beginning of the tracking template, then it is not escaped. If positioned elsewhere in the tracking template, the following characters are escaped: ?, =, ", #, \t, ', and \[space\].
      • {unescapedlpurl} is always unescaped.
      • {escapedlpurl} is always escaped.
      • {lpurl+2} is always escaped twice.
      • {lpurl+3} is always escaped three times.
  6. Pick the serving URL.

    If your tracking template URL is empty, the expanded final URL from step 4 is used. Otherwise, the system uses the expanded tracking template URL from step 5.

    Sitelinks are an exception to this rule: If the tracking URL template (determined in step 2) does not contain the {lpurl} parameter, then the sitelink's final URL is used as the serving URL.

Example scenarios

Consider an account with the following structure:

Account
    Campaign 1
        Ad Group 1
            Ad 1
            Keyword 1 (shoes)
            Keyword 2 (hats)
        Ad Group 2
            Ad 2
            Ad 3
            Keyword 3 (watches)
    FeedItem 1 (sitelink 1)

Assume the following Upgraded URL fields are defined on these entities:

Entity name Tracking URL template Final URL Custom Parameters
Account http://www.cid1-tracking.com/?{_myid}&u={lpurl}
Campaign 1 _mycampaign=cam1
Ad Group 1 http://www.ag1-tracking.com/?{_mycampaign}&u={lpurl}&{_myid} _myid=ag1id
Ad Group 2 _myid=ag2id
Ad 1 http://www.creative1-final.com/?{keyword}{ignore}&{_myid}&{_mycampaign}
Ad 2 http://www.creative2-final.com/?{keyword}{ignore}&{_myid} _myid=ad2id
Ad 3 http://www.ad3-tracking.com/?{_mycampaign}
Keyword 1 final URL: http://www.kw-final.com/?{keyword}{ignore}&{_mycampaign}

final mobile URL: http://m.kw-final-mobile.com/?{keyword}{ignore}&{_myid}
_myid=k1Id
Keyword 2
Keyword 3
FeedItem 1 final URL: http://www.sitelink-final.com/?{keyword}{ignore}&{_mycampaign}

final mobile URL: http://m.sitelink-final-mobile.com/?{keyword}{ignore}&{_myid}

The following values are used for expanding the ValueTrack parameter {keyword}:

  • Keyword 1: shoes
  • Keyword 2: hats
  • Keyword 3: watches

The following sections show how various parameters get resolved for each of these entities.