Address parts

Send profile=extended to receive data.address_parts on new readings. Use it to prefill separate address inputs, then ask the person reviewing the document to confirm them. No additional image, request option or model call is needed.

These parts describe text within the printed DOMICILIO (address). They are not twelve separately labelled electoral fields that every INE contains. The complete OCR address remains in data.address, and data.street remains the complete street line. The parser only separates supported text already present in the twenty printed fields. It does not consult a postal service, infer geography, expand abbreviations or verify that an address exists or accepts deliveries.

Twelve simple keys

When address_parts is present, it contains all twelve keys as strings or null.

A number inside a street name is not automatically a house number. Unsupported, absent, ambiguous or conflicting parts remain null. A populated part is not proof that OCR read the original image correctly.

Block, lot, unit and building

block means manzana, and lot means lote. Some addresses printed under DOMICILIO use these identifiers instead of, or alongside, a conventional house number. They are optional address details; the parser does not obtain them from an INE registry or a cadastral record.

In the fictional street line CALLE EJEMPLO NO 012 EDIF B INT 04 MZA 003 LOTE 007:

A shorter fictional line, MZA 003 LT 007, can supply block and lot while street and number remain null. Conversely, CALLE EJEMPLO NO 012 supplies neither a manzana nor a lote; both remain null. An absent part is not zero, and not evidence that the address is invalid.

The separately printed SECCIÓN, returned as data.section, is an electoral section code. A hypothetical SECCIÓN 0042 must never become block: "0042", lot: "0042" or a postal code. See the printed-field reference.

Neighborhood, locality and municipality

These names describe different roles. A colonia is a neighborhood; a localidad is a named locality or settlement; a municipio/alcaldía is an administrative municipality or borough. Their names can overlap in real addresses, so the parser does not copy one into another role.

For fictional, explicitly labelled text, COL DEMOSTRACION can yield neighborhood: "DEMOSTRACION", LOCALIDAD VILLA EJEMPLO can yield locality: "VILLA EJEMPLO", and the OCR municipality field MUNICIPIO EJEMPLO can yield municipality: "EJEMPLO". An unlabelled neighborhood field such as CENTRO is not enough on its own to choose between neighborhood and locality. Unsupported or conflicting roles stay null.

The existing data.neighborhood is an OCR field that may contain colonia or locality text. Parsed neighborhood and locality use supported role labels within that field or the original address. The parser does not infer a missing municipality from a locality, state or postal code.

Zip and postal code

data.postal_code is the original OCR field. data.address_parts.zip is its supported postal-code substring. If the fictional OCR field is C.P. 00100, the parsed zip is 00100 and its source points into postal_code. If the source already contains 00100, the value can be identical. The original OCR field is never overwritten.

Both are strings, not numbers. Supported foreign postal-code text can also be preserved; the parser does not assume every overseas INE has a five-digit Mexican code. A matching format does not verify location or deliverability.

Fictional example

This is a shortened response excerpt, not a complete API envelope. Assume the OCR street and address both contain the fictional text CALLE EJEMPLO NO 012 EDIF B INT 04 MZA 003 LOTE 007, with no other address fields populated:

{
  "data": {
    "address": "CALLE EJEMPLO NO 012 EDIF B INT 04 MZA 003 LOTE 007",
    "street": "CALLE EJEMPLO NO 012 EDIF B INT 04 MZA 003 LOTE 007",
    "address_parts": {
      "type": "CALLE",
      "street": "EJEMPLO",
      "number": "012",
      "unit": "04",
      "building": "B",
      "block": "003",
      "lot": "007",
      "neighborhood": null,
      "locality": null,
      "municipality": null,
      "state": null,
      "zip": null
    }
  }
}

Do not convert number, unit or zip to numbers: doing so would discard meaningful zeros. Keep the original address alongside the reviewed inputs.

Trace a part to its source

sources.address_parts has the same twelve keys. A populated part has an object; a null part has a null source. For the example above, the exterior number's source is:

{
  "method": "parsed",
  "field": "street",
  "start": 17,
  "end": 20
}

field names the original OCR value under data: street, address, neighborhood, municipality, state or postal_code. It never points into address_parts. Offsets are zero-based UTF-16 code units, with end exclusive, matching JavaScript String.slice. They are text offsets, not image coordinates or confidence scores.

const parts = result.data.address_parts
const source = result.sources.address_parts?.number

if (parts && source) {
  const original = result.data[source.field]
  const literal = original.slice(source.start, source.end)
  // literal === parts.number; display it for review.
}

Use UTF-16-aware slicing in other languages: ordinary Python string indexes, for example, differ for characters outside the basic multilingual plane. A source shows which OCR substring was used; it does not establish that the printed document is correct.

Warnings and older results

The result always keeps needs_review: true. Missing warnings do not prove correctness. Handle unknown warning codes without breaking your integration.

Parts are computed once when a new extended reading is created and stored with that result. GET and idempotent replay do not call the model or parser again. Older saved extended results may omit both address_parts objects; treat that as unavailable, not as a malformed response. The default standard response and legacy v1/v2 contracts remain unchanged. Prices and reading-unit rules are unchanged.