Program Feature API

πŸ“˜

This is a Yelp Partner API

Access is disabled by default. See Yelp Partner APIs on how to get access.

Overview

This document provides a reference to all endpoints of Program Feature API and contains sample request and responses. The Program Feature API allows retrieval and set-up of feature information for specific payment programs.

Authentication

Authentication uses Basic HTTP Authentication over SSL. The credentials used for the Yelp Data Ingestion API should be used for the Program Feature API.

Versioning

To maintain backwards-compatibility with partner-developed applications, the Program Feature API is versioned with the version encoded as the last path segment of the URL, i.e. https://<host>/<endpoint>/<version>. The current and latest version of the API is v1.

Format

Request and response bodies use the application/json content type and should be encoded in UTF-8. This format supports special characters (e.g. β€˜ & / % etc.).

Identifiers

Yelp identifiers are unique within a type of object only; they are not globally unique. For example, a photo and business may share the same identifier, WavvLdfdP6g8aZTtbBQHTw, but no other photo or business will have that same identifier.

Value Types

All date properties should use the YYYY-MM-DD format.

Program Feature API Endpoints

The Program Feature API provides a means to retrieve/modify/delete features for specific payment programs by calling into one of the following four endpoints:

MethodHTTP EndpointDescription
retrieveGET /program/<program_id>/features/v1Retrieve available and active features for the specified payment program
updatePOST /program/<program_id>/features/v1Set up or update program features for the specified payment program
deleteDELETE /program/<program_id>/features/v1Delete certain program features from the specified payment program

Supported Feature Types

The following table describes the format for the various features types you can set up using this API. The format will be used in both response and request bodies.

Feature Type IdentifierObject FormatNotes
LINK_TRACKING"LINK_TRACKING":
{
"website": {string|null},
"menu": {string|null},
"call_to_action": {string|null}
}
If all properties of the object are null, then the feature is disabled (not active).
NEGATIVE_KEYWORD_TARGETING"NEGATIVE_KEYWORD_TARGETING":
{
"suggested_keywords": [string],
"blocked_keywords": [string]
}
If the list of blocked_keywords is empty the feature is disabled (not active).
STRICT_CATEGORY_TARGETING"STRICT_CATEGORY_TARGETING":
{
"enabled": true|false
}
AD_SCHEDULING"AD_SCHEDULING": {
"uses_opening_hours": true|false
}
CUSTOM_LOCATION_TARGETING"CUSTOM_LOCATION_TARGETING":
{
"businesses": [{
"business_id": "string",
"locations": [string]
}]
}
AD_GOAL"AD_GOAL":
{
"ad_goal": string
}
CALL_TRACKING"CALL_TRACKING":
{
"enabled": true|false,
"businesses": [{
"business_id": "string",
"metered_phone_number": {string|null}
}]
}
BUSINESS_HIGHLIGHTS"BUSINESS_HIGHLIGHTS": {
"active_business_highlights": ["BH_1"],
"available_business_highlights": [
"BH_1",
"BH_2"
],
"mutually_exclusive_business_highlights": [
["BH_1", "BH_2"]
],
}
When using POST to setup/modify BH,
the format is:

"BUSINESS_HIGHLIGHTS": {
"business_highlights": ["BH_1", "BH_2"],
}
VERIFIED_LICENSE"VERIFIED_LICENSE": {
"licenses": [
{ "license_number": "some_license_1234" },
{ "license_number": "different_license" }
]
}
A POST request will append or edit a license indexed on license_number. DELETE must be used to remove licenses (cannot send empty license list)
CUSTOM_RADIUS_TARGETING"CUSTOM_RADIUS_TARGETING": {
"custom_radius": {float|null},
}
Radius in miles (1 to 60)
By default, radius is null which means this feature is inactive.
CUSTOM_AD_TEXT"CUSTOM_AD_TEXT": {
"custom_review_id": {string|null},
"custom_text": {string|null}
}
Only one of the two fields here can be set at a time.
By default, both are set to null, which means the ad text is set by Yelp.
CUSTOM_AD_PHOTO"CUSTOM_AD_PHOTO": {
"custom_photo_id": {string|null},
}
By default, this is set to null, which means the ad photo is set by Yelp.
BUSINESS_LOGO"BUSINESS_LOGO": {
"business_logo_url": {string|null}
}
URL set to null means this feature is inactive.
In POST, url must be publicly accessible image file of type: jpeg / png / gif / tiff
YELP_PORTFOLIO"YELP_PORTFOLIO": {
"projects": [
{
"project_id": {string},
"published": {boolean}
}, ...
]
}
POST will publish/unpublish a project created via Portfolio API. Body only needs to contain the project IDs to update

DELETE endpoint deletes all projects

Feature Type Parameters

The following section describes the configurable parameters in each request/response object for each supported feature type.

LINK_TRACKING

You can either define tracking URLs, which will replace the URLs on your Yelp business pages, or tracking parameters, which will be attached to the existing URLs. You can use link tracking for your website, Call to Action URLs and menu URLs.

ParameterTypeRequiredDescription
websitestring or nullYesTracking URL or parameter(s) for the website link
menustring or nullYesTracking URL or parameter(s) for the menu link
call_to_actionstring or nullYesTracking URL or parameter(s) for the CTA link

NEGATIVE_KEYWORD_TARGETING

