Data Export

Bulk delivery of Casafari's data as files, for loading into your own warehouse rather than calling the API.

#Overview

Casafari Data Export delivers real estate market data as Avro files to a dedicated Google Cloud Storage (GCS) bucket provisioned for your account. Five entity types are exported: Property, Listing, Alert, Location and ListingPhoto. The set of entities enabled for your account is defined by your contract.

#Data delivery

• Data is delivered to one GCS bucket per country. Bucket names are provided by Casafari during onboarding.
• Inside a bucket, files are grouped by entity type:

properties/       listings/       listing_photos/       alerts/       locations/

• File names follow the pattern {revision}_{salt}_{timestamp}.avro, e.g. latest_1f3a9c..._2026_07_29_10_15_30_123456.avro:
  • revision — latest for full snapshots, latest_delta for incremental updates;
  • salt — a unique hex identifier of the export batch;
  • timestamp — file creation time, YYYY_MM_DD_HH_MM_SS_ffffff.

#Data format

Files are standard Avro Object Container Files: the writer schema is embedded in every file, and each field carries a doc attribute with its description, so any Avro library or tool can read the files and inspect the schema. Optional fields are declared as ["null", ...] unions with a null default.

#Sync semantics

• Full sync produces a complete snapshot of every enabled entity. Previous files in the entity folders are removed and replaced with a new set of latest_* files.
• Delta sync periodically uploads latest_delta_* files containing records created or updated since the previous run.
• To maintain an up-to-date copy: load the latest full snapshot, then apply delta files in file-timestamp order, upserting records by entity key.

#Sync status

A file named sync_status.json at the root of the bucket reports the progress of full and delta syncs, so you can start processing as soon as a sync is done instead of waiting a fixed amount of time. It is written when a sync starts and updated when the sync finishes.

{
  "full": {
    "status": "finished",
    "started_at": "2026-09-01T02:00:00+00:00",
    "finished_at": "2026-09-01T06:30:00+00:00",
    "last_finished_at": "2026-09-01T06:30:00+00:00"
  },
  "delta": {
    "status": "processing",
    "started_at": "2026-09-11T02:00:00+00:00",
    "finished_at": null,
    "last_finished_at": "2026-09-10T03:10:00+00:00"
  }
}

The file has two sections, full and delta, with the same fields. All timestamps are ISO 8601 in UTC.

#Recommended usage

1. Read sync_status.json and pick the section you track (full or delta).
2. Start processing files only when status is finished.
3. Make sure the run actually delivered data: last_finished_at must be later than started_at. If it is earlier, the run did not complete in time — see Timeouts below.
4. To detect new data since your last import, compare last_finished_at with the value you saw last time. If it moved forward, there is new data.
5. Poll the file every 5–15 minutes; checking more often is not necessary.
6. If the file is missing or cannot be read, retry later. Never treat that as finished.

#Timeouts

A sync can take several hours, so a long processing status is normal. A sync should always complete well within 12 hours. As a safeguard, if a run is still open after 12 hours, it is closed in this file so the status never stays stuck on processing: status becomes finished while last_finished_at keeps its previous value. This only affects the file — the sync itself keeps running. This is not expected to happen; if you ever notice it, please contact your Casafari account manager.

#Entities and keys

The full field reference for every entity is provided in the schema definitions below.

#Support

For questions about the data or delivery, contact your Casafari account manager.

#Entities

Source: the API team's own description, https://docs.api.casafari.com/data-export.