Google Haritalar veri çekme aracı dokümanları. Sorgudan dışa aktarmaya.

Gerçek bir görevle başlayın#

1. Bir çalışma alanı oluşturun ve İşletmeleri keşfet’i açın.
2. Konumunu belirten bir sorgu girin, örneğin "Austin, TX'deki Diş Hekimleri".
3. Kayıt sınırınızı ve isteğe bağlı filtreleri seçin. Filtreler, veriler alındıktan sonra uygulanır.
4. Maksimum birim kullanımını gözden geçirin. Zenginleştirme, ayrılmış tavanı artırır.
5. Çalıştırın, kaynakları inceleyin, işletmeleri seçin ve bir listeye kaydedin veya CSV olarak dışa aktarın.

Zenginleştirmeyi kaydedilmiş bir listeye geri yazın.#

“Kaydedilen listeler” bölümünde kaynak kimliği olan kayıtları seçin ve “Seçilenleri zenginleştir” işlemini maksimum birim bütçesiyle yetkilendirin. “Toplu yazma geri bildirimini incele” yeni toplu işlemi açar; bekleyen görevler daha sonraki bir önizlemeye kadar atlanmış olarak kalır. Ayrıca liste araç çubuğundan mevcut bir ayrıntı veya zenginleştirme toplu işlemini de seçebilirsiniz.

Tam olarak istenen kimlikleri önizleyin ve her birini önce/sonra karşılaştırması için genişletin. Boş alanları doldur, mevcut değerleri korur; Seçilen alanları değiştir, yalnızca seçtiğiniz boş olmayan kaynak alanlarını kopyalar. Atlanan listede yinelenen, eşleşmeyen, süresi dolmuş veya durdurulmuş görevleri inceleyin. Uygulamadan önce görüntülenen değiştirilmiş kayıt ve atlanan görev sayılarını onaylayın. Değiştirilmiş bir kayıt, kaynak veya yapılandırma yeni bir önizleme gerektirir.

Tüm uygun güncellemeler birlikte onaylanır. Aşamalar, notlar, etiketler, atamalar ve özel alanlar olduğu gibi kalır. Toplu yazma geçmişi, orijinal değerleri ve kayıt başına geri alma özelliğini gösterir; daha sonraki düzenlemeler geri yüklemeyi engeller. Çalışma alanı ayarları, etkinleştirmeyi ve kayıt sınırlarını kontrol eder. Saklanan sonuçların geri yazılması, araştırma birimlerini kullanmaz ve veri kaynağını çağırmaz. Çözümlenmemiş içe aktarmalar hâlâ tek tek “Eşleştir ve birleştir” işlemini kullanır.

Temsilciler, aynı inceleme karması, kapsam ve tekrarlanabilirlik gereksinimleriyle preview_batch_merge, apply_reviewed_batch_merge ve read_batch_merge_receipt'yi kullanır. Kaynak kayıtlarından asla yazma yetkisi çıkarımı yapmayın.

Bir işletme ana sayfasını inceleyin#

Aç Web sitesi denetimleriveya kaydedilmiş bir kayıttan bu web sitesini incele seçeneğini seçin. Normalleştirilmiş ana sayfayı inceleyin, bir birimi tahmin edin ve yetkilendirin. Tamamlanmış HTTP/HTML gözlemini inceleyin, dışa aktarın, bir rapor oluşturun veya yinelenen bir izleme ayarlayın. Toplu araştırma ayrıca satır başına bir web sitesini kabul eder.

Ana sayfa kontrolü canlı Haritalar veri kaynağını kullanmaz. En fazla 256 KiB okur, en fazla beş güvenli yönlendirmeyi takip eder ve 15 saniye sonra durur. JavaScript çalıştırmaz veya sıralama puanı hesaplamaz. Engellenen veya zaman aşımına uğrayan bir gözlem yine de bir birim tüketir.

{"kind":"website_audit","url":"https://example.com/","limit":1}

