H
Document address normalization and geocoding

The NOE Address Fixer is a self-contained automation utility that cleans, normalizes, and geocodes address data on a monday.com Orders board. Triggered by a webhook, it extracts messy address text, parses it into standardized components using Python, fetches coordinates via Google Maps, and writes the structured data back to the original monday.com item.

This document outlines the workflow pipeline, tracks how specific data columns are modified throughout the order lifecycle, and provides troubleshooting steps for common issues.

Workflow Pipeline

The automation follows a strict, linear 5-step pipeline with no branches or filters. Every downstream step operates on the single monday.com item identified by the initial webhook.

flowchart TD
    A[1. Webhook Trigger] -->|event.pulseId| B["2. Get Column Values (monday.com)"]
    B -->|Raw Address text_mky5xz73| C[3. Python Parser]
    C -->|fullAddress| D["4. Google Geocoding API"]
    D -->|Lat / Long| E["5. Update Columns (monday.com)"]
  1. 1

    Catch Hook (Trigger)

    A raw webhook (hook_v2) receives a payload containing a monday.com item ID (event.pulseId). This is typically called by a button, automation, or manual test within the monday.com workspace.

  2. 2

    Get Column Values

    The workflow looks up the Orders board item matching the pulseId and retrieves its current column values. Crucially, it reads the raw address text stored in column text_mky5xz73.

  3. 3

    Format Address (Python)

    A Python script processes the raw address string. It strips control characters, extracts unit numbers, expands street suffixes (e.g., Ave to Avenue), applies smart title-casing, and filters out placeholder unit values (like "n/a" or "null"). It outputs a structured object containing streetOnly, unitOnly, city, state, zip, and fullAddress.

  4. 4

    Get Lat/Long (Google Geocoding)

    The cleaned fullAddress is sent to the Google Geocoding API. The search is strictly restricted to the United States and North Carolina (components=country:US|administrative_area:NC).

  5. 5

    Change Multiple Column Values

    The workflow writes the parsed data and geocodes back to the monday.com item. It populates a Location column with the coordinates, fills individual text columns for the address components, and clears out legacy status/color columns.

Hardcoded Credentials: The Google Geocoding API key in Step 4 is currently hardcoded directly in the request URL/headers rather than being pulled from a secure, stored variable.

Data Lineage: What Changes Column X?

If you need to know exactly what modifies a specific piece of data during the order lifecycle, refer to this mapping. Step 5 of this Zap is responsible for overwriting these monday.com columns.

monday.com ColumnPopulated ByTransformation Logic
Raw Address (text_mky5xz73)Python (fullAddress)Overwritten by the fully assembled, cleaned address. Doubles as both the input and output column.
StreetPython (streetOnly)Truncated at the last recognized street suffix (e.g., Street, Road). Trailing noise is discarded.
UnitPython (unitOnly)Extracted via markers (#, Apt, Ste) or house number suffixes (1613A). Placeholders (-, none, null) are explicitly dropped.
City / State / ZIPPython (city, state, zip)Split by commas from the raw string. State abbreviations and directional suffixes (NW, SE) are preserved in uppercase.
Location (Map)Google Geocoding APIPopulated with the resolved Latitude, Longitude, and Google's formatted address string.
Status / Color ColumnsHardcoded in Step 5Reset to a blank ("-") value or explicitly cleared to wipe out prior manual entries.

Despite the Python step being named "Format Address and Client Name", the code only parses address fields. No client-name logic is present in the current version of the script.

Troubleshooting Common Issues

If you are experiencing data anomalies on the Orders board, use the following guide to identify the root cause within the Zap lifecycle.

The address is not updating or geocoding at all.

Possible Causes:

  1. Zap is Paused: Check the Zapier dashboard. The action steps may be paused or disabled for testing.

  2. Webhook Failure: The monday.com automation or button that fires the webhook might be failing to send the pulseId.

  3. API Key Expired: The hardcoded Google Geocoding API key may have expired or hit its rate limit.

The unit or apartment number is missing from the final output.

Possible Causes:

  1. Unrecognized Format: The Python script looks for specific markers (#, Unit, Apt, Ste, Suite, Apartment, Lot) or a direct house number suffix. If the unit was entered in an unexpected format, the parser will miss it.

  2. Junk Filtered: If the unit was entered as -, none, n/a, or null, the Python script intentionally drops it so junk data isn't written to the board.

Valid text at the end of the street line is disappearing.

Possible Causes:
The Python parser is designed to truncate the street line at the last recognized street suffix (like Drive, Street, or Boulevard). If a user types "123 Main St Gate Code 1234", the script will discard everything after "St" as trailing noise.

Addresses outside of North Carolina are failing to geocode.

Possible Causes:
The Google Geocoding API call in Step 4 is hardcoded with a regional restriction: components=country:US|administrative_area:NC. Addresses outside of North Carolina will likely fail to resolve or return inaccurate coordinates until this parameter is made dynamic.

HPS
HPS © 2026 All rights reserved