NearSt Local Ads

Channel ID: local_ads

In addition to the Google Channel, which helps retailers display their products across the organic surfaces in Google (See What's In Store, Local Listings), NearSt also offers the ability to use inventory to run fully automated and optimised Google Local Inventory Ads.

These endpoints allow you to manage retailers' Local Ads channel integration.

About Local Ads

Local Ads are a form of Google Shopping ads specifically optimised and targeted at local customers, aiming to get customers to visit physical retail locations.

Local Ads budgets

Local Ads are billed using a daily ads budget that the retailer defines through the API. These can be updated on a daily basis. New budgets will be activated at 12:00am on the next day.

Daily budgets are always defined in GBP (Pound sterling).

Local Ads targeting

Local Ads are targeted to customers in physical location radius around the retailer's store. By default, this is either a 3, 5, 10 or 20 mile radius, defined by the type of area in which a retailer is located.

NearSt automatically manages and optimises this, just like all other targeting parameters, including keywords and device types.

Parameters

string retailerId: specify a retailer ID to identify the correct retailer.
string storeId: specify a store ID to identify the correct retailer.
string type: 'local-ads'

Requirements

An inventory feed with at least 50 in-stock products. The more products, the better these ads perform. Adding your full inventory allows NearSt and Google to target specific products to specific customers, thereby creating new audiences that weren't previously exposed to your store.
A NearSt-managed Google Accounts setup through the google channel. Note that this channel needs to have status connected before the local-ads channel can be enabled, which might take a few days from the moment the channel is added, whilst we verify and set up the relevant Google accounts for the retailer.

Examples

Enabling Local Ads or updating a budget

After creating a retailer and creating a store within the retailer account, you can enable the Local Ads for retailers. Local Ads will activate at 12:00am the next day.

POST https://partner-api.near.st/v1/retailers/{retailerId}/stores/{storeId}/channels
Content-Type: application/json

{
  "type": "local-ads",
  "parameters": {
    "dailyBudget": 2
  }
}

The response will show the status of the current budget and the created upcoming budget as follows:

{
  "warnings": [],
  "status": "connected",
  "dailyBudget": 0,
  "upcomingChange": {
    "dailyBudget": 2,
    "activates": "2023-05-10T00:00:00.000Z"
  }
}

Checking Local Ads status

The API provides information about the status of the Local Ads channel for a specific store, including the current daily budget, any scheduled changes to the budget, and the channel's status, which can be either "connected" or "pending".

To check the status of Local Ads for a specific retailer and store, use the following GET request:

GET https://partner-api.near.st/v1/retailers/{retailerId}/stores/{storeId}/channels

If Local Ads is enabled for the store the response will show the status of the current budget and the upcoming budget as follows:

[
  {
    "warnings": [],
    "status": "connected",
    "dailyBudget": 5,
    "upcomingChange": {
      "dailyBudget": 7,
      "activates": "2023-05-10T00:00:00.000Z"
    }
  }
]

Disabling Local Ads

To turn off the Local Ads channel and set the budget to zero for a specific retailer and store, a DELETE request can be made to the provided URL with the path parameter "type=local-ads." Once the request is successfully completed, the Local Ads channel will be disabled, and the budget will be set to zero the following day.

DELETE https://partner-api.near.st/v1/retailers/{retailerId}/stores/{storeId}/channels/{type}

The path parameter type=local-ads is added to ensure that the correct channel is getting deleted.

Upon successful completion of the request, the budget for the Local Ads channel will be set to 0 the next day and effectively disabling the channel.

Webhooks Analytics