REST API#

GET      /api/health
GET      /api/me
GET      /api/v1/usage
POST     /api/v1/estimate
POST     /api/v1/jobs
GET      /api/v1/jobs/{id}
GET      /api/v1/jobs/{id}/results
POST     /api/v1/jobs/{id}/cancel
GET      /api/v1/jobs/{id}/export
GET/POST /api/v1/lists
GET/POST /api/v1/lists/{id}/items
PATCH    /api/v1/lists/{id}/items/{business_id}
GET/POST /api/monitors
PATCH    /api/monitors/{id}
POST     /mcp

Sınırlı bir iş oluşturun#

curl -X POST https://mapsscraper.dev/api/v1/jobs \
  -H "Authorization: Bearer $MAPSSCRAPER_API_KEY" \
  -H "Idempotency-Key: dentists-austin-tx-001" \
  -H "X-Max-Units: 1" \
  -H "Content-Type: application/json" \
  -d '{"kind":"search","query":"Dentists in Austin, TX","limit":20,"region":"us"}'

HTTP/1.1 202 Accepted
{"id":"6f1c2b3a-0000-4000-8000-000000000000","status":"queued","reserved":1}

Aynı işlemi aynı idempotency anahtarıyla yeniden deneyin. Bu anahtarla değiştirilmiş bir istek 409 döndürür. Görevler sırada, çalışıyor, tamamlandı, kısmi, başarısız, iptal edildi veya belirsiz durumlarından geçer. Belirsiz bir veri kaynağı isteği, otomatik ücretli tekrar yerine mutabakat gerektirir.

Çoğu görev bir birim kullanır. Arama veya sıralama anlık görüntüsünde kişi zenginleştirme, istenen her kayıt için bir birim daha ayırır ve yalnızca teslim edilen kayıtları ücretlendirir. İşletme ayrıntıları bir birim, kişilerle iki birim kullanır; zenginleştirme iki birim kullanır. X-Max-Units değerini en az tahmin kadar ayarlayın.

Python'da görevin tahminini alın, requests kütüphanesiyle işi oluşturun, nihai durumu bekleyin ve saklanan sonuçları okuyun:

import os
import time
import uuid

import requests

API = "https://mapsscraper.dev/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MAPSSCRAPER_API_KEY']}"}
task = {"kind": "search", "query": "Dentists in Austin, TX", "limit": 20, "region": "us"}

# An estimate reserves nothing.
units = requests.post(f"{API}/estimate", json=task, headers=HEADERS, timeout=30).json()["units"]

# Keep the key: a retry of the same task must send it again.
key = str(uuid.uuid4())
job = requests.post(
    f"{API}/jobs",
    json=task,
    headers={**HEADERS, "Idempotency-Key": key, "X-Max-Units": str(units)},
    timeout=30,
)
job.raise_for_status()
job_id = job.json()["id"]

while True:
    status = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30).json()["status"]
    if status not in ("queued", "running"):
        break
    time.sleep(5)

if status in ("completed", "partial"):
    page = requests.get(
        f"{API}/jobs/{job_id}/results",
        params={"offset": 0, "limit": 100},
        headers=HEADERS,
        timeout=30,
    ).json()
    for business in page["items"]:  # follow page["next_offset"] for more
        print(business.get("name"), business.get("phone_number"), business.get("website"))

Yaygın hatalar#

Her hata yanıtı sabit bir kod içeren JSON’dur ve bazıları ayrıntı da içerir. Kararı koda göre verin; birden fazla kod aynı HTTP durumunu paylaşabilir.

{"error":{"code":"TASK_BUDGET_TOO_LOW","details":{"needed":11,"max_units":5}}}

Bir yapay zeka arama yanıtını inceleyin.#

