Locations
List, search, create, update, and archive business locations with the listingsapi-js SDK.
Locations are the core entity in Listings API: every listing, review, analytics
record, and post is scoped to one. All location methods live directly on the
ListingsAPI client instance.
fetchAllLocations
List locations for the account with cursor-based pagination. Returns an object
with locations, pageInfo, success, and the raw API payload. With
fetchAll: true it auto-paginates and returns a flat Location[] instead.
// 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 });Options
fetchLocationsByIds
Fetch specific locations by ID. Accepts numeric IDs or base64-encoded IDs and
returns a flat Location[]. An empty input array returns [] without making
a request.
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]fetchLocationsByStoreCodes
Fetch locations that match the given store codes. Returns a flat Location[];
an empty input array returns [] without making a request.
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);searchLocations
Search locations by keyword across name, address, and store ID. Returns the
same paginated shape as fetchAllLocations, and supports fetchAll the same
way.
// 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'] });Options
All pagination options from fetchAllLocations, plus:
createLocation
Create a new location. The API requires name, a description of at least
200 characters, a subCategoryId, countryIso, and city. Returns the
mutation payload with the created location; if the API rejects the input, the
client throws a ValidationError instead, so there is no success flag to
check.
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
Update one or more fields on an existing location. Pass the location id
plus any fields to change. Numeric IDs are encoded automatically.
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});archiveLocations
Archive one or more locations. Archived locations stop syncing to directories.
await client.archiveLocations([16808, 16809]);cancelArchiveLocations
Cancel scheduled archival for the given locations. Takes the location IDs,
a selectionType, and a changedBy identifier as positional arguments.
await client.cancelArchiveLocations([16808],'manual', // selectionType'ops@example.com', // changedBy);ID encoding
Every location method accepts either a numeric ID or a base64-encoded ID. The
SDK encodes numeric IDs (and numeric strings) automatically using the
Location:<id> format; values that are already encoded pass through as-is.
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);The encoder is also exported if you need the encoded form directly:
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808'); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged