# Network Elements Field Mapping Guide

This document maps shapefile fields to Verofy API fields for network_elements.

## Data Analysis Summary

**Source:** Map Project ID 15685
**Total Network Elements:** 263
**Date Retrieved:** 2025-12-09

## Shapefile Structure

From `network_elements.shp`:

| Field Name | Data Type | Sample Values |
|------------|-----------|---------------|
| Type | String | "Anchor", "Slack Coil" |
| Group 1 | String | "Zone 01" |
| Group 2 | String | null |
| Latitude | Float | 40.773628 |
| Longitude | Float | -124.158326 |
| UID | Integer | 0, 1, 2, ... |

## Verofy API Structure

From `map-element` API endpoint:

| Field Name | Data Type | Required | Sample Values |
|------------|-----------|----------|---------------|
| id | Integer | Auto | 202367 |
| mapProjectId | Integer | **Yes** | 15685 |
| name | String | **Yes** | "E-202367" |
| latitude | String | **Yes** | "40.773628" |
| longitude | String | **Yes** | "-124.158326" |
| typeId | Integer | **Yes** | 35 (Anchor), 7 (Slack Coil) |
| statusId | Integer | **Yes** | 1 (Planned), 2 (Complete) |
| group1 | String | No | "Zone 01" |
| group2 | String | No | null |
| manufacturer | String | No | null |
| size | String | No | null |
| description | String | No | null |
| locked | Integer | No | 0 (unlocked), 1 (locked) |
| custom | Integer | No | 0 |
| color | String | No | null |
| opacity | String | No | null |
| shapeId | Integer | No | null |
| styleSize | Integer | No | null |

## Field Mapping

### Direct Mappings

| Shapefile Field | API Field | Transformation |
|-----------------|-----------|----------------|
| Latitude | latitude | Convert float to string |
| Longitude | longitude | Convert float to string |
| Group 1 | group1 | Direct copy (string) |
| Group 2 | group2 | Direct copy (string) |

### Type Mapping (Lookup Required)

The shapefile `Type` field (string) must be mapped to API `typeId` (integer) using the MapElementType reference:

| Shapefile Type Value | API typeId | Type Name in Verofy |
|----------------------|------------|---------------------|
| "Anchor" | 35 | Anchor |
| "Slack Coil" | 7 | Slack Coil |
| "Railroad Crossing" | 8 | Railroad Crossing |
| "Water Crossing" | 10 | Water Crossing |
| "Road Crossing" | 11 | Road Crossing |
| "ILA" | 13 | ILA |
| "Gas Crossing" | 14 | Gas Crossing |
| "MPOE" | 15 | MPOE |
| "Bore Pit" | 16 | Bore Pit |
| "Marker Post" | 17 | Marker Post |
| "SFP" | 18 | SFP |
| "Midspan" | 21 | Midspan |
| "Storage Yard" | 23 | Storage Yard |
| "Router" | 25 | Router |
| "Switch" | 27 | Switch |
| "CPU" | 28 | CPU |
| "Regulatory Compliance" | 29 | Regulatory Compliance |
| "Resto - Pothole" | 31 | Resto - Pothole |
| "Resto - Seed" | 32 | Resto - Seed |
| "Resto - Asphalt" | 33 | Resto - Asphalt |
| "Riser" | 34 | Riser |

### Generated/Default Values

| API Field | Value | Notes |
|-----------|-------|-------|
| mapProjectId | User provided | Required parameter |
| name | "NE-{UID}" or "E-{UID}" | Generated from UID field |
| statusId | 1 | Default to "Planned" |
| locked | 0 | Default to unlocked |
| custom | 0 | Default value |

### Unused Shapefile Fields

| Field | Reason |
|-------|--------|
| UID | Used only to generate name field |

### Unused API Fields

These fields are set to null/0 by default unless specific data is available:

- manufacturer
- size
- description
- color
- opacity
- shapeId
- styleSize

## API Endpoint

**Endpoint:** `POST /v1/map-network-element/create`
**Authentication:** Bearer token required
**Success Response:** 201 Created

## Example API Request

```json
{
  "mapProjectId": 15685,
  "name": "E-202367",
  "latitude": "40.773628",
  "longitude": "-124.158326",
  "typeId": 35,
  "statusId": 1,
  "group1": "Zone 01",
  "group2": null,
  "locked": 0
}
```

## Implementation Notes

1. **Type Lookup:** The current `verofy_uploader.py` incorrectly maps `Type` to `type` (string field). It should map to `typeId` (integer) using the MapElementType reference lookup.

2. **Reference Data:** Load MapElementType references from `all_references.json` or create a dedicated reference file.

3. **Error Handling:** If a Type value from the shapefile is not found in the lookup table, either:
   - Log a warning and skip the record
   - Use a default typeId (e.g., 35 for Anchor)
   - Fail with a clear error message

4. **Name Generation:** Consider using UID to generate unique names like "E-{UID}" to match Verofy's naming convention.

## Status Reference

| statusId | Status Name | Description |
|----------|-------------|-------------|
| 1 | Planned | Element is planned but not yet complete |
| 2 | Complete | Element has been completed |

Default to statusId: 1 (Planned) for new imports.