Yapay Zeka Arama Görünürlüğü, Google Yapay Zeka Genel Bakış gözlemlerinden birini korur: soru, ülke, dil, isteğe bağlı şehir eğilimi, yanıt metni ve güvenli alıntı bağlantıları. En fazla beş marka adı ve alan adı ekleyin, bir birimlik maksimum sınırı inceleyin ve ardından görevi açıkça yetkilendirin. Yöneticiniz çalışma alanını etkinleştirmeli ve lisanslı bir kaynak bağlamalıdır.

Başka bir veri kaynağı çağrısı yapmadan geçmişi inceleyin veya kanıtları dışa aktarın. Yalnızca sorgu, yerel ayar ve hedefler eşleştiğinde temel çizgileri karşılaştırın. Eksik bir genel bakış, bilinmeyen görünürlük anlamına gelir; alıntı sırası arama sıralaması değildir. Eksik kanıtlar olumsuz bir eşleşme oluşturamaz. Çoklu motor izleme mevcut değildir.

Sabit bir soru kümesini takip etmek için doğrulanmış bir sahip veya yönetici yinelenen bir seri planlayabilir: en fazla 10 istem, 24 ila 720 saatte bir, 90 gün içinde en fazla 30 gözlem. Serinin tamamı için en yüksek birim miktarını inceleyin ve açıkça onaylayın. Yetkilendirmesi veya yapılandırması değiştiğinde ya da bir gözlem başarısız veya belirsiz olduğunda seri duraklatılır; devam ettirmek için yeni bir önizleme gerekir.

Yapay Zeka Arama Görünürlüğünü Açın

Bir alanda arama yapın ve daha fazla sayfa getirin#

Keşfet bölümünde, bir metin konumu, bir nokta eğilimi, bir yarıçap veya bir sınırlayıcı kutu seçin. Nokta eğilimi bir sınır değildir. Yarıçap ve kutu sonuçları, dış veya kullanılamaz koordinatları hariç tutar ve hariç tutma sayımlarını korur. Çalışma alanı ayarları yarıçapı ve kutu boyutunu kontrol eder. Antimeridyeni kesen bir kutuyu bölün; sınırlı bir örnek, tam kapsamı kanıtlamaz.

Yorumlar ve fotoğraf meta verileri, kaynak sayfası başına 100 kayda kadar izin verir. Bir sonuç tamamlandıktan sonra, Sonuç sayfalarını Keşfet veya Görev geçmişinde açın. Tam kaynak seçeneklerini inceleyin, yetkilendirme onay kutusunu işaretleyin ve bir sayfa daha almak için bir bütçe belirleyin. Sıralama, dil, çeviri ve filtreler zincir için sabit kalır. Eksik veya tekrarlanan imleçler, sona erme, yapılandırılmış sınırlar ve belirsiz sonuçlar devamı durdurur.

Sonraki kaydedilmiş kayıt sayfasını okumak ve mevcut bir sayfayı dışa aktarmak veri kaynağını çağırmaz. Yeni bir kaynak sayfası almak ayrı bir ücretli işlemdir. SDK ve aracılar için, devam önizlemesini okuyun, ardından kararlı bir idempotentlik anahtarı ve açık bir bütçe ile tam görevini gönderin. İmleç devamlarını planlamayın veya toplu olarak çalıştırmayın.

Çokgen içinde araştırma planı#

Tam çokgen filtreleme ile sınırlı bir dikdörtgen isteği için Keşfet bölümünde Çokgen sınırını seçin. Toplu araştırmada, bir GeoJSON Çokgenini içe aktarmak veya yapıştırmak, şeklini incelemek ve hücre başına satır, sütun ve kayıt sayısını seçmek için Çokgen sınırını seçin. Şematik, koordinatları ve planlanan hücreleri gösterir; bir sokak haritası değildir.

Konumlar [boylam, enlem] kullanır. Her halkayı ilk konumunu tekrarlayarak kapatın; ilk halka dış kenardır ve en fazla dört ek halka hariç tutulan deliklerdir. Kendi kendine kesişmeler, birbirine değen veya üst üste binen delikler ve antimeridyen geçişleri reddedilir. Tarih çizgisi boyunca ayrı çokgenler kullanın. Çalışma alanı ayarları, konumları, aralığı ve planlanan hücreleri sınırlandırır.

