Step 5 Where is the listing located

Capture and validate the property’s precise address and geolocation. Enables accurate search placement, pricing relevance, regulation checks, and channel distribution setup.

UX Flow (What the user sees)

• A Google-powered address input with autocomplete and an interactive map.

• Typing an address suggests places; picking a place fills address fields (street, city, zipcode, state/country code) and centers the map.

• Validation enforces that an address and coordinates are provided before proceeding.

• On success, the flow advances to “[[Step 6 - Confirm your address]].

![[Desktop 4.png]]

System Flow (How it works)

sequenceDiagram
  actor Landlord
  participant Frontend as Web App (Next.js)
  participant Backend as API (NestJS)
  participant DB as Database
  participant External as Google Maps

  Landlord->>Frontend: Type address / select suggested place
  Frontend->>External: Google Maps Autocomplete (client-side)
  External-->>Frontend: Place details (address, lat/lng, components)
  Frontend->>Frontend: Fill form fields (street, city, zipcode, state, lat, lng)

  Landlord->>Frontend: Click "Next"
  Frontend->>Frontend: Validate required fields (address, lat, lng)

  Frontend->>Backend: PATCH /api/properties/{propertyId} { address: { street, city, zipcode, state, latitude, longitude } }
  Backend->>DB: Update properties.address
  Backend-->>Frontend: 200 OK

  Frontend->>Backend: PATCH /api/users/{userId} { onboardingStep: user.onboardingStep + 1 }
  Backend->>DB: Update users.onboardingStep
  Backend-->>Frontend: 200 OK

  Frontend->>Backend: GET /api/properties (refetch)
  Backend-->>Frontend: 200 OK { properties: [...] }
  Frontend->>Frontend: Advance to "Confirm your address"

APIs Called

• PATCH /api/properties/{propertyId}

  • Payload:

    • { address: { street: string, city?: string, zipcode?: string, state?: string, latitude: number, longitude: number } }

  • Response: Updated property

  • Errors: 400 (validation), 401/403 (auth), 404 (property not found), 500

  • Idempotency: Safe for identical payload

• PATCH /api/users/{userId}

  • Payload: { onboardingStep: number } (current + 1)

  • Response: Updated user

  • Errors: 400, 401/403, 404, 500

• GET /api/properties

  • Purpose: Refresh property cache after update

Integrations

• Google Maps (client-side): Autocomplete, place selection, and geocoded lat/lng; extracted to fill address fields.

QA Checklist

• Visual

  • Map renders; autocomplete suggestions appear

  • Selecting a place centers map and fills fields

• Behavior

  • Next disabled/blocked until address and coordinates are present

  • On success: PATCH property, PATCH user step, refetch properties, advance to Confirm Address

• Data

  • Verify property address.* fields persist correctly (including lat/lng)

  • Verify onboardingStep increments once

• Negative

  • Simulate API errors: user remains on step; no step increment/navigation

  • Handle places without zipcode/state gracefully