ParameterTypeRequiredDescription
suggested_keywordslist of stringNoList of search terms for which your biz ad might be shown.
Please note: This list consists of up to 25 possible keywords where your ad may appear. Those suggestions are based on common searches associated with the business category. The 25 suggestions are not exhaustive, your ad may also appear on searches not shown in the list of suggestions.
blocked_keywordslist of stringYesList of currently blocked keywords. You can use this field to update the list of terms you would like to block.
Please note: You are allowed to add custom search terms outside of the suggested keywords list. Suggested keywords list is for guidance purposes.

STRICT_CATEGORY_TARGETING

ParameterTypeRequiredDescription
enabledboolYes

AD_SCHEDULING

ParameterTypeRequiredDescription
uses_opening_hoursboolYesShould the ad only be delivered while the business is open?

i.e. if {'uses_opening_hours': true } and the business's hours are 8-5pm, a 6pm search wouldn't be eligible for this ad.

CUSTOM_LOCATION_TARGETING

ParameterTypeRequiredDescription
businesseslist[object]YesList of all businesses that are part of the ad campaign.
businesses[].business_idstringYesBusiness ID
businesses[].locationslist[string]YesList of 0 up to 25 locations. These locations can be zip codes, cities, neighbourhoods, counties or state names but must be within the US.

AD_GOAL

ParameterTypeRequiredDescription
ad_goalstringYesMust be one of DEFAULT, CALLS, or WEBSITE_CLICKS

CALL_TRACKING

ParameterTypeRequiredDescription
enabledboolYesIndicates whether call tracking is enabled or disabled on a campaign level.
businesseslist[object]YesList of all businesses that are part of the ad campaign.
businesses[].business_idstringYesBusiness ID
businesses[].metered_phone_numberstring or nullYesPhone number which will be used as a call tracking number for the provided business in the ad campaign

BUSINESS_HIGHLIGHTS

Request typeParameterTypeRequiredRequired
GETactive_business_highlightslist[string]NoCurrently active business highlights enabled
GETavailable_business_highlightslist[string]NoValid business highlights available to select from
GETmutually_exclusive_business_highlightslist[list[string]]NoPairs of business highlights that can't be enabled together
POSTbusiness_highlightslist[string]YesList of desired business highlights to set

VERIFIED_LICENSE

ParameterTypeRequiredDescription
licenses[].license_numberstringYesLicense number provided by issuing agency/authority
licenses[].license_expiry_datestringNoLicense expiry date (format YYYY-MM-DD)
licenses[].license_tradestringNoBusiness or trade for which a license was issued
licenses[].license_issuing_agencystringNoAgency/authority that issued the license

CUSTOM_RADIUS_TARGETING

ParameterTypeRequiredDescription
custom_radiusfloatNoRadius in miles (1 to 60)
By default, custom_radius is null which means this feature is inactive.

CUSTOM_AD_TEXT

ParameterTypeRequiredDescription
custom_review_idstringNoIdentifier of the review from which to extract the text.
custom_textstringNoCustom text to be shown.

*Note: Only one field can be set
By default, this is set to null, which means the ad text is set by Yelp.

CUSTOM_AD_PHOTO

ParameterTypeRequiredDescription
custom_photo_idstringNoIdentifier of the photo to show on the custom ad.

BUSINESS_LOGO

ParameterTypeRequiredDescription
business_logo_urlstringNoURL to the business's brand logo if in use.
In POST, URL must be publicly accessible image file of type: jpeg / png / gif / tiff

YELP_PORTFOLIO

ParameterTypeRequiredDescription
projects[].project_idstringYesIdentifier of a project
projects[].publishedbooleanYesWhether the project is published

Portfolio API

The Yelp Portfolio API helps users manage their business portfolios.

EndpointObject FormatNotes
GET
/program/{program_id}/ portfolio/{project_id}/v1
{
"name": {string},
"call_to_action": {"WEBSITE"|...},
"description": {string},
"service_offerings":
[<so_1>, <so_2>,...
],
"cost": {string-enum|null},
"duration": {string-enum|null},
"completion_year": {int|null},
"completion_month": {int|null},
"published": {boolean|true},
"id": {string}
}
Fetch portfolio project details.

Up to four service offerings

Nullable fields are optional
PUT /program/{program_id}/ portfolio/{project_id}/v1{
"name": {string},
"call_to_action": {"WEBSITE"|...},
"description": {string},
"service_offerings":
[<so_1>, <so_2>,...
],
"cost": {string-enum|null},
"duration": {string-enum|null},
"completion_year": {int|null},
"completion_month": {int|null}
}
Update an existing project

Up to four service offerings
POST /program/{program_id}/ portfolio/v1No request payload

Returns
{
"project_id": {string}
}
Create a new project draft
DELETE /program/{program_id}/portfolio/ {project_id}/v1Delete a project
POST /program/{program_id}/portfolio/ {project_id}/photos/v1Request Payload
{
"photo_url": {string|null},
"biz_photo_id": {string|null}
"is_before_photo": {boolean},
"caption": {string},
}

Response Payload
{
"photo_id": {string}
}
or/and via Location header
For uploading photos
First uploaded photo will be the cover photo

is_before_photo adds a "before" label to the photo

Either provide an existing biz photo ID or link to URL
GET /program/{program_id}/portfolio/ {project_id}/photos/v1[
{
"id": {string},
"photo_url": {string},
"caption":{string|null},
"is_before_photo": {boolean},
"is_cover_photo": {boolean}
}
]
List photos belonging to the project
DELETE /program/{program_id}/portfolio/ {project_id}/photos/{photo_id}/v1Delete a photo from the project

For more information about each of the parameters, please refer to the Program Feature API Reference Page

πŸ“˜

Check out our Program Feature API Reference Page

:owlbert: Program Feature Endpoints