地点
使用 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