Image and Location Migration in Google Ads API

[Kevin]

Hi,

I saw there was a post on 2/13 about image and location auto-migration:

Google Ads Developer Blog: Image and Location Auto-migrations in Google Ads API (googleblog.com)

However, it's not clear to me how to map between old feed-based extension fields and new asset-based fields.

For example, for location extensions there are quite a lot of fields:

location_feed_item.address_line_1

location_feed_item.address_line_2
location_feed_item.business_name
location_feed_item.city
location_feed_item.country_code
location_feed_item.phone_number
location_feed_item.postal_code
location_feed_item.province

ad_schedules

start_date_time

end_date_time

My initial thought was that there would be similar fields in a `location_asset`. However, it looks like they don't really match:

location_asset.business_profile_locations
location_asset.location_ownership_type
location_asset.place_id

I could imagine that an extra request to the Places API could be necessary to decode that place_id, but I hope this is not the case - it would be quite a lot of extra work to onboard another API just to get the same data.

I'm looking for some explanation on how the fields are migrated and some advice on how to continue to retrieve these fields after the migration. I'd like to "migration-proof" my code before auto-migration starts in April.

Thanks,

Kevin

[Google Ads API Forum Advisor]

Hi Kevin,

Thank you for raising this concern to the Google Ads API Forum.

Extension setting services are deprecated and will be removed in an upcoming release. That said, you should migrate to Assets as soon as possible. Please note that the image and location extension as a feed based extension will become an asset based image extension. As mentioned in this blog post, beginning on April 3, 2023, we will start auto-migrating image and location extensions to assets. It means the format will be in the assets format. Also, our note says that Asset-based extensions will soon replace Feed-based extensions managed by Extension setting services.

I would recommend checking this Asset-based extensions document as it contains all the details about this. Also, this document as it shows how to report asset based extensions in the Google Ads API.

Let us know if you have further questions.

Best regards,

Jinky Google Ads API Team

ref:_00D1U1174p._5004Q2j1cSB:ref

[Kevin]

Hi Jinky,

I understand that the Feed-based extensions are going to migrated and I believe I said so in the first email when I brought up that blog post.

I think there is some miscommunication here - I am not asking whether I need to migrate or not (I know I do), I'm asking what the corresponding fields are in the new version.

For example, I listed the fields I saw were active for the Location Extensions in the feed-based world and the (lack-of) fields in what I thought was the corresponding Asset entity.

What I would like is clarity on how the existing fields for the feed-based versions of Location/Image Extensions map onto fields in the Asset entity.

I've read through the documentation you linked and, though I may have missed something, don't see the answer to my question.

I would like to also direct your attention to this section:

https://developers.google.com/google-ads/api/docs/extensions/assets/migrating-extensions#changes_in_asset-based_extensions

Which is supposed to show the changes in the Extensions after the migration.

Note that there are no noted changes for Location or Image Extensions - this means I would expect the fields to remain the same after migration.

This was the case for all the previous Extension migrations (e.g. App, Call, Sitelink, etc).

So, my question is still: "where are the corresponding Asset fields for Location(or Image) Extensions)"?

A specific example would be, "where is the Asset data for the Location Extension's Address?"

Apologies for the confusion, and thanks for the help.

Best,

Kevin

[Google Ads API Forum Advisor]

Hi Kevin,

Thank you for getting back to us. I hope that you are doing well today.

Moving forward to your concern, based in this document, the current extensions that support assets are listed below:

• Call
• Callout
• Hotel Callout
• Lead Form
• Mobile App
• Price
• Promotion
• Sitelink
• Structured Snippet

 
Eventually, more will be added soon and the location and image asset is not yet on the list of extensions for supporting assets. In addition, you may still continue creating location extensions by following this guide. However please note that it is stated in this blog, "The auto-migration will not keep a mapping of feed IDs to asset IDs. If you would like to keep a record of feed IDs to asset ID mappings, create a new asset image or location based on your feed, and save that ID mapping locally.".

I hope this helps. 

Kind regards,

Sherwin Vincent Google Ads API Team

