Prospecting: Create Prospect Scan
Creates a prospect scan for a known Google Business Profile.
The service assigns the scan's resource name and begins processing. A successful response normally has PENDING or RUNNING state; it does not imply that results are available.
For a Google Business Profile target, the caller supplies only the CID. The server resolves the profile, including the business identity and location, and derives the search keyword from the profile's primary category.
Only one prospect scan may be created for the same Google Business Profile CID in an account within a 60-minute period. Additional create requests during that period return ALREADY_EXISTS. The status includes a google.rpc.ResourceInfo detail with resource_type "api.yextapis.com/ProspectScan" and resource_name set to the existing scan's full resource name.
Possible errors include:
- INVALID_ARGUMENT when the CID is malformed.
- ALREADY_EXISTS when a scan was created for the same CID in the account within the previous 60 minutes.
- NOT_FOUND when the CID does not resolve to an accessible profile.
- FAILED_PRECONDITION when the resolved profile lacks information required to run the scan, such as a usable primary category or location.
- RESOURCE_EXHAUSTED when an account or service quota is exceeded.
path Parameters
| account required | string |
Request Body schema: application/json
The prospect scan to create.
Set target to identify the business to scan. The remaining fields are assigned by the service.
required | object Selects the business that a prospect scan assesses. The initial API accepts a Google Business Profile. Additional target types may be supported in the future, so clients should tolerate variants they do not recognize. Exactly one target must be set. |
object Public business profile information for a prospect. | |
| state | string Enum: "PROSPECT_SCAN_STATE_PENDING" "PROSPECT_SCAN_STATE_RUNNING" "PROSPECT_SCAN_STATE_SUCCEEDED" "PROSPECT_SCAN_STATE_FAILED" The lifecycle state of a prospect scan.
|
Responses
Request samples
- Payload
{- "target": {
- "googleBusinessProfileCid": "string",
- "countryCode": "string",
- "languageCode": "string"
}, - "prospect": {
- "address": { },
- "location": { }
}, - "state": "PROSPECT_SCAN_STATE_PENDING"
}Response samples
- 200
- default
{- "name": "string",
- "target": {
- "googleBusinessProfileCid": "string",
- "countryCode": "string",
- "languageCode": "string"
}, - "prospect": {
- "googleBusinessProfileCid": "string",
- "businessName": "string",
- "address": {
- "countryCode": "string",
- "postalCode": "string",
- "administrativeArea": "string",
- "locality": "string",
- "dependentLocality": "string",
- "addressLines": [
- "string"
]
}, - "location": {
- "latitude": 0,
- "longitude": 0
}, - "websiteUri": "string",
- "phoneNumber": "string",
- "primaryCategory": "string",
- "secondaryCategories": [
- "string"
]
}, - "searchKeyword": "string",
- "state": "PROSPECT_SCAN_STATE_PENDING",
- "createTime": "2019-08-24T14:15:22Z",
- "updateTime": "2019-08-24T14:15:22Z"
}Prospecting: Get Prospect Scan
Gets the current state and metadata of a prospect scan.
Returns NOT_FOUND when the scan does not exist or is not accessible.
path Parameters
| account required | string |
| prospectScan required | string |
Responses
Response samples
- 200
- default
{- "name": "string",
- "target": {
- "googleBusinessProfileCid": "string",
- "countryCode": "string",
- "languageCode": "string"
}, - "prospect": {
- "googleBusinessProfileCid": "string",
- "businessName": "string",
- "address": {
- "countryCode": "string",
- "postalCode": "string",
- "administrativeArea": "string",
- "locality": "string",
- "dependentLocality": "string",
- "addressLines": [
- "string"
]
}, - "location": {
- "latitude": 0,
- "longitude": 0
}, - "websiteUri": "string",
- "phoneNumber": "string",
- "primaryCategory": "string",
- "secondaryCategories": [
- "string"
]
}, - "searchKeyword": "string",
- "state": "PROSPECT_SCAN_STATE_PENDING",
- "createTime": "2019-08-24T14:15:22Z",
- "updateTime": "2019-08-24T14:15:22Z"
}Prospecting: Fetch Discovered Prospects
Fetches competitors discovered in local search results for a completed scan.
Use this method to build a business-centric list of the competitors found by the scan. Each discovered prospect includes its observed search rank, available business profile details, and calculated metrics. The scan target is not included. To inspect the search results and other source material used to produce this result set, use FetchProspectScanEvidence.
Returns FAILED_PRECONDITION while the scan is not in SUCCEEDED state. Returns NOT_FOUND when the scan does not exist or is not accessible.
path Parameters
| account required | string |
| prospectScan required | string |
Responses
Response samples
- 200
- default
{- "discoveredProspects": [
- {
- "prospect": {
- "googleBusinessProfileCid": "string",
- "businessName": "string",
- "address": {
- "countryCode": "string",
- "postalCode": "string",
- "administrativeArea": "string",
- "locality": "string",
- "dependentLocality": "string",
- "addressLines": [
- "string"
]
}, - "location": {
- "latitude": 0,
- "longitude": 0
}, - "websiteUri": "string",
- "phoneNumber": "string",
- "primaryCategory": "string",
- "secondaryCategories": [
- "string"
]
}, - "searchRank": 0,
- "metrics": [
- {
- "metric": "METRIC_SEARCH_RANK",
- "value": 0
}
]
}
]
}Prospecting: Fetch Prospect Scan Evidence
Fetches supporting evidence collected for a completed prospect scan.
Use this method to inspect the source material used to produce the scan's summarized results and discovered prospects. Evidence is source-centric and includes search results, AI answers and citations, and publisher listing checks. To retrieve a business-centric list of competitors, use FetchDiscoveredProspects.
Returns FAILED_PRECONDITION while the scan is not in SUCCEEDED state. Returns NOT_FOUND when the scan does not exist or is not accessible.
path Parameters
| account required | string |
| prospectScan required | string |
Responses
Response samples
- 200
- default
{- "evidence": [
- {
- "observedTime": "2019-08-24T14:15:22Z",
- "search": {
- "keyword": "string",
- "searchEngine": "SEARCH_ENGINE_GOOGLE",
- "results": [
- {
- "rank": 0,
- "title": "string",
- "uri": "string",
- "matchedProspect": {
- "googleBusinessProfileCid": "string",
- "businessName": "string",
- "address": {
- "countryCode": "string",
- "postalCode": "string",
- "administrativeArea": "string",
- "locality": "string",
- "dependentLocality": "string",
- "addressLines": [
- "string"
]
}, - "location": {
- "latitude": 0,
- "longitude": 0
}, - "websiteUri": "string",
- "phoneNumber": "string",
- "primaryCategory": "string",
- "secondaryCategories": [
- "string"
]
}, - "displayAddress": "string"
}
]
}, - "ai": {
- "experience": {
- "id": "string",
- "displayName": "string",
- "modelVersion": "string"
}, - "prompt": "string",
- "answer": "string",
- "mentions": [
- {
- "businessName": "string",
- "rank": 0
}
], - "citations": [
- {
- "uri": "string",
- "title": "string"
}
]
}, - "listings": {
- "prospect": {
- "googleBusinessProfileCid": "string",
- "businessName": "string",
- "address": {
- "countryCode": "string",
- "postalCode": "string",
- "administrativeArea": "string",
- "locality": "string",
- "dependentLocality": "string",
- "addressLines": [
- "string"
]
}, - "location": {
- "latitude": 0,
- "longitude": 0
}, - "websiteUri": "string",
- "phoneNumber": "string",
- "primaryCategory": "string",
- "secondaryCategories": [
- "string"
]
}, - "results": [
- {
- "publisher": "string",
- "listingUri": "string",
- "status": "LISTING_STATUS_MATCHED",
- "publisherId": "string"
}
]
}
}
]
}Prospecting: Fetch Prospect Scan Results
Fetches the summarized results of a completed prospect scan.
Returns FAILED_PRECONDITION while the scan is not in SUCCEEDED state. Returns NOT_FOUND when the scan does not exist or is not accessible.
path Parameters
| account required | string |
| prospectScan required | string |
Responses
Response samples
- 200
- default
{- "prospect": {
- "googleBusinessProfileCid": "string",
- "businessName": "string",
- "address": {
- "countryCode": "string",
- "postalCode": "string",
- "administrativeArea": "string",
- "locality": "string",
- "dependentLocality": "string",
- "addressLines": [
- "string"
]
}, - "location": {
- "latitude": 0,
- "longitude": 0
}, - "websiteUri": "string",
- "phoneNumber": "string",
- "primaryCategory": "string",
- "secondaryCategories": [
- "string"
]
}, - "performance": {
- "googleRank": 0,
- "aiPerformance": [
- {
- "experience": {
- "id": "string",
- "displayName": "string",
- "modelVersion": "string"
}, - "rank": 0,
- "visibilityPercent": 0,
- "sentiment": {
- "positivePercent": 0,
- "negativePercent": 0,
- "neutralPercent": 0
}
}
], - "listingsAccuracyPercent": 0,
- "listingsVisibilityPercent": 0
}, - "comparisons": [
- {
- "metric": "METRIC_SEARCH_RANK",
- "prospectValue": 0,
- "benchmarkValue": 0
}
], - "aiRankings": [
- {
- "experience": {
- "id": "string",
- "displayName": "string",
- "modelVersion": "string"
}, - "prospectRank": 0,
- "competitors": [
- {
- "rank": 0,
- "businessName": "string"
}
]
}
], - "generatedTime": "2019-08-24T14:15:22Z"
}