Locations

List, search, create, update, and archive business locations with the listingsapi-js SDK.

Locations are the core entity in listingsAPI: 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.

TypeScript

// Single page
const 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 page
const 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

Parameter	Type	Description
`first`	`number`	Forward page size.
`after`	`string`	Cursor from a previous `pageInfo.endCursor`.
`before`	`string`	Cursor for backward pagination.
`last`	`number`	Backward page size.
`fetchAll`	`boolean`	Auto-paginate and return a flat `Location[]`.
`pageSize`	`number`	Page size used internally when `fetchAll` is `true` (default `100`).

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.

TypeScript

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.

TypeScript

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.

TypeScript

// Single page
const 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 searched
const byName = await client.searchLocations('Acme Dental', { fields: ['name'] });

Options

All pagination options from fetchAllLocations, plus:

Parameter	Type	Description
`fields`	`string[]`	Restrict the search to specific fields.

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.

TypeScript

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.

TypeScript

await client.updateLocation({
id: 16808,
phone: '4155550199',
name: 'Acme Dental Mission District',
});

archiveLocations

Archive one or more locations. Archived locations stop syncing to directories.

TypeScript

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.

TypeScript

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.

TypeScript

// These are equivalent
await client.fetchLocationsByIds([16808]);
await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);

The encoder is also exported if you need the encoded form directly:

TypeScript

import { encodeLocationId } from 'listingsapi-js';
 
encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='
encodeLocationId('16808');                // 'TG9jYXRpb246MTY4MDg='
encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged

Listings, directory sync status per location
Reviews, review list and analytics per location
Analytics, Google, Bing, Facebook insights per location