Local Services Ads (LSA) to partner with aggregators to surface their listings (or providers) on Google.com. In this guide, we describe how aggregators can provide LSA structured data about their providers. Specifically, we document the set of API endpoints aggregators must implement for integrating with LSA.
Glossary
Aggregator (or partner): These are partners that aggregate providers to whom they provide services and whose data may be provided to LSA..
3P provider (or listing): These are the individual small businesses (e.g., Joe’s plumbing) who may have a business relationship with aggregators. Aggregators provide to Local Services information about these businesses.
Overview
Aggregators will provide data about their providers (businesses) to Local Services using feeds. Each feed consists of data about multiple providers. Within a feed, data about a single provider is encapsulated by a feed item. Each feed also specifies a feed timestamp that denotes the freshness of the feed. Each feed also specifies a feed type: this may be data about the provider profile or provider reviews as described below.
Feed types
For the initial integration, each feed may be one of the following feed types:
Profile feeds: This feed provides information about provider profiles. Each feed item encapsulates profile information about a particular provider. This includes a unique business ID, business name, serving locations, services offered, hours of operation etc. The feed item also contains serving metadata for this business (e.g., amount of monthly budget, ad status etc).
Review feeds: This feed provides information about provider reviews. Each feed item encapsulates a list of detailed consumer reviews of a particular provider. Each consumer review consists of the consumer name, rating (1 - 5), review text, review timestamp etc.
More details about the specific fields and their semantics in Profile feed and Review feed.
Feed ingestion
Feed data is serialized as JSON. To submit data, LSA will only support a pull mechanism. There are future plans to support a push mechanism.
Pull mechanism
In the pull mechanism, aggregators support a set of predefined REST endpoints (URLs) that send and receive JSON objects. This is analogous to hosting one or more files on a web server. LSA will periodically issue HTTP GET requests to these URLs to fetch data. Details about the predefined URLs can be found in the next section on API endpoints.
Push mechanism
In the push mechanism, LSA will provide an endpoint for aggregators to call and provide data. Semantically, this is the same as a pull, but provides flexibility in the cases where aggregators want to push specific data to Local Services. All semantics, rules or constraints described in the protocol apply to both push and pull in the same manner.
API endpoints
The following endpoints should be supported by aggregators: one for profile feed and one for review feed.
Recommended endpoints path
We recommend the endpoints contain version information such as below. We start
with v1.
| Endpoint | Path |
|---|---|
| Profile feed | /feeds/{version}/profile |
| Review feed | /feeds/{version}/review |
Endpoint param
| Params | Description |
|---|---|
maxresults |
This is the limit for how many feed items can be requested in a page. |
nextpagetoken |
Pagination token to get the next page of results |
Endpoint Authentication
Authentication uses HTTP basic access authentication: base64-encoded username and password for authentication. Below is an example.
username“Authorization” (for illustrative purposes)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (for illustrative purposes)
SFTP dropbox for Push
Dropbox path: partnerupload.google.com:19321
WARNING: Files loaded to this SFTP drop box are automatically deleted after 24 hours.
Endpoint Authentication
Public/private key pair (recommended)
- Use tutorial here to generate key pairs.
- Send LSA the public key and keep the private key for authentication
- LSA will use the public key to generate a username and send back to aggregator
Password authentication
- LSA will generate the username and password and send back to aggregator
SFTP command quick reference
Log in. Use this command to log in. (Leave out -i
if you don't use a private key). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comCopy file. Copy the file into the remote system. You can use
lls/lcdtols/cdinto your local system to find the file. Then copy the file via:put <path_to_local_file>Verify. Use
lsto see a list of folders and files in the SFTP directory and verify that your file has been copied to the remote system
Feed Categories
As noted earlier, each feed is analogous to a file and consists of several feed items. Each feed item encapsulates data about a particular provider (unique business ID). Each feed also has a timestamp that denotes the freshness of this feed. Feed Category specifies how LSA interprets a given feed. There are two categories of feeds as described below.
Snapshot feed contains a complete list of providers (under an aggregator) at a particular timestamp. After processing this snapshot feed, the following semantics apply:
For any provider present in the feed, the system will update the data for this provider in the LSA database (e.g., create a new provider if encountered for the first time, or update the provider data if the provider was processed in an earlier feed).
For any provider under the aggregator currently present in the LSA database, but missing in the feed, the provider will be deleted.
Update (or Incremental) feed contains a partial list of providers (under an aggregator) at a particular timestamp. After processing an incremental feed, the following semantics will apply:
For any provider present in the feed, the system will update the data for this provider in the LSA database if the provider was created in an earlier snapshot feed. (e.g. if a provider is encountered first time, it will be a no-op)
For any provider currently present in the LSA database, but missing in the feed, this is a no-op (i.e., there will be no change to this provider).
The semantics for profile vs reviews feed are slightly nuanced. See individual feed semantics for processing details.
Profile feeds: * Pull-based Snapshot feeds * Push-based Snapshot feeds * Push-based Update feeds Review feeds: * Pull-based Snapshot feeds * Push-based Snapshot feeds
Separate profile feeds are required for:
Providers that are deemed eligible for the Google Guarantee or Google Screened badge.
Providers who are not eligible for the badge.
Examples
Snapshot feeds
Recall that a snapshot feed will consist of a complete list of providers. For example, if an aggregator wants 100 providers to be ingested into LSA, the snapshot feed should contain the latest state for all 100 providers.
How this works
Below is a simple example demonstrating how the snapshot category of profile feeds work.
- Snapshot 1 has Pro 1, Pro 2
- Snapshot 2 has Pro 1, Pro 3
After processing Snapshot 1, LSA database will have Pro 1 and Pro 2. During processing of Snapshot 2, LSA will update Pro 1, create Pro 3 and Delete Pro 2. That is, after the processing of Snapshot 2, LSA database will have Pro 1 and Pro 3.
Update (Incremental) feeds
Recall that an update feed contains a partial list of providers under an aggregator. For example, if an aggregator only wants to update 5 of it’s previously provided 100 providers, the update feed need only contain the latest state for these 5 providers.
How this works
Below is a simple example demonstrating how the update category of “profile feeds” work.
- Update 1: Pro 1, Pro 2
- Update 2: Pro 1, Pro 3
After processing Update 1, LSA database will have Pro 1 and Pro 2. During the processing of Update 2, LSA will update Pro 1, and create Pro 3. Note that Pro 2 is untouched. That is, after processing of Update 2, LSA database will have Pro1, Pro2 and Pro 3.
Implications of Snapshot and Pull
The snapshot feeds + pull mechanism implies the following restrictions:
- There may be a delay of a few hours for partners to add or delete providers, update profile information, pause ads or change budgets. Delay is directly related to the frequency of the pull requests.
- For urgent data updates, we may need to manually support a one-off/adhoc pull.
Implications of Incremental and Push support
Opening update feeds + push mechanism implies the following improvements:
- Partners can deliver snapshot feed in either push or pull. For partners who prefer not to maintain the endpoint (for pull) can use push instead to reduce endpoint maintenance cost. Partner already supported snapshot feeds in pull can feel free to keep delivering snapshots in pull.
- Partners can use incrementals to update only a subset of providers with profile changes. This improves profile data freshness.
- In terms of how to choose snapshot vs incrementals, push vs pull, see this section for recommended integration approach.
Recommended integration approach
Partners are required to have periodic snapshot feeds, whether via push or pull. This allows LSA to handle emergencies like rollbacks and system-recovery in the event of missed updates.
- With the push mechanism, partners should push snapshot profile feeds every 2 hours and review feeds every 6 hours to guarantee baseline data freshness.
- With the pull mechanism, LSA will pull snapshot profile feeds every 2 hours and review feeds every 6 hours to guarantee baseline data freshness.
- Partners only need one of the mechanisms (either push or pull), but not both, to deliver snapshot feeds.
Optionally, partners who want to improve data freshness can send update feeds via push. LSA will not pull update feeds.
- Update feeds are used to propagate changed items since the last snapshot without waiting for the next snapshot.
- LSA recommends providers to have greater than a 5 minute interval between two pushes.
- It is recommended to bundle feeditems reasonably in an update feed. To update 5 providers, LSA prefers providers to push 1 update feed with 5 feeditems instead of pushing 5 update feeds with 1 feeditem in each.
- LSA supports incremental feeds only for profile feeds, not for review feeds.
LSA will honor the feedTimestampMicros field in the metadata to guarantee data
consistency. A feed item with an older timestamp will be skipped to avoid
introducing staleness if a fresher item that updates the same pro has been
ingested. It is the partner’s responsibility to reflect data freshness correctly
using feedTimestampMicros in both snapshot and update feeds.
Partners should use the Reporting API to get information on leads and charges per provider.