# Location Management ## Overview This guide explains how to create and edit service locations for customers in the Kozy system. Locations represent physical addresses where services are performed. Each location can be linked to multiple customers with different relationship types (homeowner, tenant, etc.). The location management system includes: - **Google Places integration** for accurate address lookup - **Interactive map** with draggable markers for precise coordinates - **Existing location detection** to prevent duplicates - **Full address editing** capabilities --- ## Creating a New Location ### Step 1: Open the Add Location Dialog 1. Navigate to the customer's profile 2. Click the **"Add Location"** button in the locations section [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763648285976-12-22-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763648285976-12-22-pm.png) [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763648292620-14-55-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763648292620-14-55-pm.png) ### Step 2: Search for an Address 1. Type the address in the **Google Places search field** [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763648316707-19-36-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763648316707-19-36-pm.png) 2. Select the correct address from the autocomplete dropdown [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763650607639-54-08-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763650607639-54-08-am.png) 3. The system will automatically: - Parse the address into components (street, city, state, ZIP) - Retrieve GPS coordinates (latitude/longitude) - Search for existing matching locations [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763650638955-54-15-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763650638955-54-15-am.png) ### Step 3: Link to Existing Location (if found) If the system finds matching locations in the database: 1. **Review the matches** displayed in the [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763650935446-54-08-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763650935446-54-08-am.png) 2. **Select the correct location** (if applicable) [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763650950185-54-15-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763650950185-54-15-am.png) 3. **Choose the relationship type**: - Homeowner - Tenant - Price Matched - Fuel Payment Override - Service Payment Override [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763651162318-58-54-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763651162318-58-54-am.png) 4. Click **"Link Customer"** [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763651331197-54-20-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763651331197-54-20-am.png) > **Note:** Linking to an existing location maintains data consistency and prevents duplicate addresses in the system. ### Step 4: Create a New Location (if no matches) If no existing locations are found, or the matches are incorrect: [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659342129-11-39-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659342129-11-39-am.png) 1. Click **"Continue with Address"** 2. The **Edit Address Details** form will appear ### Step 5: Edit Address Details The form displays all address components with the following fields: [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659482886-12-02-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659482886-12-02-am.png) **Address Fields:** - **Street Number** (e.g., "123") - **Street*** (required, e.g., "Main St") - **City*** (required, e.g., "Springfield") - **State*** (required, e.g., "MA") - **ZIP Code** (e.g., "01101") **Coordinate Fields** (read-only): - **Latitude** (displayed with 8 decimal precision) - **Longitude** (displayed with 8 decimal precision) > **Required fields** are marked with an asterisk (*). ### Step 6: Adjust Location on Map An interactive Google Map displays below the form: [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659573982-12-02-am-copy.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659573982-12-02-am-copy.png) 1. **View the marker** at the initial coordinates from Google Places 2. **Drag the red marker** to adjust the exact location - This is useful when the address pin is slightly off - Only the coordinates update—address fields remain unchanged 3. **Use zoom controls** to get a better view > **Tip:** Accurate coordinates are important for route planning and service dispatch. ### Step 7: Select Relationship Type Choose how this location relates to the customer: [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659594246-27-09-am.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659594246-27-09-am.png) - **Homeowner** - Customer owns the property - **Tenant** - Customer rents/leases the property - **Price Matched** - Uses customer's pricing for this location - **Fuel Payment Override** - Custom fuel payment settings - **Service Payment Override** - Custom service payment settings ### Step 8: Create the Location [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659621690-12-02-am-copy-3.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659621690-12-02-am-copy-3.png) 1. **Review** all address details and coordinates 2. Click **"Create Location"** 3. The system will: - Create the new location in the database - Link it to the customer with the selected relationship type - Close the dialog - Refresh the customer's location list ### Canceling - Click **"Back to Search"** to return to the address search [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659894970-28-00-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659894970-28-00-pm.png) - Click **"Cancel"** to close the dialog without saving [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763659901292-28-06-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763659901292-28-06-pm.png) --- ## Editing an Existing Location ### Step 1: Open Location Settings 1. Navigate to the customer's profile [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763660692432-35-07-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763660692432-35-07-pm.png) 2. Find the location you want to edit [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763660863665-35-16-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763660863665-35-16-pm.png) 3. Click the **settings/gear icon** next to the location [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763660992196-35-22-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763660992196-35-22-pm.png) 4. The **Location Settings dialog** opens [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763661007865-35-41-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763661007865-35-41-pm.png) ### Step 2: Navigate to the Address Tab The Location Settings dialog has multiple tabs: [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662041941-35-41-pm-copy.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662041941-35-41-pm-copy.png) [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662080551-35-41-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662080551-35-41-pm.png) [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662112381-35-47-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662112381-35-47-pm.png) - Labels - Taxes - Customers - Notes - **Address** ← Select this tab ### Step 3: Review Current Address The Address tab displays: [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662181088-09-20-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662181088-09-20-pm.png) - Current full address (street, city, state, ZIP) - Current GPS coordinates (latitude/longitude) ### Step 4: Open the Edit Dialog Click **"Edit Address & Coordinates"** [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662210119-35-47-pm-copy.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662210119-35-47-pm-copy.png) The edit dialog opens with all fields pre-populated. ### Step 5: Modify Address Details **Editable Fields:** [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662230181-35-58-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662230181-35-58-pm.png) - Street Number - Street (required) - City (required) - State (required) - ZIP Code - Latitude (updated by dragging map marker) - Longitude (updated by dragging map marker) **Making Changes:** 1. **Type directly** in any address field to update it 2. **Drag the map marker** to adjust coordinates precisely 3. **Zoom the map** for better accuracy > **Important:** When you drag the marker, only the latitude/longitude change. The address fields do NOT auto-update to maintain your manual entries. ### Step 6: Save Changes [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662362935-35-58-pm-copy.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662362935-35-58-pm-copy.png) 1. **Review** all modifications 2. Click **"Update Location"** 3. The system will: - Update the location in the database - Close the edit dialog - Refresh the Location Settings dialog - Show a success message ### Canceling Click **"Cancel"** to close the dialog without saving changes. [![](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/scaled-1680-/image-1763662476859-13-33-pm.png)](https://docs-kozyops-com-uploads.s3.amazonaws.com/uploads/images/gallery/2025-11/image-1763662476859-13-33-pm.png) --- ## Best Practices ### Address Entry ✅ **Do:** - Use Google Places autocomplete for initial address lookup - Verify the address components are correct - Check that city, state, and ZIP are properly filled - Use standard postal abbreviations (e.g., "St" not "Street") ❌ **Don't:** - Manually type addresses without using Google Places first - Leave required fields empty - Use non-standard address formats - Enter apartment numbers in the street number field ### Coordinate Adjustment ✅ **Do:** - Zoom in on the map before adjusting the marker - Drag the marker to the exact building/entrance location - Use satellite view (if available) for precision - Verify coordinates match the visible location ❌ **Don't:** - Skip coordinate adjustment for rural/ambiguous addresses - Place markers on roads instead of buildings - Ignore coordinate discrepancies ### Linking vs. Creating ✅ **Do:** - Always review existing location matches before creating new ones - Link to existing locations when the address matches exactly - Consider minor variations (Apt 1 vs Unit 1) as the same location - Use different relationship types for the same location when appropriate ❌ **Don't:** - Create duplicate locations for the same address - Ignore existing location matches without reviewing them - Link to locations with different addresses --- ## Common Scenarios ### Scenario 1: Multiple Customers at One Address **Example:** A landlord owns a building, and tenants also need service. **Solution:** 1. Create the location linked to the landlord as "Homeowner" 2. For each tenant, open the Add Location dialog 3. Search for the same address 4. Select the existing location from matches 5. Link each tenant as "Tenant" **Result:** One location with multiple customer relationships. ### Scenario 2: Google Places Returns Wrong Coordinates **Example:** Address autocomplete works, but the map marker is 100 feet off. **Solution:** 1. Proceed with the Google Places address 2. Click "Continue with Address" 3. Zoom in on the interactive map 4. Drag the marker to the correct building location 5. Create/update the location with accurate coordinates ### Scenario 3: Address Not Found in Google Places **Example:** New construction or rural address not in Google's database. **Solution:** 1. Find the closest known address in Google Places 2. Click "Continue with Address" 3. Manually edit all address fields to the correct values 4. Drag the map marker to the approximate location 5. Create the location > **Note:** For addresses without Google data, you may need to manually enter latitude/longitude from another source or estimate using the map. ### Scenario 4: Need to Fix Typo in Existing Address **Example:** Street name misspelled or wrong ZIP code. **Solution:** 1. Open Location Settings for the affected location 2. Go to the "Address" tab 3. Click "Edit Address & Coordinates" 4. Correct the typo in the appropriate field 5. Click "Update Location" **Result:** The address is corrected for all customers linked to this location. --- ## Field Reference ### Address Component Fields | Field | Required | Format | Example | Notes | |-------|----------|--------|---------|-------| | Street Number | No | Numeric or alphanumeric | "123", "123A" | Leave empty if N/A | | Street | Yes | Text | "Main St" | Use standard abbreviations | | City | Yes | Text | "Springfield" | Full city name | | State | Yes | 2-letter code | "MA" | Uppercase state abbreviation | | ZIP Code | No | 5 or 9 digits | "01101", "01101-1234" | Include ZIP+4 if known | | Latitude | Yes | Decimal degrees | "42.101234" | Auto-filled, read-only in form | | Longitude | Yes | Decimal degrees | "-72.589876" | Auto-filled, read-only in form | ### Relationship Types | Type | Use Case | Billing Impact | |------|----------|----------------| | Homeowner | Property owner receiving service | Uses customer's default billing | | Tenant | Renter/lessee receiving service | Uses customer's default billing | | Price Matched | Special pricing applies | Uses custom pricing for this location | | Fuel Payment Override | Custom fuel billing | Overrides default fuel payment terms | | Service Payment Override | Custom service billing | Overrides default service payment terms | --- ## Troubleshooting ### "No matching locations found" appears immediately **Cause:** The address search didn't complete or returned no database matches. **Solution:** This is normal for new addresses. Click "Continue with Address" to proceed with creating a new location. ### Map marker won't drag **Cause:** Map hasn't fully loaded or browser issue. **Solution:** 1. Wait a few seconds for the map to fully render 2. Try zooming in/out 3. Refresh the browser if problem persists ### Required field validation errors **Cause:** Street, City, or State fields are empty. **Solution:** 1. Review the error message 2. Fill in all required fields (marked with *) 3. Ensure no fields are blank or contain only spaces ### Address fields show wrong information after Google search **Cause:** Google Places parsed the address incorrectly. **Solution:** 1. Click "Continue with Address" 2. Manually correct any incorrect fields 3. Proceed with creating the location ### Can't find the edit button **Cause:** Looking in the wrong location. **Solution:** 1. Open the Location Settings dialog (gear icon next to location) 2. Click the "Address" tab at the top 3. The "Edit Address & Coordinates" button is in the center panel --- ## Tips for Efficiency 1. **Use keyboard shortcuts**: Tab through form fields quickly 2. **Zoom before dragging**: Zoom in on the map before adjusting markers for precision 3. **Batch similar addresses**: When adding multiple locations in the same area, adjust map zoom once and keep it 4. **Review matches carefully**: Linking takes seconds; creating duplicates causes long-term issues 5. **Verify on save**: Always review the success message to confirm the operation completed --- ## Related Documentation - [Customer Management Guide](./customer-management.md) - [Service Ticket Creation](./service-tickets.md) - [Route Planning](./route-planning.md) --- *Last updated: October 24, 2025*