地點
使用 listingsapi-js SDK 列出、搜尋、建立、更新及封存商家地點。
地點是 Listings API 的核心實體：每筆商家資訊、評論、分析記錄和貼文都屬於一個地點。所有地點方法都位於 ListingsAPI 用戶端實例上。
fetchAllLocations
使用游標式分頁列出帳戶中的地點。傳回的物件包含 locations、pageInfo、success 和 raw API 酬載。使用 fetchAll: true 時，會自動分頁，改為傳回扁平的 Location[]。
// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations); // Location[]console.log(page.pageInfo); // { hasNextPage, hasPreviousPage, startCursor, endCursor, total? } // Next pageconst next = await client.fetchAllLocations({ first: 25, after: page.pageInfo.endCursor!,});} // All pages at once, returns Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });選項
fetchLocationsByIds
依 ID 取得特定地點。接受數值 ID 或經 base64 編碼的 ID，並傳回扁平的 Location[]。若輸入陣列為空，則傳回 []，不會發出請求。
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]fetchLocationsByStoreCodes
取得符合指定商店代碼的地點。傳回扁平的 Location[]；若輸入陣列為空，則傳回 []，不會發出請求。
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);searchLocations
以關鍵字搜尋地點的名稱、地址和商店 ID。傳回的分頁資料結構與 fetchAllLocations 相同，並以相同方式支援 fetchAll。
// Single pageconst result = await client.searchLocations('Brooklyn', { first: 20 });if (!Array.isArray(result)) {console.log(result.locations, result.pageInfo);} // All matching results, returns Location[]const all = await client.searchLocations('Brooklyn', { fetchAll: true }); // Restrict which fields are searchedconst byName = await client.searchLocations('Acme Dental', { fields: ['name'] });選項
包含 fetchAllLocations 的所有分頁選項，以及：
createLocation
建立新地點。API 要求提供 name、至少 200 個字元的 description、subCategoryId、countryIso 和 city。傳回包含已建立地點的回應酬載；若 API 拒絕輸入，用戶端則會擲回 ValidationError，因此沒有可供檢查的成功旗標。
const result = await client.createLocation({name: 'Acme Dental',description: 'Acme Dental is a family-owned dental practice offering cleanings, ' + 'checkups, fillings, crowns, and cosmetic dentistry for patients of all ' + 'ages. Our gentle, experienced team uses modern digital imaging and ' + 'same-day scheduling to make every visit fast and comfortable.',subCategoryId: 1432,countryIso: 'US',city: 'San Francisco',street: '2100 Mission St',stateIso: 'CA',postalCode: '94110',phone: '4155550100',storeId: 'AD-SF-003',});console.log(result.location.id);updateLocation
更新現有地點的一個或多個欄位。傳入地點的 id 及任何要變更的欄位。數值 ID 會自動編碼。
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});archiveLocations
封存一個或多個地點。已封存的地點會停止同步至目錄。
await client.archiveLocations([16808, 16809]);cancelArchiveLocations
取消指定地點的排定封存作業。接受地點 ID、selectionType 和 changedBy 識別碼作為位置引數。
await client.cancelArchiveLocations([16808],'manual', // selectionType'ops@example.com', // changedBy);ID 編碼
每個地點方法都接受數值 ID 或經 base64 編碼的 ID。SDK 會使用 Location:<id> 格式自動編碼數值 ID（及數值字串）；已編碼的值則會原樣傳遞。
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);如果您需要直接使用編碼後的形式，也可以使用已匯出的編碼器：
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808'); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged