Read and update place data

Grant content access

Use the server SDK or REST API from your backend. An owner/admin creates a key in Share → Developer access & API keys, selecting Read approved place fields and, if needed, Update approved draft fields. Select each permitted Read/Write field as well. A normal update workflow needs both scopes.

Published reads expose only approved public values. A granted private field is available only in saved draft reads. The places API includes IDs, content types and floor relationships even when no values are granted. It does not return editor geometry, tracing plans, guides or workspace records.

Read and paginate

import { createMapApi } from "maphere-sdk/server";
const api = createMapApi({ apiKey: process.env.MAPHERE_API_KEY! });
const mapId = "33333333-3333-4333-8333-333333333333";

let cursor: string | undefined;
do {
  const page = await api.listPlaces(mapId, {
    stage: "published", limit: 50, cursor,
  });
  for (const place of page.places) {
    // Use approved values in your application; escape text in your UI.
    console.log(place.id, Object.keys(place.values));
  }
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Published is the default stage; draft reads the saved working version. Request 1–100 places per page. A cursor is bound to the current snapshot and key. If content changes between pages, discard the partial result and restart from page one after CURSOR_EXPIRED (409). Do not combine snapshots.

Responses include approved field definitions. Text, email and phone values are strings; choices use stable option IDs; numbers and booleans keep their types. Links, images and opening hours have structured JSON shapes described by the OpenAPI schema. Zero, false, an empty string and a missing value are distinct.

From API update to published map

import { createMapApi, MaphereApiError } from "maphere-sdk/server";
const api = createMapApi({ apiKey: process.env.MAPHERE_API_KEY! });
const mapId = "33333333-3333-4333-8333-333333333333";

const current = await api.listPlaces(mapId, { stage: "draft" });
// Choose an actual place ID from your saved map, not its display name.
const placeId = "bookshop";
try {
  const updated = await api.updatePlace(mapId, placeId, {
    name: "Harbour Books & Gifts", // Existing, granted field ID.
    description: null, // Remove this value; omitted fields are unchanged.
  }, { etag: current.etag });
  console.log("Saved draft revision", updated.revision);
} catch (error) {
  if (error instanceof MaphereApiError && error.status === 412) {
    // Read the latest draft and ask the editor to reconcile the conflict.
    // Do not overwrite it with an automatic retry.
  } else {
    throw error;
  }
}
// The published map is unchanged until an owner/admin publishes in Maphere.

Replace bookshop with the target place’s stable ID and name/description with actual granted field IDs. Null removes a value; omitted fields are retained. The API validates field types, references and the whole resulting document. It does not create fields, edit geometry or upload images.

Grant exports separately

The separate map:export scope allows api.exportMap(mapId) to return the active publication’s full geometry and public content, regardless of the key’s field grants. Grant it only when that full data access is intended. It does not return private draft data or image bytes, and it is not an offline map bundle.

Exported image URLs still follow the map’s access rules and active publication. Recipients can retain exported content; revocation stops future requests, not existing copies.