ref:_00D1U1174p._5004Q2j1cSB:ref

[Kevin]

Accidentally replied to author instead of to all in my last reply . Re-iterating in a "Reply All" in case others are having the same issue.

Based on this conversation, I'm worried about the overall timeline for these 3 reasons:

1. As you've mentioned, the auto-migration starts in April, a little more than a month away.

2. Sherwin mentioned that the Location/Image Extensions are not available in the current APIs.

3. I would like my code to be ready to consume the new Asset Location/Image Extensions before the auto-migration.

A month is already not a very long time to get the required code ready, but it shrinks further if the new Asset data is not available.

I think many API users who get Location/Image Extension data (myself included) will want to be ready to get the Asset data before the migration.

So if it not available in V12/V13 like the blog post announcing the Location/Image Extension migration seemed to imply I would like the auto-migration date postponed.

If it is available in V12/V13 (like the blog post seems to imply), then I would like to know the expected mapping for Location Extensions.

For example, for Promotion Extensions, there is an example in the documentation:

https://developers.google.com/google-ads/api/docs/extensions/assets/migrating-extensions#create_an_asset-based_extension

and the mapping is reasonably clear from the names:

https://developers.google.com/google-ads/api/fields/v13/extension_feed_item

promotion_feed_item.discount_modifier
promotion_feed_item.final_mobile_urls
promotion_feed_item.final_url_suffix
promotion_feed_item.final_urls
promotion_feed_item.language_code
promotion_feed_item.money_amount_off.amount_micros
promotion_feed_item.money_amount_off.currency_code
promotion_feed_item.occasion
promotion_feed_item.orders_over_amount.amount_micros
promotion_feed_item.orders_over_amount.currency_code
promotion_feed_item.percent_off
promotion_feed_item.promotion_code
promotion_feed_item.promotion_end_date
promotion_feed_item.promotion_start_date
promotion_feed_item.promotion_target
promotion_feed_item.tracking_url_template

https://developers.google.com/google-ads/api/fields/v13/asset

promotion_asset.ad_schedule_targets
promotion_asset.discount_modifier
promotion_asset.end_date
promotion_asset.language_code
promotion_asset.money_amount_off.amount_micros
promotion_asset.money_amount_off.currency_code
promotion_asset.occasion
promotion_asset.orders_over_amount.amount_micros
promotion_asset.orders_over_amount.currency_code
promotion_asset.percent_off
promotion_asset.promotion_code
promotion_asset.promotion_target
promotion_asset.redemption_end_date
promotion_asset.redemption_start_date
promotion_asset.start_date

This is not the case for Location:

FeedItem

location_feed_item.address_line_1
location_feed_item.address_line_2
location_feed_item.business_name
location_feed_item.city
location_feed_item.country_code
location_feed_item.phone_number
location_feed_item.postal_code
location_feed_item.province

Asset

location_asset.business_profile_locations
location_asset.location_ownership_type
location_asset.place_id

Thanks,

Kevin

[Google Ads API Forum Advisor]

Hi Kevin,

Thank you for your reply. 

We really understand your concern, however, this auto-migration date can't be postponed. With this, as per our blog post "The auto-migration will not keep a mapping of feed IDs to asset IDs. If you would like to keep a record of feed IDs to asset ID mappings, create a new asset image or location based on your feed, and save that ID mapping locally.".

Best regards,

Google Ads API Team

 

ref:_00D1U1174p._5004Q2j1cSB:ref

[Kevin]

Hi (didn't see who replied this time in the response),

It is fine if the auto-migration cannot be postponed, so long as there is still a way to get the migrated data.

So after the auto-migration happens, how can I get that Location (and Image) Extension data from the Assets?

I'm not worried about the id mapping at the moment, just being able to get the details from the extension (e.g. location extension's address, postal code, etc).

How can I get that data after the migration?

Thanks,

Kevin

[Kevin]

Or, if you could just point me to a document explaining how to "create a new asset image or location based on your feed" (as you mentioned in your previous reply) that might suffice as well.

For Location Extensions - how do you create the corresponding Location Asset?

[Google Ads API Forum Advisor]