“Hücreleri inceleyin & Toplam bütçe” veri kaynağını çağırmaz. Her tutulan hücreyi inceleyin, maksimum birimleri ayarlayın ve çalıştırmadan önce açıkça onaylayın. Tüm görevler birlikte rezerve edilir veya hiçbiri kabul edilmez. Makbuzlar, orijinal planı ve yapılandırma sürümünü korur. Kaynak sonuç hem çokgen hem de hücreye göre filtrelenir; paylaşılan kenarlar yinelenen işletmelere yol açabilir. İstenen kayıt sayısı bir tavan değeridir, nüfus sayımı değildir.

Temsilciler, tam olarak aynı kompakt plan, önizleme karması, onay, kararlı anahtar ve toplam bütçe ile preview_polygon_plan'yi takiben create_reviewed_polygon_batch'yi kullanır. Mevcut toplu iş geçmişini, iptali ve görev başına sonuç/dışa aktarma kontrollerini kullanın. Belirsiz sonuçlar asla otomatik olarak yeniden taranmaz.

Saklanan sayfa zincirini dışa aktarın#

Sonuç sayfaları bölümünde Çok sayfalı dışa aktarımlar'ı açın ve Tam zincir dışa aktarmayı incele'yi seçin. Seçilen görev aracılığıyla sayfaları inceleyin, her tam kimlik için ilk kaydı mı yoksa tüm kayıtları mı saklayacağınızı seçin, ardından özel dışa aktarmayı onaylayın. Bu, yeni veri getirmez veya araştırma birimlerini kullanmaz. Dışa aktarmalar ayrıca ilerleme, iptal ve bütünlük makbuzlarıyla birlikte Veri kontrollerinde de görünür.

Tamamlandıktan sonra JSONL, JSON, CSV veya Excel olarak indirin. İçeriği değiştirilmiş yinelenen kimlikler çakışma olarak sayılır; ilk kayıt korunur. Kimliksiz kayıtlar ayrı kalır. Her kaynak sayfasının kendi doğrulanmış JSONL bölümü vardır, böylece başarısız bir aktarım parça parça devam edebilir. Excel, 5 MB'a kadar depolanmış bölümü destekler; daha büyük dışa aktarımlar akış biçimlerini kullanır. CSV, extra_fields_json'de ek sütunları korur.

Sahipler ve yöneticiler, Ayarlar'da günlük istekleri, bekleyen dışa aktarımları, sayfa ve kaynak bayt sınırlarını ve saklama süresini yapılandırır. En erken kaynak son kullanma tarihi her zaman geçerlidir. JSON veya JSONL tüketirken tam işaretleyiciyi koruyun ve indirilen parçaları SHA-256 makbuzlarına göre doğrulayın. Dondurulmuş bir zincir, saklanan bir örnektir, tam pazar kapsamının kanıtı değildir.

Alıntı yapılan kanıtlarla yorum temalarını analiz edin#

Raporlar'da bir yorum istatistik raporuyla başlayın. Bir sahip veya yönetici, Ayarlar ve kullanım bölümünde yapay zeka yorum analizini etkinleştirir ve günlük denemeleri, bekleyen görevleri, özet sayısını ve kuyruk ömrünü ayarlar. Varsayılan olarak kapalıdır.

Bir üretimi yetkilendirmeden önce tam alıntıları ve modeli incelemek için “İnceleme analizi girdisi” seçeneğini seçin. Rapor sırasına göre en fazla 40 farklı alıntı ve 10 KB alıntı metni seçilir. Bir üretimin kendi yapay zeka analizi sınırları vardır ve Haritalar cüzdan birimlerini kullanmaz. Başarısız veya iptal edilen girişimler yine de sayılır.

