Esta guía está disponible en inglés.
How Listing Syndication Works
Listing syndication takes one business record, translates it into each publisher's format, and pushes it out asynchronously, which is why sync status matters.
De un vistazo
- Qué logra esta guía
- Explain how one location record reaches many publishers, why it is asynchronous, and how to tell whether a change landed.
- APIs utilizadas
- patch
/api/v1/locations/{id}Actualizar una ubicación - get
/api/v1/listingsObtener el listado de una ubicación - get
/api/v1/listings/summaryObtener un resumen de listados
- patch
- Referencia
- Listados publicadosLocations
- Requisitos previos
- None. This is a concept page; the guides linked from it have the code.
- Casos de uso habituales
- Understanding why a saved change is not instantly live
- Designing a sync-status view in your product
- Setting the right expectations with customers
Change a location once and every connected directory should end up agreeing. That is syndication, the delivery half of a listings API. The word doing the work is "should". This is not one write. It is a fan-out to many systems, and each one accepts changes on its own terms and its own clock.
- You update
PATCH /api/v1/locations/{id}Synup validates and stores the change - TranslateThe shared location shape is mapped to each publisher's own format
- QueueA sync is queued per connected publisher
- PublishEach publisher applies it on its own schedule; some review edits by hand
- Verify
GET /api/v1/listings?locationId=Per-publisher status reports what actually landed
Why one record looks different on each publisher
Every publisher has its own data model. Google carries categories and attributes that Apple does not. Some directories take a single phone number where others take several. Syndication maps your one location onto each of those shapes, so the same field can surface a little differently from one directory to the next, and some fields have nowhere to go on a given publisher at all. That is expected, not a bug.
The delay belongs to the publisher
The write to PATCH /api/v1/locations/{id} is synchronous. It returns the moment Synup has validated and stored the change. Getting that change onto the publishers is not. Directories refresh on their own cadence, minutes to hours, and the ones that review edits by hand can take days. Nothing you do removes that delay. It belongs to the publisher, not to the API in front of it.
One rule falls out of this, and it shapes everything you build here: never treat a successful write as a live listing. Show the customer "queued", then "live", driven by real status and not by the 200 you got back.
Telling what actually landed
Per-publisher status is a first-class read. GET /api/v1/listings returns the status for one location across its publishers. For a whole account, do not loop that call. GET /api/v1/listings/summary answers for every location at once: a per-location table of synced-versus-total publisher counts, which is how you find the locations that need attention after a bulk change. The managing listings guide shows the read-diff-verify loop, and managing thousands of locations scales it to a large account.