google-maps-scraper-sdk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6db571d98b81c21e14ffeaec282c78869ed47d73c96146dce26bfb57c9a283b
+  data.tar.gz: 072c115cbcd6fe6666b6d04c22c03be038145612d53773f2058bad776e6d226a
+SHA512:
+  metadata.gz: 208386cbbf47b5dc9afd319b5ddcfa9304772def7b4a3d5169bb9029fee378e137c827b4e0263722a942f0e480196f5e88702955107f570a910cfcc1bec6ba19
+  data.tar.gz: c9516bfef13d8bf73e83571989f9a35f4995e79716c2bc0c516aff347769df77ffb3cfeb5e7178dc521d53722fc462959113074df3199287147d28d18ad6201e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GMaps Lead Finder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# Google Maps Scraper
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/google-maps-lead-scraper/google-maps-scraper/main/google-maps-scraper.png" alt="Google Maps Lead Scraper" width="100%" />
+</p>
+
+**Google Maps Extractor · Google Maps Lead Scraper · Google Maps Lead Extractor**
+
+Ruby SDK to scrape Google Maps places and export leads (name, phone, website, emails, and more) through a hosted Agent HTTP API. Powered by [GMaps Lead Finder](https://gmapsleadfinder.com). This is **not** a local browser crawler — jobs run in the cloud scrape-and-enrich pipeline.
+
+- **RubyGems:** [`google-maps-scraper-sdk`](https://rubygems.org/gems/google-maps-scraper-sdk)
+- **Require:** `gmaps_scraper` → `GmapsScraper::Client`
+- **CLI:** `gmaps-scraper`
+
+## Get an API key
+
+1. Sign in at [gmapsleadfinder.com](https://gmapsleadfinder.com).
+2. Use a plan with Agent API (**Growth** or higher) — see [Pricing](https://gmapsleadfinder.com/pricing).
+3. Open [Account → API key](https://gmapsleadfinder.com/account#api-key) and copy your `gmf_…` key.
+
+```bash
+export GMF_API_KEY=gmf_your_key_here
+```
+
+## Install
+
+```bash
+gem install google-maps-scraper-sdk
+# or: bundle add google-maps-scraper-sdk
+```
+
+Requires **Ruby 3.1+** (stdlib `net/http` + `json` only).
+
+## Quickstart
+
+```ruby
+require "gmaps_scraper"
+
+client = GmapsScraper::Client.new # reads GMF_API_KEY
+me = client.me
+puts "#{me['plan']} #{me['creditsRemaining']}"
+
+rows = client.scrape("dentists in Austin TX")
+puts rows.length
+```
+
+CLI:
+
+```bash
+gmaps-scraper me
+gmaps-scraper scrape "dentists in Austin TX" --out leads.json
+```
+
+From this directory:
+
+```bash
+bundle install
+bundle exec ruby examples/quickstart.rb
+bundle exec gmaps-scraper me
+```
+
+## Client API
+
+| Method | Description |
+|--------|-------------|
+| `Client.new(api_key:, base_url:, timeout_s:)` | From env / kwargs |
+| `me` | Plan & credits |
+| `create_job(keyword)` | Queue one-keyword job |
+| `get_job(job_id)` | Poll status |
+| `get_results(job_id, limit:, cursor:)` | Paginated rows |
+| `scrape(keyword, poll_interval_ms:, timeout_ms:, result_limit:)` | Create → poll → all rows |
+
+`scrape` defaults: `poll_interval_ms` 2000, `timeout_ms` 600000, `result_limit` 100.
+
+## Errors
+
+| HTTP | Class |
+|------|-------|
+| 400 | `GmapsScraper::BadRequestError` |
+| 401 | `GmapsScraper::AuthenticationError` |
+| 402 | `GmapsScraper::InsufficientCreditsError` |
+| 403 | `GmapsScraper::PlanNotAllowedError` |
+| 404 | `GmapsScraper::NotFoundError` |
+| 409 | `GmapsScraper::JobConflictError` |
+| — | `GmapsScraper::TimeoutError`, `GmapsScraper::ApiError` |
+
+## Limits
+
+- Exactly one keyword per API job
+- One running job per user (`409` if busy)
+- 1 credit = 1 place row; Growth+ required
+
+## Publish to RubyGems
+
+```bash
+cd ruby
+gem build google-maps-scraper-sdk.gemspec
+gem push google-maps-scraper-sdk-0.1.1.gem
+```
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| Website | https://gmapsleadfinder.com |
+| HTTP API | https://gmapsleadfinder.com/docs/api |
+| RubyGems | https://rubygems.org/gems/google-maps-scraper-sdk |
+| Monorepo | https://github.com/google-maps-lead-scraper/google-maps-scraper |
+
+## License
+
+MIT

data/examples/quickstart.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "gmaps_scraper"
+
+client = GmapsScraper::Client.new
+me = client.me
+puts "plan=#{me['plan']} creditsRemaining=#{me['creditsRemaining']}"
+
+rows = client.scrape("dentists in Austin TX")
+puts "scraped #{rows.length} places"
+unless rows.empty?
+  r = rows.first
+  puts "#{r['Name']} #{r['Phone']} #{r['Website']} #{r['Emails']}"
+end

data/exe/gmaps-scraper

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+require "optparse"
+require "pathname"
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "gmaps_scraper"
+
+def write_output(rows, out)
+  if out.nil?
+    puts JSON.pretty_generate(rows)
+    return
+  end
+
+  path = Pathname.new(out)
+  path.dirname.mkpath
+  suffix = path.extname.downcase
+  if suffix == ".csv"
+    fieldnames = []
+    seen = {}
+    rows.each do |row|
+      row.each_key do |key|
+        next if seen[key]
+
+        seen[key] = true
+        fieldnames << key
+      end
+    end
+    fieldnames = ["Name"] if fieldnames.empty?
+    CSV.open(path, "w") do |csv|
+      csv << fieldnames
+      rows.each do |row|
+        csv << fieldnames.map { |k| row[k] || "" }
+      end
+    end
+  else
+    path.write("#{JSON.pretty_generate(rows)}\n")
+  end
+  warn "Wrote #{rows.length} rows to #{path}"
+end
+
+def print_help
+  puts <<~HELP
+    Usage: gmaps-scraper <command> [options]
+
+    Commands:
+      me                          Show plan and credits
+      scrape "<keyword>" [opts]   Scrape one keyword and print/save rows
+
+    Options for scrape:
+      --out PATH                  Output path (.json or .csv). Default: JSON to stdout
+      --poll-interval-ms MS       Job poll interval (default: 2000)
+      --timeout-ms MS             Max wait for job completion (default: 600000)
+
+    Global:
+      --version                   Print version
+      -h, --help                  Show this help
+  HELP
+end
+
+argv = ARGV.dup
+if argv.empty? || argv.include?("-h") || argv.include?("--help")
+  print_help
+  exit(argv.empty? ? 1 : 0)
+end
+if argv.include?("--version")
+  puts GmapsScraper::VERSION
+  exit 0
+end
+
+cmd = argv.shift
+begin
+  case cmd
+  when "me"
+    client = GmapsScraper::Client.new
+    puts JSON.pretty_generate(client.me)
+  when "scrape"
+    out = nil
+    poll_interval_ms = GmapsScraper::Client::DEFAULT_POLL_INTERVAL_MS
+    timeout_ms = GmapsScraper::Client::DEFAULT_TIMEOUT_MS
+    keyword = nil
+
+    OptionParser.new do |opts|
+      opts.on("--out PATH") { |v| out = v }
+      opts.on("--poll-interval-ms MS", Integer) { |v| poll_interval_ms = v }
+      opts.on("--timeout-ms MS", Integer) { |v| timeout_ms = v }
+    end.parse!(argv)
+
+    keyword = argv.shift
+    raise ArgumentError, "keyword is required" if keyword.nil? || keyword.strip.empty?
+
+    client = GmapsScraper::Client.new
+    rows = client.scrape(
+      keyword,
+      poll_interval_ms: poll_interval_ms,
+      timeout_ms: timeout_ms
+    )
+    write_output(rows, out)
+  else
+    raise ArgumentError, "unknown command #{cmd}"
+  end
+rescue GmapsScraper::ApiError => e
+  warn "error: #{e.message}"
+  warn "status: #{e.status_code}" if e.status_code
+  exit 1
+rescue ArgumentError => e
+  warn "error: #{e.message}"
+  exit 1
+end

data/google-maps-scraper-sdk.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/gmaps_scraper/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "google-maps-scraper-sdk"
+  spec.version = GmapsScraper::VERSION
+  spec.authors = ["GMaps Lead Finder"]
+  spec.email = ["support@gmapsleadfinder.com"]
+
+  spec.summary = "Google Maps Scraper / Extractor / Lead Scraper SDK for GMaps Lead Finder"
+  spec.description =
+    "Official Ruby client for the GMaps Lead Finder Agent HTTP API — scrape Google Maps " \
+    "places (name, phone, website, emails) via a hosted cloud pipeline."
+  spec.homepage = "https://gmapsleadfinder.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] =
+    "https://github.com/google-maps-lead-scraper/google-maps-scraper/tree/main/ruby"
+  spec.metadata["changelog_uri"] =
+    "https://github.com/google-maps-lead-scraper/google-maps-scraper/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://gmapsleadfinder.com/docs/api"
+  spec.metadata["bug_tracker_uri"] =
+    "https://github.com/google-maps-lead-scraper/google-maps-scraper/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "lib/**/*",
+      "exe/*",
+      "examples/**/*",
+      "README.md",
+      "LICENSE",
+      "google-maps-scraper-sdk.gemspec"
+    ].select { |f| File.file?(f) }
+  end
+  spec.bindir = "exe"
+  spec.executables = ["gmaps-scraper"]
+  spec.require_paths = ["lib"]
+end

data/lib/gmaps_scraper/client.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module GmapsScraper
+  class Client
+    DEFAULT_BASE_URL = "https://gmapsleadfinder.com"
+    DEFAULT_POLL_INTERVAL_MS = 2000
+    DEFAULT_TIMEOUT_MS = 600_000
+    DEFAULT_RESULT_LIMIT = 100
+    DEFAULT_HTTP_TIMEOUT_S = 60.0
+    USER_AGENT = "gmaps-scraper-ruby/#{VERSION}"
+    TERMINAL_STATUSES = %w[completed partial failed].freeze
+
+    def initialize(api_key: nil, base_url: nil, timeout_s: DEFAULT_HTTP_TIMEOUT_S)
+      key = (api_key || ENV["GMF_API_KEY"]).to_s.strip
+      if key.empty?
+        raise AuthenticationError,
+              "Missing API key. Set GMF_API_KEY or pass api_key: " \
+              "(https://gmapsleadfinder.com/account#api-key)"
+      end
+
+      @api_key = key
+      @base_url = (base_url || ENV["GMF_BASE_URL"] || DEFAULT_BASE_URL).to_s.strip.gsub(%r{/+\z}, "")
+      @timeout_s = timeout_s
+    end
+
+    def me
+      request("GET", "/api/v1/me")
+    end
+
+    def create_job(keyword)
+      trimmed = keyword.to_s.strip
+      raise BadRequestError, "keyword is required" if trimmed.empty?
+
+      request("POST", "/api/v1/jobs", json_body: { "keyword" => trimmed })
+    end
+
+    def get_job(job_id)
+      request("GET", "/api/v1/jobs/#{job_id}")
+    end
+
+    def get_results(job_id, limit: DEFAULT_RESULT_LIMIT, cursor: nil)
+      query = { "limit" => limit.to_s }
+      query["cursor"] = cursor.to_s unless cursor.nil?
+      request("GET", "/api/v1/jobs/#{job_id}/results", query: query)
+    end
+
+    def scrape(
+      keyword,
+      poll_interval_ms: DEFAULT_POLL_INTERVAL_MS,
+      timeout_ms: DEFAULT_TIMEOUT_MS,
+      result_limit: DEFAULT_RESULT_LIMIT
+    )
+      created = create_job(keyword)
+      job_id = created["jobId"].to_s
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + (timeout_ms / 1000.0)
+      poll_s = [poll_interval_ms, 100].max / 1000.0
+
+      loop do
+        job = get_job(job_id)
+        status = job["status"].to_s.downcase
+        if TERMINAL_STATUSES.include?(status)
+          if status == "failed"
+            raise ApiError.new(job["error"] || "Job #{job_id} failed", body: job)
+          end
+          break
+        end
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          raise TimeoutError,
+                "Timed out after #{timeout_ms}ms waiting for job #{job_id} " \
+                "(last status=#{job['status'].inspect})"
+        end
+        sleep(poll_s)
+      end
+
+      fetch_all_rows(job_id, result_limit: result_limit)
+    end
+
+    private
+
+    def fetch_all_rows(job_id, result_limit:)
+      rows = []
+      cursor = "0"
+      while cursor
+        page = get_results(job_id, limit: result_limit, cursor: cursor)
+        rows.concat(Array(page["rows"]))
+        next_cursor = page["nextCursor"]
+        cursor = next_cursor.nil? || next_cursor == "" ? nil : next_cursor.to_s
+      end
+      rows
+    end
+
+    def request(method, path, json_body: nil, query: nil)
+      uri = URI("#{@base_url}#{path}")
+      if query && !query.empty?
+        uri.query = URI.encode_www_form(query)
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout_s
+      http.read_timeout = @timeout_s
+
+      klass = case method.upcase
+              when "GET" then Net::HTTP::Get
+              when "POST" then Net::HTTP::Post
+              when "PUT" then Net::HTTP::Put
+              when "DELETE" then Net::HTTP::Delete
+              else
+                raise ApiError, "Unsupported HTTP method #{method}"
+              end
+
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = USER_AGENT
+      if json_body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(json_body)
+      end
+
+      begin
+        res = http.request(req)
+      rescue StandardError => e
+        raise ApiError, "Network error: #{e.message}"
+      end
+
+      body = parse_body(res.body)
+      code = res.code.to_i
+      raise_for_status(code, body) if code < 200 || code >= 300
+      body.is_a?(Hash) ? body : {}
+    end
+
+    def parse_body(raw)
+      return {} if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      { "message" => raw }
+    end
+
+    def raise_for_status(status, body)
+      message = "API request failed with status #{status}"
+      if body.is_a?(Hash)
+        %w[message error statusMessage].each do |key|
+          val = body[key]
+          if val.is_a?(String) && !val.empty?
+            message = val
+            break
+          end
+        end
+      end
+
+      klass = case status
+              when 400 then BadRequestError
+              when 401 then AuthenticationError
+              when 402 then InsufficientCreditsError
+              when 403 then PlanNotAllowedError
+              when 404 then NotFoundError
+              when 409 then JobConflictError
+              else ApiError
+              end
+      raise klass.new(message, status_code: status, body: body)
+    end
+  end
+end

data/lib/gmaps_scraper/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GmapsScraper
+  class ApiError < StandardError
+    attr_reader :status_code, :body
+
+    def initialize(message, status_code: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @body = body
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  class PlanNotAllowedError < ApiError; end
+  class InsufficientCreditsError < ApiError; end
+  class JobConflictError < ApiError; end
+  class NotFoundError < ApiError; end
+  class BadRequestError < ApiError; end
+  class TimeoutError < ApiError; end
+end

data/lib/gmaps_scraper/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GmapsScraper
+  VERSION = "0.1.1"
+end

data/lib/gmaps_scraper.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "gmaps_scraper/version"
+require_relative "gmaps_scraper/errors"
+require_relative "gmaps_scraper/client"
+
+module GmapsScraper
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: google-maps-scraper-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- GMaps Lead Finder
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-09-16 00:00:00.000000000 Z
+dependencies: []
+description: Official Ruby client for the GMaps Lead Finder Agent HTTP API — scrape
+  Google Maps places (name, phone, website, emails) via a hosted cloud pipeline.
+email:
+- support@gmapsleadfinder.com
+executables:
+- gmaps-scraper
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/quickstart.rb
+- exe/gmaps-scraper
+- google-maps-scraper-sdk.gemspec
+- lib/gmaps_scraper.rb
+- lib/gmaps_scraper/client.rb
+- lib/gmaps_scraper/errors.rb
+- lib/gmaps_scraper/version.rb
+homepage: https://gmapsleadfinder.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gmapsleadfinder.com
+  source_code_uri: https://github.com/google-maps-lead-scraper/google-maps-scraper/tree/main/ruby
+  changelog_uri: https://github.com/google-maps-lead-scraper/google-maps-scraper/blob/main/CHANGELOG.md
+  documentation_uri: https://gmapsleadfinder.com/docs/api
+  bug_tracker_uri: https://github.com/google-maps-lead-scraper/google-maps-scraper/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Google Maps Scraper / Extractor / Lead Scraper SDK for GMaps Lead Finder
+test_files: []