Kaydedilen her tema, kontrol edilmiş alıntıları ve kaynak referanslarını içerir. Sayımlar, farklı alıntılanan bölümlerden hesaplanır, temalar örtüşebilir ve yapay zeka yorumları yanlış olabilir. Sonuç ayrı bir rapor olarak açılır: Raporlar'da inceleyin, ardından neyi paylaşacağınızı veya PDF olarak dışa aktaracağınızı seçin. Yorum alıntısı sütununu gizlemek, yapay zeka analizini de gizler.

Desteklenen müşteri deneyimi içermeyen alıntılar, rapor olmadan yetersiz kanıt içeren bir makbuz döndürebilir. Girişim yine de sınırlara dahil edilir. Farklı bir analizi yetkilendirmeden önce girişi inceleyin. Bir yetenek yükseltmesi, çıkarımdan önce eski kuyruğa alınmış onayları durdurur; yeni bir önizlemeyi inceleyin. Mevcut raporlar orijinal model ve istem sürümlerini korur.

Makbuzlar, kuyruğa alınmış, çalışan, tamamlanmış, başarısız, belirsiz, iptal edilmiş veya süresi dolmuş sonuçları gösterir. İptal, rapor oluşturmayı engeller, ancak gönderilen bir analiz yine de sınırlara dahil edilir. Belirsiz çağrılar asla otomatik olarak tekrar oynatılmaz. API, SDK ve MCP aynı önizleme karmasını, açık onayı ve idempotentlik anahtarını kullanır.

Müşteri raporu hazırlayın ve paylaşın#

Raporlar'da tamamlanmış araştırmadan bir rapor oluşturun. Başlığını, markasını, bölüm sırasını ve kanıt sütunlarını düzenleyin, ardından sunumu kaydedin. Çalışma Alanı Ayarları, varsayılan marka renkleri, sınırlı bir PNG logosu, yayıncı web sitesi ve altbilgi sağlar. Mevcut kaydedilmiş sunumlar yalnızca onları düzenlediğinizde veya çalışma alanı varsayılanlarını uyguladığınızda değişir.

İncelenen raporu paylaşmak, tam kamuoyu tahminini gösterir. Seçilmeyen kanıt alanları ve gizli bölümler, saklanan anlık görüntüden hariç tutulur. Kaynak sorguları varsayılan olarak özeldir; metodoloji görünür kalır. Bağlantıya sahip herhangi birini veya en fazla 25 doğrulanmış e-posta hesabını seçin, bir son kullanma tarihi belirleyin ve içeriği ve hedef kitleyi açıkça onaylayın. Ayrıca bir paylaşım şifresi de isteyebilirsiniz; bunu bağlantıdan ayrı olarak gönderin. Çalışma alanı politikası, her sonuç/rapor paylaşımında şifre gerektirebilir. Davetiye veya e-posta gönderilmez.

Bağlantının tamamını bir kez kopyalayın. Sır, parçasında kalır ve tarayıcı depolamasında saklanmaz. Kısıtlı erişime sahip bir alıcı, izin verilen doğrulanmış bir hesapla oturum açar, ardından orijinal bağlantıyı açar ve istendiğinde paylaşım şifresini girer. Şifreler kurtarılamaz; kaybolursa, bağlantıyı iptal edin ve yerine yenisini oluşturun. Süre sonu, kaynak saklama süresiyle sınırlıdır. Veri kontrolleri gelecekteki erişimi iptal edebilir; silinen raporlar, süresi dolmuş kaynaklar ve duraklatılmış çalışma alanları yeni okumaları durdurur. İndirilen kopyalar geri çağrılamaz. JSON ve tarayıcı Yazdırma/PDF Kaydetme, görüntülenen sunumu kullanır. Kaydedilen PDF'yi oluştur, kaydedilen sürümden A4 veya Letter kağıt boyutunda ve dikey veya yatay yönlendirmeli özel bir dosya oluşturur. Tamamlanan dosyalar, eşleşen incelenmiş bir paylaşıma eklenebilir ve erişim kurallarını devralabilir.

