Zillow API batch lookups: handle partial success

A batch response has more than one outcome

The PropertiesAPI batch endpoint accepts 1 to 50 items per request. Each result has its own ok flag and input index. Treat the batch as a collection of independent outcomes: a successful HTTP response does not mean every property lookup succeeded.

Batching is useful when you already have a list of Zillow links or addresses. It reduces request orchestration in your application. It does not turn the endpoint into a market search feed, guarantee simultaneous completion, or remove account and service limits.

• Start with a complete address-to-CSV program

Validate and label rows before sending

Give each input a stable local row ID. Check empty strings and duplicates before submission, and split larger files into chunks no larger than the documented batch limit. Store the mapping from batch index to original row ID before making the request.

The documented body accepts string inputs or objects with a url or address. Optional status applies to the whole request. If your file mixes sale and rental properties, omit a blanket hint or group rows intentionally. Do not force every property into one listing category just because it simplifies the request.

{
  "items": [
    { "address": "1600 Main St, Austin, TX 78701" },
    { "address": "1 Nowhere Rd, Austin, TX 78701" }
  ]
}

Read every result before marking the job complete

For each returned item, join its index back to the saved row mapping. If ok is true, save the property and its metadata. Otherwise save the error code against that row. A finished batch should account for every submitted row, including failures.

The addresses above are illustrative placeholders, not verified live properties. Use your own authorized inputs when exercising the endpoint. A realistic test includes an intentionally invalid row so you can prove that partial failure does not discard successful rows.

Retry only the rows that need it

Validation errors need corrected input. Ambiguous addresses need review. Transient service errors may justify a bounded retry after the indicated delay. An item that misses the batch deadline can be retried separately rather than resubmitting the entire file.

Keep successful rows out of the retry queue. Even when a repeated lookup is cached, replaying every item wastes client time and makes progress harder to measure. Put a maximum attempt count and an overall time budget on the job so a failing source cannot keep it running indefinitely.

Reconcile credits separately from row counts

Use the response metadata and your account usage to reconcile charges. Submitted rows, successful rows and charged credits are different counts. Cached results and failed lookups do not have the same billing outcome as successful live collections.

A useful job summary includes submitted, succeeded, failed, deferred and credits. Retain errors in an export rather than silently dropping them. Otherwise a CSV with fewer rows can look like a complete dataset even though several properties were never resolved.

Start small before importing a large file

Run a small representative chunk first and inspect the output manually. Confirm identity, field interpretation and retry behavior before increasing the workload. Choose concurrency from the current plan limits and observed service behavior; a batch size is not a throughput promise.