Documentation使用說明
Complete guide to installing and using PlacesImporter with ListingPro.
PlacesImporter 完整安裝與使用指南。
Requirements系統需求
| Component項目 | Minimum最低需求 |
|---|---|
| WordPress | 5.8+ |
| PHP | 7.4+ |
| ListingPro Theme | v2.6+ |
| SerpApi Key | Free tier available (250 searches/month)有免費方案（每月 250 次搜尋） |
| Google AI Studio Key | Free tier available — Pro AI features only有免費方案 — 僅 Pro 的 AI 功能需要 |
Installation安裝方式
Install the Plugin安裝外掛
In your WordPress admin, go to Plugins → Add New and search for Places Importer for ListingPro, or choose Upload Plugin and select the plugin ZIP file, then click Install Now.
進入 WordPress 後台 外掛 → 安裝外掛，搜尋 Places Importer for ListingPro；或選擇 上傳外掛 並選取外掛 ZIP 檔，再點擊立即安裝。
Activate the Plugin啟用外掛
Click Activate Plugin. A new Places Importer menu appears in your admin sidebar, and a short welcome guide walks you through adding your SerpApi key and running your first import.
點擊 啟用外掛，後台側邊欄會出現 Places Importer 選單，並會顯示簡短的新手引導，帶你完成 SerpApi 金鑰設定與第一次匯入。
Verify ListingPro is Active確認 ListingPro 已啟用
PlacesImporter requires the ListingPro theme. Listings are created as ListingPro listings using its native fields, categories, locations, features and tags.
PlacesImporter 需要 ListingPro 佈景主題，店家會以 ListingPro 原生欄位、分類、地區、設施與標籤建立為列表。
API SetupAPI 金鑰設定
The plugin page has four tabs: Smart Fetch Engine, API & Settings, System Health and What's New. All keys are entered in the API & Settings tab and saved automatically.
外掛頁面分為四個分頁：Smart Fetch Engine、API & Settings、System Health、What's New。所有金鑰都在 API & Settings 分頁填寫，會自動儲存。
SerpApi
SerpApi fetches live Google Maps data. Get a free key at serpapi.com, paste it in, and click Test to confirm it works.
SerpApi 負責抓取 Google 地圖即時資料。前往 serpapi.com 取得免費金鑰，貼上後點擊 測試 確認可以使用。
Google AI Studio (Gemini) PRO
Needed only for AI features. Get a free key at aistudio.google.com. There is no test button to press — as soon as you paste the key, the plugin automatically detects, verifies and selects the best available Gemini model. If a model later becomes unavailable, it falls back to another one automatically.
僅 AI 功能需要。前往 aistudio.google.com 取得免費金鑰。不需要按測試——貼上金鑰後，外掛會自動偵測、驗證並選用最佳的 Gemini 模型；日後若模型失效，也會自動改用其他可用模型。
Importing Businesses匯入店家
Open the Smart Fetch Engine tab. There are two ways to find businesses:
打開 Smart Fetch Engine 分頁，有兩種方式找店家：
- Search by category & location — pick a ListingPro category and location (the search query is filled in for you, and you can edit it), e.g. "Tokyo restaurants".
- 依分類與地區搜尋 — 選擇 ListingPro 分類與地區（會自動帶入搜尋字詞，也可自行修改），例如「東京 餐廳」。
- Fetch by Name — paste business names or Google Maps URLs, one per line, to import exactly those businesses. URLs avoid mix-ups when several businesses share a name.
- 依名稱匯入 — 貼上店家名稱或 Google 地圖網址（一行一筆），精準匯入指定店家。同名店家很多時，用網址可避免抓錯。
Choose what to import選擇要匯入的項目
Above the search button, the "This time, fetch:" buttons let you toggle Reviews, Photo Gallery, Opening Hours, Social & Website Links and Features & Amenities. Basic Info (name, category, address, phone, rating, coordinates) is always included. The same buttons also appear above the results so you can adjust after seeing what was found. Your choices are remembered for next time.
搜尋按鈕上方的 「本次要抓取」 按鈕，可開關評論、相簿、營業時間、社群與網站連結、設施與服務。核心基本資料（店名、分類、地址、電話、評分、座標）一律匯入。搜尋結果上方也有同一組按鈕，看完結果後仍可調整，選擇會自動記住。
Run the import執行匯入
- Click Launch Engine — it runs whichever search you filled in.
- 點擊 啟動引擎 — 會依你填寫的欄位執行對應的搜尋。
- Tick the businesses you want (Select All picks only new ones), then click the import button at the bottom of the list.
- 勾選要匯入的店家（一鍵全選 只會選取尚未匯入的店家），再點擊清單最下方的匯入按鈕。
- When finished, the report shows each field as imported, not selected, or Google has no data.
- 完成後的報告會標示每個項目為 已匯入、本次未勾選 或 Google 沒有提供資料。
Places below your Minimum Rating (set in API & Settings, default 3.0★) are skipped automatically. The free version shows up to 5 results per search; Pro is unlimited with "Load More".
低於 任務自動評分過濾門檻（在 API & Settings 設定，預設 3.0★）的店家會自動略過。免費版每次搜尋最多顯示 5 筆，Pro 無上限並可「載入更多」。
AI FeaturesAI 功能 PRO
When a Gemini API key is configured, PlacesImporter enhances each imported listing with:
設定 Gemini API 金鑰後，每筆匯入的店家資料將自動強化：
- Business Introduction — A 150–300 word description written from the business info and reviews
- 店家介紹 — 根據店家資訊與評論撰寫 150–300 字的介紹
- Review Translation — Customer reviews are translated into your site's language
- 評論翻譯 — 顧客評論自動翻譯成網站語言
- Auto-Tagging — Relevant tags are generated and added to ListingPro's tags
- 自動標籤 — 自動產生相關標籤並加入 ListingPro 標籤
- Category Matching — AI selects the best matching ListingPro category
- 分類比對 — AI 自動選擇最適合的 ListingPro 分類
- SEO Image Alt Text — Descriptive alt text is generated for imported photos
- 圖片 SEO Alt 文字 — 自動為匯入照片生成描述性 Alt 文字
Temporary Gemini errors (such as "high demand") are retried automatically before falling back to another model.
遇到 Gemini 暫時性錯誤（例如流量過高）會自動重試，必要時改用其他模型。
Background Auto Sync背景自動同步 PRO
PlacesImporter can keep imported listings fresh by re-checking them on a schedule via WP-Cron.
PlacesImporter 可透過 WP-Cron 定期重新檢查已匯入的店家，讓資料保持最新。
How to Enable如何啟用
In the API & Settings tab, tick Enable Background Auto Sync, then set:
在 API & Settings 分頁勾選 啟用背景自動同步，然後設定：
- Sync cycle — 7, 14 or 30 days. A listing becomes due for an update this long after its last sync.
- 同步週期 — 7、14 或 30 天。店家距離上次同步超過這個天數，就會排入更新。
- Businesses per day — 5, 10, 20 or 50. The plugin shows a live recommendation based on how many listings you have and your cycle, and tags the recommended option.
- 每天同步數量 — 5、10、20 或 50 間。外掛會依你的店家數與週期即時給出建議，並在建議的選項旁標示。
- Update during sync — choose exactly what gets refreshed.
- 同步時更新 — 精確選擇要更新哪些項目。
Choose what gets updated選擇要更新的項目
| Item項目 | Default預設 |
|---|---|
| Rating & Review Count評分與評論數 | On開啟 |
| Review Content評論內容 | On開啟 |
| Opening Hours營業時間 | On開啟 |
| Cover & Gallery Photos封面與相簿照片 | Off關閉 |
| Name, Description & Price名稱、描述與價位 | Off關閉 |
| Address, Phone & Coordinates地址、電話與座標 | Off關閉 |
| Links, Features & Tags連結、特色與標籤 | Off關閉 |
Unchecked items keep their current values, so anything you or the business owner edited by hand is never overwritten. Skipping photos also saves API requests and downloads, and if nothing that needs AI is selected, Gemini isn't called at all.
未勾選的項目會保留目前的內容，你或店家手動修改過的資料都不會被覆蓋。不更新照片還能省下 API 請求與下載；若沒有勾選需要 AI 的項目，就完全不會呼叫 Gemini。
Next Sync column & Sync now「下次同步」欄位與立即同步
The Listings screen has a Next Sync column. It counts down to each listing's next update, and for overdue listings shows their place in the queue and roughly when they'll be synced (the oldest listings are synced first). Click Sync now under any listing to update it immediately without waiting.
後台 Listings 列表有 下次同步 欄位，顯示每間店距離下次更新的倒數；已到期的會顯示排隊順序與預估同步時間（最久沒更新的優先）。點擊任一店家下方的 立即同步，即可馬上更新，不必排隊。
Imported Fields Reference匯入欄位參考
| Field欄位 | Source來源 | Notes備註 |
|---|---|---|
| Business Name店家名稱 | SerpApi | — |
| Full Address完整地址 | SerpApi | — |
| Phone Number聯絡電話 | SerpApi | Free & Pro免費版與 Pro 皆可 |
| Opening Hours營業時間 | SerpApi | — |
| Google Rating & Review CountGoogle 評分與評論數 | SerpApi | — |
| Price Range價位 | SerpApi | When Google provides $–$$$$Google 有提供 $–$$$$ 時 |
| Features & Amenities設施與服務 | SerpApi | Accessibility, service options, offerings, hotel amenities → ListingPro Features無障礙、服務選項、供應品項、飯店設施 → ListingPro Features |
| Category分類 | Google type / Gemini AIGoogle 類型／Gemini AI | Matched to your existing categories; AI matching is Pro比對現有分類；AI 比對為 Pro |
| Cover Photo封面照片 | SerpApi | Downloaded to your Media Library下載至媒體庫 |
| GPS CoordinatesGPS 座標 | SerpApi | — |
| Gallery Photos相簿照片 | SerpApi | Up to 12 images (Pro)最多 12 張（Pro） |
| Reviews顧客評論 | SerpApi + Gemini AI | AI translated (Pro)AI 翻譯（Pro） |
| Description店家介紹 | Gemini AI | AI written (Pro)AI 撰寫（Pro） |
| Tags標籤 | Gemini AI | AI generated (Pro)AI 自動產生（Pro） |
| Website / Facebook / Instagram網站／Facebook／Instagram | SerpApi | Detected from website URL (Pro)從網站網址偵測（Pro） |
FAQ
Does it work if I don't have a Gemini key?沒有 Gemini 金鑰也能使用嗎？
Yes. All AI features are optional. Without a Gemini key, businesses are imported with their original data from SerpApi — no translation, AI description or AI tagging.
可以。所有 AI 功能均為選配。沒有 Gemini 金鑰時，仍可正常匯入 SerpApi 的原始資料，只是不會有翻譯、AI 介紹和 AI 標籤。
Can I re-import a business to update it?可以重新匯入已存在的店家來更新資料嗎？
Yes. Tick it again in the search results, or (Pro) click Sync now on the Listings screen. The existing listing is found by its Google Place ID and updated in place — never duplicated.
可以。在搜尋結果中再次勾選，或（Pro）在 Listings 列表點擊 立即同步。系統會透過 Google Place ID 找到原本的店家並直接更新，不會重複建立。
Will auto sync overwrite my manual edits?自動同步會覆蓋我手動修改的內容嗎？
Not unless you ask it to. Only the items ticked under Update during sync are refreshed; everything else keeps its current value. By default, the name, description, address, photos and links are left untouched.
不會，除非你勾選要更新。只有在 同步時更新 勾選的項目會被更新，其他都保留原本內容。預設不會動到名稱、描述、地址、照片與連結。
Why do many listings say "waiting in queue"?為什麼很多店家顯示「排隊中」？
Each day only the number of businesses you chose under Businesses per day is synced, oldest first. If you have more listings than your daily amount can cover within one cycle, some will wait. Follow the recommendation shown in Settings, choose a longer cycle, or use Sync now for urgent ones.
每天只會同步你在 每天同步數量 設定的間數，由最久沒更新的開始。若店家數多到一個週期內輪不完，就會有店家需要排隊。可依設定頁的建議調高每日數量、改用較長的週期，或對急需更新的店家使用 立即同步。
Is there a limit on how many businesses I can import?匯入數量有限制嗎？
The free version shows up to 5 results per search. Pro removes that limit. Beyond that, the only limit is your SerpApi monthly quota (free tier: 250 searches/month).
免費版每次搜尋最多顯示 5 筆，Pro 沒有此限制。除此之外，唯一的上限是您的 SerpApi 月配額（免費方案每月 250 次搜尋）。
Upgrading to Pro升級至 Pro 版
Pro unlocks unlimited search results, Gemini AI descriptions, translation & tagging, full gallery sync, social link import, and configurable background auto-sync.
Pro 版開啟無限搜尋筆數、Gemini AI 介紹、翻譯與標籤、完整相簿同步、社群連結匯入，以及可自訂的背景自動同步。
Purchase a License購買授權
Visit the Pro checkout page and complete the purchase. You'll receive your license key and a download link by email.
前往 Pro 購買頁面 完成結帳，之後會收到包含授權金鑰與下載連結的確認信件。
Download the Pro ZIP下載 Pro 版 ZIP
Download the Pro ZIP (placesimporter-for-listingpro-premium-x.x.x.zip) from the link in your confirmation email or from your Freemius account dashboard.
從確認信件中的連結或 Freemius 帳號後台下載 Pro 版 ZIP（placesimporter-for-listingpro-premium-x.x.x.zip）。
Install & Activate安裝並啟用
Go to Plugins → Add New → Upload Plugin, upload the Pro ZIP and choose Replace current with uploaded if prompted. Then enter your license key when asked. All your settings are preserved.
進入 外掛 → 安裝外掛 → 上傳外掛，上傳 Pro 版 ZIP，提示覆蓋時選擇 以上傳的版本取代目前版本，再依提示輸入授權金鑰。所有設定將完整保留。