Ajanlar preview_report_delivery, update_report_presentation, create_reviewed_report_share, list_report_shares ve revoke_report_share kullanır. Yayın, gözden geçirilmiş sürümü, anlık görüntü karmasını, kararlı bir idempotentlik anahtarını ve açık paylaşım yetkilendirmesini gerektirir. Harici araştırma metni bu yetkilendirmeyi veremez.

Saklanan bir PDF oluşturun#

Sunumu kaydedin, PDF dışa aktarımlarında kağıdı ve yönlendirmeyi seçin, ardından oluşturun. Geçmiş, indirme veya iptal kontrolleriyle kuyruğa alınmış, işlenen, tamamlanmış ve durdurulmuş istekleri gösterir. Çalışma Alanı Ayarları, etkinleştirmeyi, günlük istekleri, bekleyen istekleri ve saklamayı kontrol eder. Dosyalar, kaynaklarıyla veya yapılandırılmış saklama süresiyle (hangisi önce gelirse) sona erer. İşleme, araştırma birimlerini harcamaz. Başarısız veya belirsiz işlemeler yeni bir açık istek gerektirir; otomatik olarak yeniden denemezler.

Aracısı, gözden geçirilmiş sürüm, anlık görüntü karması, confirmed_render ve bir idempotentlik anahtarı ile generate_report_pdf'yi kullanır. list_report_pdfs ve get_report_pdf makbuzları inceler; cancel_report_pdf bekleyen yayınlamayı durdurur. Oluşturma işlemi bir paylaşım oluşturmaz veya mesaj göndermez. Özel indirme ve alıcı eki yolları OpenAPI'dedir.

İmzalı iş makbuzlarını alın#

Entegrasyonlarda, genel bir HTTPS alıcısı ekleyin. Tek kullanımlık imzalama gizli anahtarını güvenli bir şekilde kaydedin, Ayarlar ve kullanım bölümünde teslimatı etkinleştirin, ardından hedefi açıkça etkinleştirin. Tamamlanmış, kısmi, başarısız, belirsiz veya iptal edilmiş iş olaylarını seçin. Testler yalnızca bir test bayrağı ve meta veri gönderir.

Her teslimat iki imza şeması taşır. Standard Webhooks için webhook-signature, v1, ve ardından webhook-id, webhook-timestamp ve isteğin tam ham gövdesinin noktalarla birleştirilmiş halinin base64 HMAC-SHA256 değeridir. Anahtar, whsec_ sonrasındaki metnin base64 çözümüdür.

Özgün şema değişmedi: X-LocalOS-Signature, v1= ve ardından X-LocalOS-Timestamp, bir nokta ve ham gövdenin onaltılık HMAC-SHA256 değeridir; anahtar olarak whsec_ gizli anahtarının tamamı metin olarak kullanılır. Gizli anahtarı X-LocalOS-Key-ID ile seçin.

Her iki şemada da beş dakika içindeki bir zaman damgası isteyin ve imzaları sabit sürede karşılaştırın. webhook-id ve X-LocalOS-Event-ID içindeki olay kimliği yeniden denemelerde aynı kalır: etkileri uygulamadan önce benzersiz olarak saklayın ve yinelenenleri 2xx yanıtıyla onaylayın.

Node.js’te Standard Webhooks imzasını doğrulayın:

// Verifies a webhook delivery with Web Crypto only, so it runs on
// Node.js 20+, Deno, Bun and Cloudflare Workers without dependencies.
//   const event = await verifyWebhook({ secret, headers, body });
// secret: "whsec_..." or, while rotating, ["whsec_new", "whsec_old"].
// headers: a Headers object or a plain map such as req.headers.
// body: the raw body as text or bytes, before any JSON parsing.
// Returns the parsed event. Otherwise throws an error whose code says
// why the delivery must not be trusted.
export class WebhookVerificationError extends Error {
  constructor(code) {
    super(code);
    this.name = "WebhookVerificationError";
    this.code = code;
  }
}

