API Methods

Keyword Scan

POST
https://app.persuaded.io/api/keywords/scans/

Required query parameters

  • api_key - The API key associated with your user account.
Required JSON body keys
  • keyword - The term or phrase to use when searching.
  • lat - Latitude of the grid center point.
  • lng - Longitude of the grid center point.
Optional JSON body keys
  • dimensions - Indicates length of one side of a square search grid (i.e. 4 = 16 search pins). Default value is 4.
  • distance - Distance in meters between each pin of the search grid. Default value is 1000.
  • spam_scan - Check addresses for residential, vacant, or virtual office status. Default value is false.
Example JSON request body
{ "keyword": "garage door repair", "lat": 35.8984, "lng": -78.7725, "dimensions": 4, "distance": 1000, "spam_scan": true }

The response will contain a ID that can be used to poll for results while the scan is running. The ref_id value refers to the keyword ID and can be used to retrieve results once the task is completed. The example at the bottom of the page demonstrates the complete flow of requesting a scan, polling, and fetching results.

Example JSON response
{"capture_date": "2020-12-24 15:12:27.360329", "end_date": null, "id": 93, "name": "KEYWORD_SCAN", "next_id": null, "queued_date": "2020-12-24T15:12:27.360329", "ref_id": 21, "ref_type": "keyword", "start_date": null, "status": "NOT_STARTED"}
Pricing

Scans are billed at $0.02 per point. Spam checks are billed at $0.02 per address, but are only performed when requested, by including the spam_scan key in the JSON request body.

Error codes
  • 400 - Request missing required data. Response JSON will describe the error.
  • 402 - Insufficient account balance to start the scan.
  • 503 - Service is temporarily down for maintenance or upgrades.

Task Polling

GET
https://app.persuaded.io/api/task/task_id/

Required path parameters

  • task_id - The ID of the task to fetch.
Required query parameters
  • api_key - The API key associated with your user account.

Example JSON response
{"capture_date": "2020-12-24 15:12:27.360329", "end_date": null, "id": 93, "name": "KEYWORD_SCAN", "next_id": null, "queued_date": "2020-12-24T15:12:27.360329", "ref_id": 21, "ref_type": "keyword", "start_date": null, "status": "NOT_STARTED"}
Tasks begin as NOT_STARTED when queued, transition to RUNNING, and finally move to COMPLETE. The next_id value represents the ID of the next task if the process involves multiple tasks.

Retrieving Results

GET
https://app.persuaded.io/api/keywords/keyword_id/results/

Required path parameters

  • keyword_id - The ID of the keyword scan, or the task ref_id.
Required query parameters
  • api_key - The API key associated with your user account.

Example JSON response
[{"address": "300 Dominion Dr Suite 201, Morrisville, NC 27560", "categories": ["Garage door supplier"], "cid": "https://www.google.com/maps?cid=17174845768764410897", "claimed": true, "google_rating": 4.7, "google_reviews": 307, "name": "Precision Garage Door Service", "phone_number": "(919) 500-5160", "visibility_rank": 1, "website": "https://precisiondoortriangle.com/?utm_source=GMBListing&utm_medium=organic", "website_title": "\t\tPrecision Garage Door Raleigh | Repair, Openers & New " "Garage Doors\t"}, {"address": "4809 Hargrove Rd #117, Raleigh, NC 27616", "categories": ["Garage builder", "Garage door supplier"], "cid": "https://www.google.com/maps?cid=5254056723730444400", "claimed": true, "google_rating": 5.0, "google_reviews": 55, "name": "Hanson Overhead Garage Door Service", "phone_number": "(919) 829-0940", "visibility_rank": 2, "website": "http://www.hansonraleigh.com/", "website_title": "Raleigh Garage Repair | Raleigh Garage Doors and Openers | " "Hanson Overhead Garage Door Service"}]

An Example of Scanning, Polling, and Retrieving Results

Checking GMB Names in Bulk

POST
https://app.persuaded.io/api/locations/names/

Required query parameters

  • api_key - The API key associated with your user account.

Example JSON request body
[ "https://www.google.com/maps?cid=13693390095071552444", "https://www.google.com/maps?cid=10363473652864890526", "https://www.google.com/maps?cid=1383562434814721243" ]
Example JSON response
[ "Jamacha Point Self Storage", "A-1 Self Storage", "Extra Space Storage" ]
Pricing

Name checks are billed at $0.005 per name.

Error codes
  • 400 - Request missing required data. Response JSON will describe the error.
  • 402 - Insufficient account balance to start the scan.
  • 503 - Service is temporarily down for maintenance or upgrades.