MapsData

Search the Google Maps business categories MapsData can scrape. CALL THIS FIRST, before mapsdata_start_scrape: a scrape's query must be one of these exact categories, and a free-text guess like 'plumbing companies' is rejected.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Substring to search for, e.g. 'plumb'."
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ]
}

List the exact region names a scrape accepts for a country. Submit them verbatim. Abbreviations like 'TX' are rejected, because the postal tables key on the full name.

{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "au",
        "ca",
        "uk",
        "us"
      ],
      "default": "us"
    }
  }
}

Start scraping Google Maps businesses and their emails. Returns IMMEDIATELY with a job id; the scrape itself takes 5 minutes to several hours. Before calling this, confirm the category with mapsdata_search_categories and the region with mapsdata_list_regions. Those two mistakes are the overwhelming majority of rejections. This consumes the user's monthly lead allowance. Set dry_run to check a request against every rule without spending anything.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "An exact Google Maps category, e.g. 'Plumber'. Verify it with mapsdata_search_categories first."
    },
    "states": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Full region names, e.g. ['Texas']. Not abbreviations. Use this or cities, not both."
    },
    "cities": {
      "type": "array",
      "description": "Named cities instead of whole regions.",
      "items": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "description": "Full region name."
          }
        },
        "required": [
          "city",
          "state"
        ]
      }
    },
    "total_limit": {
      "type": "integer",
      "minimum": 1,
      "description": "Rows to scrape. Read max_rows_this_scrape from mapsdata_get_usage first: a larger request is reduced to the allowance left this cycle, not rejected."
    },
    "country": {
      "type": "string",
      "enum": [
        "au",
        "ca",
        "uk",
        "us"
      ],
      "default": "us"
    },
    "list_name": {
      "type": "string",
      "description": "Label for the list. Defaults to the query."
    },
    "dry_run": {
      "type": "boolean",
      "default": false,
      "description": "Validate against every rule and return the plan WITHOUT starting a scrape or spending quota."
    }
  },
  "required": [
    "query",
    "total_limit"
  ]
}

Get the current state of one scrape. This is an INSTANT SNAPSHOT of a job that runs for minutes to hours. Do NOT call it repeatedly in a loop. The response includes next_action, the suggested next step for the job's current status. MapsData also emails the user when a scrape finishes.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    }
  },
  "required": [
    "job_id"
  ]
}

List this workspace's recent scrapes, newest first.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "cancelling",
        "cancelled",
        "completed",
        "failed"
      ]
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 25
    }
  }
}

Cancel a queued or running scrape. A queued scrape costs nothing. CANCELLING A RUNNING SCRAPE STILL BILLS the leads already delivered, so confirm with the user before calling this.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    }
  },
  "required": [
    "job_id"
  ]
}

Get a link to a finished scrape's results. The link expires in 15 minutes, so hand it to the user promptly rather than storing it.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    },
    "format": {
      "type": "string",
      "enum": [
        "csv",
        "xlsx"
      ],
      "default": "csv"
    },
    "scope": {
      "type": "string",
      "enum": [
        "emails",
        "all",
        "filtered"
      ],
      "default": "emails",
      "description": "'emails' is rows with a deliverable email, which is what usage is billed on. 'all' is every scraped row."
    }
  },
  "required": [
    "job_id"
  ]
}

How much of this month's lead allowance is left, and the largest single scrape this plan allows. Read max_rows_this_scrape before choosing a total_limit.

{
  "type": "object",
  "properties": {}
}