Vendasta Local SEO REST API
Local SEO (formerly Listing Builder) product API: listing sync listings, listing scores, listing profiles and citations for a business location. Scope-gated with the `listing` OAuth2 scope.
OpenAPI Specification
openapi: 3.0.0
info:
title: Local SEO REST APIs
version: '1.0'
description: Using this api requires active Local SEO
servers:
- url: 'https://prod.apigateway.co/products/listings'
description: Production
- url: 'https://demo.apigateway.co/products/listings'
description: Demo
- url: '{local}/products/listings'
description: Local
- url: 'http://localhost:11001/products/listings'
description: Localhost
tags:
- name: Listing Sync Listings
- name: Listing Scores
- name: Listing Profiles
- name: Citations
- name: Options
paths:
/listingSyncListings:
get:
tags:
- Listing Sync Listings
summary: List Listing Sync Listings
operationId: list-listingSyncListings
security:
- OAuth2Demo:
- listing
- OAuth2Prod:
- listing
x-lifecycle:
status: proposed
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Gets a list of listings for a listing profile. This corresponds to the Business Profile page in Local SEO.
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
in: query
name: 'filter[businessLocation.id]'
description: Return listings for the specified listing profile for the Vendasta's unique ID for the business
required: true
- schema:
type: string
in: query
name: 'page[cursor]'
description: 'The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
- schema:
type: string
in: query
name: 'page[limit]'
description: 'For now we only support a value of 200. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/listingSyncListings'
links:
type: object
properties:
self:
type: string
format: uri
first:
type: string
description: Provides a link back to the first page of results
format: uri
next:
type: string
description: The URI at which the next batch of reviews can be gotten from
format: uri
options:
operationId: options-listingSyncListings
summary: List valid HTTP verbs for /listingSyncListings
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
responses:
'204':
description: No Content
'403':
description: User Cannot Access Business Location
'404':
description: Business Not Found
'406':
description: No Listing Product Active
tags:
- Options
- Listing Sync Listings
parameters: []
'/listingScores/{id}':
get:
summary: Get Listing Score
tags:
- Listing Scores
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/listingScores'
operationId: get-listingScores
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Get the listing score information for a specific business
x-lifecycle:
status: proposed
security:
- OAuth2Demo:
- listing
- OAuth2Prod:
- listing
parameters:
- schema:
type: string
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
parameters:
- schema:
type: string
name: id
in: path
required: true
options:
summary: List valid HTTP verbs for /listingScores
operationId: options-listingScores-id
responses:
'200':
description: OK
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly.'
tags:
- Options
- Listing Scores
'/listingProfiles/{id}':
parameters:
- schema:
type: string
name: id
in: path
required: true
patch:
summary: Update Listing Profile
operationId: patch-listingProfiles-id
tags:
- Listing Profiles
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Update the existing listing profile.
Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.
x-lifecycle:
status: proposed
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
- schema:
type: string
default: application/vnd.api+json
enum:
- application/vnd.api+json
in: header
name: Content-Type
required: true
description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
security:
- OAuth2Demo:
- listing
- OAuth2Prod:
- listing
responses:
'200':
description: Ok
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/listingProfiles'
links:
type: object
properties:
self:
type: string
format: uri
description: The address of the updated listing profile
headers: {}
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/listingProfiles'
get:
summary: Get Listing Profile
tags:
- Listing Profiles
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/listingProfiles'
links:
type: object
properties:
self:
type: string
operationId: get-listingProfiles-id
x-lifecycle:
status: trustedTester
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Returns basic data about the listing profile.
parameters:
- schema:
type: string
example: Bearer <Access Token>
pattern: ^Bearer\s\S+
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
required: true
security:
- OAuth2Demo:
- listing
- OAuth2Prod:
- listing
/citations:
get:
summary: Get Citation Data
tags:
- Citations
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
$ref: '#/components/schemas/citations'
links:
type: object
properties:
self:
type: string
format: uri
first:
type: string
description: Provides a link back to the first page of results
format: uri
next:
type: string
description: The URI at which the next batch of citations can be fetched from
format: uri
operationId: get-citationData
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
Get the citation data information for a specific business. The citations that are returned are sorted by the `foundAt` property in descending order.
x-lifecycle:
status: proposed
security:
- OAuth2Demo:
- listing
- OAuth2Prod:
- listing
parameters:
- schema:
type: string
in: header
name: Authorization
description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
- schema:
type: string
in: query
name: 'filter[businessLocation.id]'
description: Return citations for the specified listing profile for Vendasta's unique ID for the business
- schema:
type: string
in: query
name: 'page[cursor]'
description: 'The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
- schema:
type: string
in: query
name: 'page[limit]'
description: '[Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).'
options:
operationId: options-citationData
summary: List valid HTTP verbs for /citations
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
responses:
'204':
description: No Content
'403':
description: User Cannot Access Citations
'404':
description: Business Not Found
'406':
description: No Listing Product Active
components:
securitySchemes:
JWT:
type: http
scheme: bearer
OAuth2Demo:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-demo.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-demo.apigateway.co/oauth2/token'
refreshUrl: ''
scopes:
listing: Access to the Local SEO REST API
OAuth2Prod:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-prod.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-prod.apigateway.co/oauth2/token'
refreshUrl: ''
scopes:
listing: Access to the Local SEO REST API
schemas:
listingSyncListings:
title: Listing Sync Listings
type: object
x-lifecycle:
status: proposed
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`
A list of listings for a business location
x-internal: false
properties:
id:
description: Public facing name of the source
type: string
type:
type: string
default: listingSyncListings
enum:
- listingSyncListings
attributes:
type: object
properties:
icon:
description: Link to icon provided by Vendasta’s media service
type: string
format: uri
example: 'https://www.cdnstyles.com/static/images/icon32/sourceId-10090.png'
popularity:
description: Popularity of the source relative to other sources
type: number
sourceTypeCode:
description: |-
The type of listing source.
unspecified - The listing source type is unknown
directory - An online listing directory
map - Sites that have an online map like MapQuest or Google Maps
social - Social networks like Facebook
aggregator - Publishers that push their listing information to other listing sources
app - Stand alone applications like Snapchat that are not GPS services
gps - These sources power GPS applications
type: string
syncStatusCode:
description: |-
The listing status provided by the listing sources.
unknown - Default error value, should never be used intentionally
synced - Listing data was submitted to the listing source, and the source responded that the data is good and in use
inProgress - Information has been sent to the listing source who is in the process of syncing the information to the listing.
syncingWithWarnings - The data has been updated by the listing but there are some warnings that many affect the values updated.
hasErrors - There was an error with the data we sent to the listing source causing updating all the information to fail.
syncDisabled - Updating information for this source has been disabled.
claimedByOthers - The listing source is rejecting our data because this listing has been claimed by another user/service.
doesNotSupportServiceAreaBusiness - This listing source does not support service area businesses.
submitted - The business profile information was successfully sent to the listing source. The listing source does not verify when the information was published.
manualUpdateOnly - This listing cannot be updated by Vendasta's platform with the current set of apps actived for this business. The listing must be updated with the listing source directly by the business.
notFound - The listing source does not have a listing for this business.
type: string
listingScore:
description: A score based on the status of your online source
type: number
maximumlistingScore:
description: The maximum score this source can attain
type: number
url:
description: The online listing
format: uri
type: string
syncingError:
type: array
description: Any errors stopping the business information from being updated by the listing source.
items:
type: object
properties:
errorCode:
description: |-
businessName
streetAddress
postalCode
city
wholeAddress - Error is not isolated to street address, city, etc.
phoneNumber
hoursOfOperation
categories
descriptionLong
descriptionShort
email
paymentOptions
photos
website
existingRelationship
chainLocation
unavailableReason - Superpages is unable to update this listing due to an issue with their database.
type: string
errorDetails:
description: Human readable details about the error
type: string
syncingWarning:
description: Any warnings reported while updating your information on the listing source.
type: array
items:
type: object
properties:
warningCode:
description: |-
businessName
streetAddress
postalCode
phoneNumber
wholeAddress - Error is not isolated to street address, city, etc.
hoursOfOperation
categories
descriptionLong
descriptionShort
email
photos
website
services
type: string
warningDetails:
description: Human readable details about the warning
type: string
updatedAt:
format: date
type: string
description: 'The last time this source’s listing was checked by Vendasta’s independent listing verification system. This will be `1970-01-01T00:00:00Z` if we have never verified the listing.'
streetAddress:
description: |-
Service area businesses will not have this field.
For a physical location this physical address of the business. Vendasta’s platform supports multiple address lines but currently those are combined into a single street address in our listing verification system.
type: object
properties:
Value:
description: The street address on the listing
type: string
Match:
description: Does the street address match the business’s street address in their Vendasta Business Profile
type: boolean
city:
description: |-
For a service area business this will be the city the business services.
For a physical location this will be the city that the business physically exists in.
type: object
properties:
value:
description: The city as it appears on the source listing
type: string
match:
description: Does the city match the business’s street address in their Vendasta Business Profile
type: boolean
region:
description: |-
For a service area business this will be the region that contains the city the business services.
For a physical location this will be the region that the business physically exists in.
Examples of regions are states, provinces, etc.
type: object
properties:
value:
description: The region as it appears on the source listing
type: string
match:
description: Does the region match the business’s street address in their Vendasta Business Profile
type: boolean
country:
description: |-
For a service area business this will be the country that contains the city the business services.
For a physical location this will be the country that the business physically exists in.
type: object
properties:
value:
description: The country as it appears on the source listing
type: string
match:
description: Does the country match the business’s street address in their Vendasta Business Profile
type: boolean
postalCode:
description: For a physical location this will be the postal code of the physical location of the business. In the USA this is the zip code
type: object
properties:
value:
description: The postal code as it appears on the source listing
type: string
match:
description: Does the postal code match the business’s street address in their Vendasta Business Profile
type: boolean
phoneNumber:
description: |-
The contact phone number for the business. This corresponds to the first phone number in the Vendasta business profile.
This will not be the toll free, cell or fax number.
type: object
properties:
value:
description: The phone number as it appears on the listing.
type: string
match:
description: 'Does the phone number match the business’s first phone number in their Vendasta Business Profile. Toll free, cell and fax numbers are not considered even if they are the only number on the business profile.'
type: boolean
website:
description: The website of the business location.
type: object
properties:
value:
description: The website as it appears on the online listing.
type: string
match:
description: Does the website match the business’s website in their Vendasta Business Profile
type: boolean
accuracyStatusCode:
description: |-
Indicates if Vendasta's independent accuracy reporting is available, found and whether or not it is active.
unknown - Default error value, should never be used intentionally
accurate - Listing was independently verified by Vendasta to be accurate
inaccurate - Vendasta found at least one inaccuracy with the listing
notAvailable - No Vendasta reporting is available for this source
notFound - No listing was found for this source by Vendasta.
type: string
x-tags:
- Listing Sync Listings
listingScores:
title: Listing Scores
type: object
properties:
id:
type: string
description: Vendasta's unique ID for the business
type:
type: string
default: listingScores
enum:
- listingScores
attributes:
type: object
properties:
totalScore:
type: integer
description: The business's current listing score including the score based on online citations
industryAverageNinetyFifth:
type: integer
description: The ninety fifth percentile listing score for businesses in the same industry
initialListingScore:
type: integer
description: The listing score of the business when Local SEO was first activated
x-lifecycle: proposed
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`
The listing score information for a business location
x-tags:
- Listing Scores
listingProfiles:
type: object
x-examples:
Example 1:
id: AG-1234567
type: listingProfiles
attributes:
customerIdentifier: customer 123
name: Fred's Fish
address:
line1: 109 8th Street E.
line2: Suite 23
city: string
postalCode: S7M 1R3
regionCode: CA-SK
countryCode: CA
phoneNumbers:
- +1 (306) 555-1234
serviceAreaBusiness: true
geoCoordinate:
latitude: -90
longitude: -180
hours:
- hoursTypeId: general
regularHours:
- openDay: wednesday
closeDay: wednesday
openTime: '09:45'
closeTime: '09:45'
specialHours:
- status: closed
startDate: '2019-08-24'
endDate: '2019-08-24'
openTime: '09:45'
closeTime: '09:45'
relationships:
businessPartner:
data:
type: partners
id: ABC
businessCategories:
data:
- type: businessCategories
id: 'active:diving:freediving'
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
A listing profile is the representation of a business location (or similar) used by the Local SEO product. It contains advanced fields used by listing sources. If the Local SEO product is active for the location the data will be shared to listing sources such as Google Maps.
properties:
id:
type: string
example: AG-1231232
description: An identifier for the record. Currently these will be the same as a platform/salesAccounts or platform/businessLocations id.
type:
type: string
enum:
- listingProfiles
default: listingProfiles
description: The data type of this record
attributes:
type: object
properties:
customerIdentifier:
type: string
description: 'A value assigned by the business partner to reference this business location. Customer ID is currently NOT enforced to be unique, and there may be negative side effects to having a duplicate and/or changing a customer ID, specifically around legacy SSO. Use caution when editing a customer ID.'
readOnly: true
name:
type: string
description: |-
The common name for this location.
Note: The pipe character (`|`) is not allowed.
address:
type: object
properties:
line1:
type: string
description: The primary information. Typically a street address
line2:
type: string
description: An additional line of information to add after the street address.
city:
type: string
postalCode:
type: string
description: The zip code or postal code component of an address.
regionCode:
type: string
example: 'CA-SK, US-FL, AG-08, AU-NSW'
pattern: '^[A-Z]{2}-[\w]{1,3}$'
minLength: 4
maxLength: 6
description: |-
The code for the top level subdivision within the country (state/province). For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)
Examples: CA-SK, US-FL, AG-08, AU-NSW
countryCode:
type: string
example: 'CA, US, AU'
minLength: 2
maxLength: 2
pattern: '^[A-Z]{2}$'
description: |-
The two letter country code. For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)
Examples: CA, US, AU
phoneNumbers:
type: array
description: |-
The standard phone numbers for the location.
Formatting characters may be included.
**Extensions**
It is recommended that extensions are included at the end of the number after an appropriate separator: Pause: `,` Wait: `;` Default: `ext.`
You may test the parsibility of a number using https://phonenumbers.temba.io/ All phone numbers are assumed to be in the same country as this listing profile
items:
type: string
serviceAreaBusiness:
type: boolean
description: When true the address will be used as the center of the area that this location services instead of being displayed
geoCoordinate:
type: object
description: |-
The point where the map pin for the location should be displayed.
The values will **not** be automatically updated when the address is updated. If not provided when creating the location they will be initialized based on the address.
It is expressed as a pair of numbers to represent degrees latitude and degrees longitude in accordance with the [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) standard (the one used by your GPS).
required:
- latitude
- longitude
properties:
latitude:
type: number
longitude:
type: number
hours:
$ref: '#/components/schemas/hoursOfOperation'
ico:
type: number
x-stoplight:
id: ccum95lf9wwqb
description: Identifier for a business in the Czech republic. Can only be set for Czech businesses
relationships:
type: object
properties:
businessPartner:
type: object
description: A link to the organization that provides the platform to this listing profile
required:
- data
properties:
data:
type: object
required:
- type
- id
properties:
type:
type: string
id:
type: string
businessCategories:
type: object
description: A list of the types of business this location should be compared against. The first item on the list will be considered as the primary category. If not set during creation it will default "other".
properties:
data:
type: array
items:
type: object
required:
- type
- id
properties:
type:
type: string
id:
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vendasta/refs/heads/main/openapi/vendasta-local-seo-openapi.yml