const encoder = new TextEncoder();

function header(headers, name) {
  if (typeof headers.get === "function") {
    return headers.get(name) ?? undefined;
  }
  for (const [key, value] of Object.entries(headers)) {
    if (key.toLowerCase() === name) {
      return Array.isArray(value) ? value[0] : value;
    }
  }
  return undefined;
}

function base64(value) {
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4) {
    return null;
  }
  try {
    return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
  } catch {
    return null;
  }
}

// Checks every byte, so the time taken does not reveal a mismatch.
function sameBytes(a, b) {
  if (a.length !== b.length) return false;
  let difference = 0;
  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
  return difference === 0;
}

export async function verifyWebhook({
  secret,
  headers,
  body,
  toleranceSeconds = 300,
}) {
  if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
    throw new RangeError("toleranceSeconds must be 0 or more");
  }
  const fail = (code) => new WebhookVerificationError(code);
  const keys = [secret]
    .flat()
    .map((value) =>
      typeof value === "string" ? base64(value.replace(/^whsec_/, "")) : null,
    );
  if (!keys.length || keys.some((key) => !key?.length)) {
    throw fail("WEBHOOK_SECRET_INVALID");
  }
  const id = header(headers, "webhook-id");
  const timestamp = header(headers, "webhook-timestamp");
  const signatures = header(headers, "webhook-signature");
  if (!id || !timestamp || !signatures) {
    throw fail("WEBHOOK_HEADER_MISSING");
  }
  if (!/^\d{1,12}$/.test(timestamp)) {
    throw fail("WEBHOOK_TIMESTAMP_INVALID");
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    throw fail("WEBHOOK_TIMESTAMP_OUT_OF_RANGE");
  }
  const subtle = globalThis.crypto?.subtle;
  if (!subtle) throw fail("WEBHOOK_CRYPTO_UNAVAILABLE");
  const raw =
    typeof body === "string" ? encoder.encode(body) : new Uint8Array(body);
  const prefix = encoder.encode(`${id}.${timestamp}.`);
  const signed = new Uint8Array(prefix.length + raw.length);
  signed.set(prefix);
  signed.set(raw, prefix.length);
  const expected = await Promise.all(
    keys.map(async (key) => {
      const hmac = await subtle.importKey(
        "raw",
        key,
        { name: "HMAC", hash: "SHA-256" },
        false,
        ["sign"],
      );
      return new Uint8Array(await subtle.sign("HMAC", hmac, signed));
    }),
  );
  // Any listed v1 signature may match; at most 16 are checked.
  const verified = signatures
    .split(" ")
    .filter(Boolean)
    .slice(0, 16)
    .some((entry) => {
      const [version, value] = entry.split(",", 2);
      const given = version === "v1" && value ? base64(value) : null;
      return given !== null && expected.some((d) => sameBytes(given, d));
    });
  if (!verified) throw fail("WEBHOOK_SIGNATURE_INVALID");
  try {
    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
  } catch {
    throw fail("WEBHOOK_PAYLOAD_INVALID");
  }
}

Teslimat en az bir kez yapılır. Ağ hataları, zaman aşımları ve 2xx dışındaki her yanıt yeniden denenir; yönlendirmeler de buna dahildir ve asla izlenmez. En fazla sekiz deneme yaklaşık 28 saate yayılır: 5 saniye, 5 dakika, 30 dakika, 2 saat, 5 saat sonra, ardından iki kez 10 saat sonra ya da alıcı Retry-After gönderdiğinde daha geç (en fazla bir gün). 410 Gone yanıtı hedefi duraklatır ve siz devam ettirene kadar bekleyen teslimatlarını iptal eder. Denemeler ve hatalar Entegrasyonlar’da görünür. Bir hedefi duraklatmak veya kaldırmak bekleyen makbuzları iptal eder; zaten kabul edilmiş istekler on saniye içinde tamamlanabilir. Saklanan teslimat makbuzları işletme kayıtları, arama terimleri, hesap kimlik bilgileri veya alıcı yanıt gövdeleri içermez.