Hi Kevin,

Thank you for the clarification. We really understand your concern and we appreciate your patience here.

As per blog post is on the migration of deprecated feed based image and location extensions to asset based extensions. I am afraid that asset based Image / location extensions are not supported.

To answer this "So after the auto-migration happens, how can I get that Location (and Image) Extension data from the Assets?", unfortunately, we can give any information in the feature related questions as this is still on process. Please follow our blog post to see what changes have been made for any given release.

Best regards,

[Kevin]

Thanks, I'll monitor the blog.

But I do think this release is a bit... rushed.

If I'm understanding here:

1. the data will certainly be auto-migrated from feed->asset in early April

2. the old feed data should get cleaned up (and anyway won't reflect the actually serving assets) after the migration

3. the new asset data is not available via API after the migration

This doesn't seem right for the API users.

Is there any workaround to get the data post-migration?

[Kevin]

Or, could someone provide the justification for doing it this way?

[Google Ads API Forum Advisor]

Hi Kevin,

Good day to you. Please allow me to raise this concern to the rest of our team. Rest assured that we will get back to you as soon as we have an update.

Kind regards,

[Google Ads API Forum Advisor]

I'm attempting to understand your concerns from the multiple interactions. So that we are clear on terminology, extension refers to the feed based model and assets refers to the new model.

Starting 3 April 2023, accounts will be eligible to be automigrated for image and location extensions. Once an account is selected for auto-migration, the account is prevented from mutating extension during which time the extensions continue to serve, the automigration takes place (a couple of minutes), assets start to serve and extension mutation is permanently disallowed on this account.

Currently, you can create location and image assets in test accounts.

https://developers.google.com/google-ads/api/docs/location-extensions/location-assets
https://developers.google.com/google-ads/api/samples/upload-image-asset

As of 3 April you will be able to do this in production accounts.

As to your question as to why we decided to do it this way:

Location assets are are extremely complex to migrate and there is no good user path for this. We can do it efficiently on the back end and guarantee that the locations are efficiently and safely migrated. Image assets are more numerous that locations assets, so we decided to auto-migrate them also. Because the image assets are a new entity there is no mapping to the extension. If you want to keep a link then you need to create the map yourself.

Reporting for image and location assets are just like any other asset. You can see the list of reports with metrics at https://developers.google.com/google-ads/api/fields/v13/metrics This asset data will be available as soon as your account is migrated and the extension data will be available until sometime in 2024.

It is possible to move the images yourself by creating an image asset, linking it to campaign or adgroup via CampaignAsset or AdGroupAsset and then remove the original feeditem link so that the image asset will be used for serving instead of feeditem extension. We can't provide support for this if you decide to do it yourself.

We strongly recommend that you use the automigration. blog post: https://ads-developers.googleblog.com/2023/02/image-and-location-auto-migrations-in.html

Image and location automigrations will run in parallel but are not synchronized. So, an account can be migrated for each type at different times. The order of accounts chosen is non-deterministic, so even though the migration starts on 3 April 2023, you account could be migrated at any time between then and 15 September 2023. Check the blog post to see how to tell if your account has been migrated.

Once the image and location automigration is complete, extensions will not longer be able to be mutated and all of the Google Ads API will be asset based.

-- Bob Hancock

ref:_00D1U1174p._5004Q2j1cSB:ref

[Kevin]

Hi Bob,

Thanks for the response - it helps!

From the previous posts, I was under the impression that asset-based Image and Location extensions are not supported because of this quote:

"I am afraid that asset based Image / location extensions are not supported."

From your reply, it looks like they are supported and the way they are supported can be found in these two links:

https://developers.google.com/google-ads/api/docs/location-extensions/location-assets
https://developers.google.com/google-ads/api/samples/upload-image-asset

For asset-based location extensions, it looks like it's preferred to use a location sync asset set, which automatically generates the corresponding assets.

It looks like it is preferred to deal only in asset sets:

"First, create a location sync asset set and attach it to the customer. Then, if you need to select a subset of the location assets in the asset set for a campaign or ad group, create a location group asset set and attach it to the campaign or ad group."

It is not clear to me whether you have the option to directly generate and associate single assets.

The asset set association does not specify type and is explained in the document.

The asset association does have a specific type, but there does not look like there is one that corresponds to a location.

For asset-based image extensions, it looks like there are no asset sets for them based on the allowed types in the asset set:

https://developers.google.com/google-ads/api/reference/rpc/v13/AssetSetTypeEnum.AssetSetType

so I should create individual assets for each image extension and associate it to the customer/campaign/adgroup with an association (customer_asset/campaign_asset/ad_group_asset).

Question - For image extensions that are migrated to asset-based extensions, what is the asset association type?

The list here in the documentation has something clearly labeled for other extension types:

https://developers.google.com/google-ads/api/reference/rpc/v13/AssetFieldTypeEnum.AssetFieldType

For example: "The asset is linked for use as a Sitelink extension."

I venture to guess that the only one that makes sense is "AD_IMAGE", but I would like confirmation since it isn't in the document that Bob sent and it says:

"The asset is linked for use to select an ad image." rather than anything about extensions.

For what it's worth, I think it'd be helpful if more documentation was linked in the blog post announcing the auto-migration.

I think guides and examples on how to migrate each of the extension types manually and retrieve the data back would be helpful.

Thanks,

Kevin

[Kevin]

One more thing - it looks like to get the location data, I need to talk to the Places API which is a paid service.

Previously we could get this data for free from the Ads API - any way we can continue to get this data the same way?

[duca...@gmail.com]

Hello team,

Can you please let us know if you have update regarding Kevin's questions? Thank you. 

[Google Ads API Forum Advisor]

For asset-based location extensions, it looks like it's preferred to use a location sync asset set, which automatically generates the corresponding assets.
It looks like it is preferred to deal only in asset sets:
"First, create a location sync asset set and attach it to the customer. Then, if you need to select a subset of the location assets in the asset set for a campaign or ad group, create a location group asset set and attach it to the campaign or ad group."

rwh: It is not preferred it is required.

It is not clear to me whether you have the option to directly generate and associate single assets.
The asset set association does not specify type and is explained in the document.
The asset association does have a specific type, but there does not look like there is one that corresponds to a location.

rwh: This is a question for our support alias. I can answer question regarding the auto-migration, but API usage questions should be in a separate request.

For asset-based image extensions, it looks like there are no asset sets for them based on the allowed types in the asset set:
https://developers.google.com/google-ads/api/reference/rpc/v13/AssetSetTypeEnum.AssetSetType

so I should create individual assets for each image extension and associate it to the customer/campaign/adgroup with an association (customer_asset/campaign_asset/ad_group_asset).

rwh: https://developers.google.com/google-ads/api/samples/upload-image-asset shows how to upload an image asset. Once uploaded if you are using it as a field type AD_IMAGE you can link it to CampaignAsset
or AdGroupAsset.

Question - For image extensions that are migrated to asset-based extensions, what is the asset association type?
The list here in the documentation has something clearly labeled for other extension types:
https://developers.google.com/google-ads/api/reference/rpc/v13/AssetFieldTypeEnum.AssetFieldType

For example: "The asset is linked for use as a Sitelink extension."
I venture to guess that the only one that makes sense is "AD_IMAGE", but I would like confirmation since it isn't in the document that Bob sent and it says:

"The asset is linked for use to select an ad image." rather than anything about extensions.

For what it's worth, I think it'd be helpful if more documentation was linked in the blog post announcing the auto-migration.
I think guides and examples on how to migrate each of the extension types manually and retrieve the data back would be helpful.

rwh: We have documentation pending that will be available prior to the start of the auto-migration. The field type will most likely be AD_IMAGE as you state.

If the source was used as field type:
HEADLINE

LONG_HEADLINE

DESCRIPTION

MANDATORY_AD_TEXT

CALL_TO_ACTION_SELECTION

It will be moved within the same type of ad originally used.

 

ref:_00D1U1174p._5004Q2j1cSB:ref

[Kevin]

Hi,

I had lost track of this thread when  Google Ads Developer Blog: Image and Location Auto-migration in Google Ads API Postponed (googleblog.com) had been posted in late March.

I see that it's now on track again to be migrated in early August now: Google Ads Developer Blog: Image and Location Auto-migration August 2023 (googleblog.com)

However, I still do not quite understand how I can get the location data (e.g. address) post-migration.

To re-iterate from my previous posts on this thread:

I would like to understand how we can prepare code post-migration to get the location data (address, business name, city, country code, ...)

Thanks,

Kevin

[Google Ads API Forum Advisor]

I've asked for the mapping and will replay here with an update when I receive it.

 

This message is in relation to case "ref:_00D1U1174p._5004Q2j1cSB:ref"

Thanks,
 

Bob Hancock Google Ads API Team

 

[Google Ads API Forum Advisor]

During the migration, if you have filled in the location feed item fields, we will calculate a Place ID and insert it in the asset.

In Location assets, the fields:

location_feed_item.address_line_1
location_feed_item.address_line_2
location_feed_item.business_name
location_feed_item.city
location_feed_item.country_code
location_feed_item.phone_number
location_feed_item.postal_code
location_feed_item.province

are not stored as part of the asset. You can obtain the data via
location_asset.place_id

using the Google Maps API you can input place ids to retrieve whatever organic location information you would like to  have: https://developers.google.com/maps/documentation/places/web-service/place-id

[Kevin]

Hi Bob,

It's been a few days - any update on this?

Thanks,

Kevin

[Google Ads API Forum Advisor]

I replied on 12 July with the response below. This should answer the question from my understanding.

During the migration, if you have filled in the location feed item fields, we will calculate a Place ID and insert it in the asset.

In Location assets, the fields:

location_feed_item.address_line_1
location_feed_item.address_line_2
location_feed_item.business_name
location_feed_item.city
location_feed_item.country_code
location_feed_item.phone_number
location_feed_item.postal_code
location_feed_item.province

are not stored as part of the asset. You can obtain the data via
location_asset.place_id

using the Google Maps API you can input place ids to retrieve whatever organic location information you would like to  have: https://developers.google.com/maps/documentation/places/web-service/place-id

 

[Kevin]

Thanks!

I did see the place_id before, but it looks like the Places API is a paid service:

https://developers.google.com/maps/documentation/places/web-service/usage-and-billing

Are we expected to pay for this data now?

-Kevin

[Kevin]

Oh never mind - it looks like the SKU for if we have the place_id may be free:

https://developers.google.com/maps/documentation/places/web-service/usage-and-billing#find-place-id-only

And the "Find Place" request does seem to have the address information:
https://developers.google.com/maps/documentation/places/web-service/search-find-place#find-place-responses

It is a bit strange that we'd have to call a different service at all and I worry about the price changing in the future.

-Kevin

[Google Ads API Forum Advisor]

I can't guarantee the future, but we don't have a policy of charging for APIs. Originally, you had to pay to use the Ads API but it was not a successful use case and it was abandoned years ago.

Google has a number of APIs that can include location details. The thinking was to have it all in one place so that it is a consistent experience across multiple products.

[Kevin]

Hi,

I started using the Places API but found out recently that the Place Details request that gives the address and phone # information is not free.

Is there a different request I can use to get the address information for Location extensions without paying money for each request?

Thanks,
Kevin

[Kevin]

Hi,

I got a private reply, but it looks like Gmail may have gotten confused and split the email thread so let me reiterate the current details here.

I've tried using the place_id to retrieve data from the Places web service as suggested in the Google Ads API documentation: asset.location_asset.place_id

However, all of the requests I can make there to get location extension data (e.g. address, phone #) cost money to use.

Advertisers using the Google Ads API can handle a large volume of locations, so the single-place-id, rate-limited requests to the Places API look both inefficient and costly.

I think it's unlikely that Google would just remove the data from the Ads API and force their API users to buy the data back.

Instead, I think I haven't found the correct request in the Places API.

Could you help me understand what the new workflow to get Location data is?

Migration from Location Extensions to Location Assets is already underway.

Thanks,

Kevin