DOCSEARCHbyAlgolia
Submit Docs

AddressZen Documentation

website·Indexed 33 days ago

https://docs.addresszen.com

Integration guides, client libraries, and a REST API reference for US and international address lookup and verification. Features include the AddressZen CLI (azn) for managing API keys and validating emails, phone numbers, and USPS CASS-certified addresses, as well as a customizable Address Lookup component for web forms with support for geospatial biasing and WCAG 2.1 Level AA accessibility.

Tokens
137.3K
Snippets
454
Records
862
Agent score
53%

What's inside AddressZen

  1. Overview of AddressZen data services

    AddressZen provides several tools and datasets for address management:

    • Address Lookup: A tool to extract address suggestions based on a complete or partial address.
    • Multiple Residence Dataset: Identifies and verifies premises where households share the same letter box, providing a detailed address structure.
    • Not Yet Built Dataset: A Royal Mail database listing properties currently in planning or under construction.
    • Data Cleansing: Solutions to remove duplicates, standardize formats, and correct inaccurate data.
    • Data Extraction: The process of extracting PAF Data to generate new address records in a database.

  2. Overview of Sublicensing Keys

    Sublicensing Keys allow platform vendors to license multiple organizations or individuals (Licensees) under a single API key. All usage is managed, controlled, and billed to the primary account holder. This is specifically designed for vendors providing services to multiple clients who each have their own end-users.

  3. Overview of the Eircode Address File (ECAF) dataset

    ECAF is the Eircode Address File, containing one record per Irish postal address. English and Irish language versions are indexed separately and distinguished by the language field.

    Key constraints:

    • Unavailable elements are returned as empty strings (""), never null.
    • ECAF does not contain coordinates; longitude and latitude are always empty strings. For geolocated Irish addresses, use the EcadAddress dataset instead.

  4. Overview of the BAN French Address File

    The Base Adresse Nationale (BAN) is France's official open national address database published via Etalab. It covers metropolitan France and overseas départements. Note that BAN only provides data down to the house-number level (numero + street + commune) and does not contain sub-premise data such as unit, floor, or building numbers.

  5. Overview of the Swisstopo Swiss Address File

    The Swisstopo dataset provides address information for Switzerland and Liechtenstein. Data is aggregated from three upstream Swisstopo products: the building address directory (gebaeudeadressverzeichnis), the street directory (strassenverzeichnis), and the official directory of towns and cities (amtovz). For records marked as multilingual upstream, the dataset provides one address per street name, with the language field identifying the specific language of the street name.

  6. Overview of Kartverket (Matrikkelen) address data

    Address data from Matrikkelen is provided by Kartverket (the Norwegian Mapping Authority) and covers Norway (NOR) and Svalbard and Jan Mayen (SJM). The data is aggregated from cadastre address, apartment level, and road address files. Because the source files vary, the available fields in a record depend on the origin file; any field not present in the source is returned as an empty string ("").

  7. Check API Key availability and licensed contexts

    Use the GET /v1/keys/{key} endpoint to retrieve public information about an Address Zen API key. This endpoint determines if a key is currently usable (available), lists the geographical search contexts it is licensed for (contexts), and identifies the context matching the caller's IP address (context).

    Key Details:

    • Supports API Keys (starting with ak_) and sub-licensed keys (starting with sl_).
    • No user_token is required for public information.
    • If a valid user_token belonging to the key owner is provided, the endpoint returns private key details instead.
    • A 200 OK response with available: false indicates the key exists but cannot be used (e.g., exhausted lookups or breached limits).
    • Unknown or malformed keys return an error (e.g., 404 Not Found).
    curl 'https://api.addresszen.com/v1/keys/ak_test'

  8. Understand the Not Yet Built (NYB) address format

    The Not Yet Built (NYB) address format is used for delivery points allocated by Royal Mail for addresses under construction before they appear in the Postcode Address File (PAF). The data structure is identical to the PAF format, with the only difference being the dataset label, which is set to nyb.

  9. Verify US addresses using the Address Verification API

    The Address Verification API cleans, standardizes, and validates US addresses against authoritative postal data. It is used for data quality improvement, form validation, order processing, and CRM integration. The API returns a standardized, deliverable address or an error if the address cannot be verified.

  10. Understand Addresszen API Openbare Ruimte (Public Space) fields

    The Addresszen API provides detailed information about the 'openbare ruimte' (public space) object based on the Dutch BAG standard. Key fields include:

    • openbare_ruimte_identificatie: Unique identifier of the public space object.
    • openbare_ruimte_naam: The official name (usually the street name).
    • openbare_ruimte_type: The nature of the object (e.g., Weg for road, Water, Spoorbaan for railway).
    • openbare_ruimte_status: The current status (e.g., Naamgeving uitgegeven).
    • openbare_ruimte_geconstateerd: Boolean indicating if the object was included via observation without a regular source document.
    • openbare_ruimte_verkorte_naam: Abbreviated name used if the full name exceeds 24 characters.
    • Timestamps (ISO 8601): Includes openbare_ruimte_begin_geldigheid (start of validity), openbare_ruimte_eind_geldigheid (end of validity), and registration times for both the source holder (tijdstip_registratie) and the Landelijke Voorziening BAG (tijdstip_registratie_lv).
    • Documentation: openbare_ruimte_documentdatum and openbare_ruimte_documentnummer provide the date and ID of the source document.

  11. Manage API keys with azn keys

    The azn keys command group allows you to inspect and manage API keys. Most subcommands accept an optional [key] positional argument. If omitted, the CLI uses the currently resolved api_key.

    Authentication Requirements: All subcommands except azn keys get and azn keys context require a user_token. The CLI looks for this token in the following order:

    1. The --user-token flag
    2. The AZN_USER_TOKEN environment variable
    3. A session established via azn auth login

    If no token is found, the command exits with code: missing_user_token.

  12. Understand MoIS South Korean road name address indexing

    The MoIS dataset contains South Korean road name addresses (도로명주소) published by the Ministry of the Interior and Safety. Each address is indexed twice: once in Hangul and once in Revised Romanization. When using the API, line_1 and line_2 will match the language of the document found, while the underlying MOIS fields are returned using their original Hangul names. If a source record lacks a value for a Korean-named field, it is returned as an empty string.