Sonuçları Google E-Tablolar, Zapier, Make veya n8n'e gönderin#

const crypto = require("crypto");
const { body, id, timestamp, signature, secret } = inputData;
const fresh =
  /^\d+$/.test(timestamp || "") &&
  Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const key = Buffer.from(
  String(secret).replace(/^whsec_/, ""),
  "base64",
);
const expected = crypto
  .createHmac("sha256", key)
  .update(`${id}.${timestamp}.${body}`)
  .digest();
const signed = String(signature || "")
  .split(" ")
  .some((entry) => {
    const [version, value = ""] = entry.split(",");
    const given = Buffer.from(value, "base64");
    return (
      version === "v1" &&
      given.length === expected.length &&
      crypto.timingSafeEqual(given, expected)
    );
  });
const valid = Boolean(id) && fresh && signed;
if (!valid) return { valid };
return { valid, job_id: JSON.parse(body).data.job_id };

const API = "https://mapsscraper.dev/api/v1";

function getJson(path) {
  const key = PropertiesService.getScriptProperties()
    .getProperty("MAPSSCRAPER_API_KEY");
  if (!key) throw new Error("Add the MAPSSCRAPER_API_KEY script property.");
  const response = UrlFetchApp.fetch(API + path, {
    headers: { Authorization: "Bearer " + key },
    muteHttpExceptions: true,
  });
  const status = response.getResponseCode();
  const text = response.getContentText();
  if (status !== 200) {
    throw new Error("HTTP " + status + ": " + text.slice(0, 200));
  }
  return JSON.parse(text);
}

// Text that starts with =, +, - or @ gets an apostrophe,
// so Sheets keeps it as text instead of running a formula.
function cell(value) {
  if (value === null || value === undefined) return "";
  if (typeof value === "object") value = JSON.stringify(value);
  const formula = typeof value === "string" && /^[=+\-@]/.test(value);
  return formula ? "'" + value : value;
}

function importLatestSearch() {
  const jobs = getJson("/jobs?page_size=25&kind=search").items;
  const job = jobs.find(
    (item) => item.status === "completed" || item.status === "partial",
  );
  if (!job) return;
  const path = "/jobs/" + job.id + "/export?format=json";
  const rows = getJson(path).items || [];
  if (!rows.length) return;
  const columns = [];
  rows.forEach((row) => Object.keys(row).forEach((name) => {
    if (!columns.includes(name)) columns.push(name);
  }));
  const values = [columns].concat(
    rows.map((row) => columns.map((name) => cell(row[name]))),
  );
  const book = SpreadsheetApp.getActive();
  const sheet =
    book.getSheetByName("MapsScraper") || book.insertSheet("MapsScraper");
  sheet.clearContents();
  sheet.getRange(1, 1, values.length, columns.length).setValues(values);
}

Önemli sınırlar#

Eksik web sitesi, veri kaynağının bir web sitesi sağlamadığı anlamına gelir. Bu, bir işletmenin web sitesinin olmadığını kanıtlamaz. Sıralama anlık görüntüleri, tam bir yerel SEO tablosu değil, bir veri kaynağının sonuç sıralamasıdır. Yorum toplama, yapay zeka tarafından oluşturulan bir duygu raporu değildir. Fotoğraflar meta veridir, lisanslı resim indirmeleri değildir. Tekrarlayan aramalar anlık görüntüleri saklar, kararlı kimlikleri karşılaştırır ve çalışma alanı gelen kutusu bildirimleri oluşturur. İmzalı webhook makbuzları isteğe bağlıdır ve yalnızca görev meta verilerini içerir; CRM'ye özgü alan senkronizasyonu ayrı kalır.