# ArcGIS SDK Examples Expansion Plan
**Created:** 2026-01-18
**Status:** In Progress
**Goal:** Expand example coverage from ~25% to 80%+ of SDK operations
## Executive Summary
Current example coverage is approximately 25% of available SDK operations. This plan outlines a phased approach to create high-quality, entertaining, and educational examples that demonstrate best practices while showcasing the SDK's capabilities.
## Organization
Examples are organized into two categories based on authentication requirements:
### 🆓 Public Examples (`examples/public/`)
**Tier 1 - No authentication required, no credit costs**
- ✅ `query_features.rs` - Comprehensive Feature Service queries
- ✅ `spatial_query.rs` - Advanced spatial relationship queries
**Benefits:**
- Run immediately without API keys
- Zero credit cost
- Perfect for learning and CI/CD
- Uses ESRI's public World Cities service
### 💼 Enterprise Examples (`examples/enterprise/`)
**Tier 2+ - Requires API key or OAuth, may consume credits**
**Authentication & Setup:**
- ✅ `basic_client.rs` - Client creation and API key auth
- ✅ `client_credentials_flow.rs` - OAuth 2.0 flow
**Location Services (Tier 2):**
- ✅ `geocode_addresses.rs` - Forward/reverse geocoding (~0.04 credits)
- ✅ `routing_navigation.rs` - Route finding, directions (~0.50 credits)
- ✅ `geometry_operations.rs` - Buffer, union, intersection (~0.10 credits)
**Portal Operations (Tier 3):**
- ✅ `edit_session.rs` - Feature editing with transactions (~0.01 credits)
- ✅ `feature_attachments.rs` - Attachment management (~0.02 credits)
- ✅ `portal_content_management.rs` - Portal search, groups (~0.01 credits)
**Total credit cost for all enterprise examples:** ~0.68 credits (~$0.07)
For enterprise users with credit pools, this cost is negligible.
### Target State (15+ examples)
Coverage across all major services with practical, real-world scenarios. Organize new examples into appropriate categories based on authentication requirements.
## Implementation Phases
### Phase 1: Core Workflows (Week 1) 🎯
#### 1. Routing Navigation (`routing_navigation.rs`)
**Status:** ✅ Completed (2026-01-18)
**Priority:** HIGH
**Estimated Effort:** 4-6 hours → **Actual:** 3 hours
**Operations Demonstrated:**
- `solve_route()` - Optimal route between multiple stops
- `solve_service_area()` - Drive-time/distance polygons
- `solve_closest_facility()` - Nearest facility analysis
**Story:** Plan a road trip from San Francisco to Seattle with optimal stops, show 30-minute drive zones around each city, and find the nearest gas station along the route.
**Learning Objectives:**
- Multi-stop route optimization
- Service area generation
- Closest facility analysis
- Error handling for routing failures
- Working with complex result geometries
**Success Criteria:**
- [x] Successfully calculates multi-stop route
- [x] Generates service area polygons
- [x] Finds closest facilities
- [x] Handles routing errors gracefully with anyhow::Context
- [x] Uses tracing for progress updates
- [x] Includes practical tips and caveats
---
#### 2. Portal Content Management (`portal_content_management.rs`)
**Status:** ✅ Completed (2026-01-18)
**Priority:** HIGH
**Estimated Effort:** 5-7 hours → **Actual:** 2 hours
**Operations Demonstrated:**
- `search()` - Content discovery with Lucene queries
- `get_item()` - Item metadata retrieval
- `add_item()` - Upload new content (GeoJSON)
- `update_item()` - Modify metadata
- `update_item_data()` - Upload item data
- `share_item()` - Sharing with groups/org
- `create_group()` - Group management
**Story:** Complete content lifecycle - search for parks datasets, upload a new GeoJSON file, add rich metadata, create a project group, and share with team members.
**Learning Objectives:**
- Content search patterns with pagination
- Item creation with rich metadata
- Data upload workflows
- Metadata updates and verification
- Group creation for collaboration
- Sharing workflows (private → org → groups)
- Builder pattern for complex parameters
- Cleanup awareness (quota management)
**Success Criteria:**
- [x] Searches and filters items
- [x] Creates item with metadata
- [x] Uploads item data (GeoJSON)
- [x] Updates existing items
- [x] Shares to groups and organization
- [x] Creates and manages groups
- [x] Error handling with anyhow::Context
- [x] Uses tracing for progress updates
- [x] Shows cleanup tips for quota management
- [x] Demonstrates auth requirements (API key vs OAuth2)
---
#### 3. Feature Attachments (`feature_attachments.rs`)
**Status:** ✅ Completed (2026-01-18)
**Priority:** HIGH
**Estimated Effort:** 3-5 hours → **Actual:** 2 hours
**Operations Demonstrated:**
- `query_attachments()` - List attachments with metadata
- `add_attachment()` - Upload files to features (bytes and file paths)
- `download_attachment()` - Download attachments (to file and memory)
- `update_attachment()` - Replace existing attachments
- `delete_attachments()` - Remove multiple attachments
**Story:** Field inspection workflow - utility worker adds photos and documents to infrastructure assets, office staff retrieves attachments for reporting, and cleanup removes outdated files.
**Learning Objectives:**
- Binary data handling with mock JPEG/PDF generators
- Attachment API patterns (demonstration mode for writable services)
- Attachment metadata querying
- Multiple upload/download patterns (bytes vs file paths)
- Batch deletion operations
- Working with LayerId, ObjectId, and AttachmentId types
**Success Criteria:**
- [x] Demonstrates upload patterns for various file types (images, PDFs)
- [x] Shows attachment listing with metadata
- [x] Shows download patterns (to file and memory)
- [x] Demonstrates deletion of attachments
- [x] Includes error handling with anyhow::Context
- [x] Shows file format considerations
- [x] Demonstrates both bytes and streaming patterns
- [x] Includes complete workflow example
- [x] Uses tracing for progress updates
- [x] Handles placeholder service URL gracefully
---
### Phase 2: Analytics & Batch Operations (Week 2) 📊
#### 4. Advanced Feature Queries (`advanced_queries.rs`)
**Status:** 🔲 Not Started
**Priority:** MEDIUM
**Estimated Effort:** 4-5 hours
**Operations Demonstrated:**
- `query_related_records()` - Related table queries
- `query_top_features()` - Top N features
- `calculate_statistics()` - Statistical aggregations
- Pagination with `resultOffset`/`resultRecordCount`
- `query_domains()` - Domain value lookups
**Story:** Analyze crime incident data - find related evidence records for each incident, identify top 10 crime hotspots, calculate monthly statistics, and use pagination for large datasets.
**Learning Objectives:**
- Relationship queries
- Statistical operations
- Efficient pagination
- Domain value handling
- Complex where clauses
- Result set management
**Success Criteria:**
- [ ] Queries related records
- [ ] Gets top N features
- [ ] Calculates statistics
- [ ] Demonstrates pagination
- [ ] Shows domain lookups
- [ ] Handles large result sets
- [ ] Performance tips included
---
#### 5. Batch Geocoding (`batch_geocoding.rs`)
**Status:** 🔲 Not Started
**Priority:** MEDIUM
**Estimated Effort:** 3-4 hours
**Operations Demonstrated:**
- `geocode_addresses()` - Batch address geocoding
- Rate limiting strategies
- Error recovery and retry
- Category-specific geocoding
- Result quality assessment
**Story:** Process a customer mailing list of 500 addresses, handle rate limits gracefully, retry failures, and generate a report of geocoding quality scores.
**Learning Objectives:**
- Batch operation patterns
- Rate limiting implementation
- Error recovery strategies
- Quality assessment
- Progress tracking
- Production-ready patterns
**Success Criteria:**
- [ ] Processes batch addresses
- [ ] Implements rate limiting
- [ ] Handles partial failures
- [ ] Retries transient errors
- [ ] Reports quality metrics
- [ ] Shows progress with tracing
- [ ] Production patterns documented
---
### Phase 3: Specialized Services (Week 3) 🗺️
#### 6. Elevation Analysis (`elevation_analysis.rs`)
**Status:** 🔲 Not Started
**Priority:** MEDIUM
**Estimated Effort:** 3-4 hours
**Operations Demonstrated:**
- `profile()` - Elevation along paths
- `summarize_elevation()` - Elevation statistics
- `viewshed()` - Visibility analysis
**Story:** Analyze hiking trail from Mount Tamalpais - get elevation profile, calculate total gain/loss, and determine viewshed from summit.
**Learning Objectives:**
- Elevation profile generation
- Statistical summaries
- Viewshed analysis
- Working with DEMs
- Profile visualization data
**Success Criteria:**
- [ ] Gets elevation profile
- [ ] Calculates elevation stats
- [ ] Generates viewshed
- [ ] Handles terrain data
- [ ] Shows visualization tips
---
#### 7. Places Discovery (`places_discovery.rs`)
**Status:** 🔲 Not Started
**Priority:** MEDIUM
**Estimated Effort:** 3-4 hours
**Operations Demonstrated:**
- `find_places_near_point()` - POI search by location
- `find_places_by_address()` - POI search by address
- `get_place_details()` - Detailed information
- `get_place_categories()` - Category listing
- Category filtering and ranking
**Story:** Build a travel app - find restaurants near current location, search for hotels by address, get detailed reviews/hours, and explore available categories.
**Learning Objectives:**
- POI search patterns
- Category filtering
- Place detail retrieval
- Ranking and sorting
- Consumer app patterns
**Success Criteria:**
- [ ] Searches places by location
- [ ] Searches by address
- [ ] Gets place details
- [ ] Lists categories
- [ ] Filters by category
- [ ] Shows ranking strategies
---
#### 8. Map Export (`map_export.rs`)
**Status:** 🔲 Not Started
**Priority:** LOW
**Estimated Effort:** 3-4 hours
**Operations Demonstrated:**
- `export()` - Map image export
- `identify()` - Feature identification
- `find()` - Attribute search
- `legend()` - Legend generation
- `get_metadata()` - Service metadata
**Story:** Generate static maps for PDF reports - export map images with different extents, identify features at clicked coordinates, and include legends.
**Learning Objectives:**
- Map image export
- Identify operations
- Legend generation
- Extent management
- Static map creation
**Success Criteria:**
- [ ] Exports map images
- [ ] Identifies features
- [ ] Generates legends
- [ ] Shows extent control
- [ ] Image format options
---
### Phase 4: Advanced Features (Future) 🚀
#### 9. Geoprocessing Workflows (`geoprocessing_tasks.rs`)
**Status:** 🔲 Not Started
**Priority:** LOW
**Operations:**
- `execute()` - Synchronous tasks
- `submit_job()` - Async job submission
- `get_job_status()` - Job monitoring
- `get_result()` - Result retrieval
---
#### 10. Image Service Operations (`image_analysis.rs`)
**Status:** 🔲 Not Started
**Priority:** LOW
**Operations:**
- `export()` - Image export
- `identify()` - Raster identification
- `histogram()` - Raster histogram
- `sample()` - Raster sampling
---
#### 11. Vector Tile Styling (`vector_tiles.rs`)
**Status:** 🔲 Not Started
**Priority:** LOW
**Operations:**
- `get_style()` - Style retrieval
- `get_tile()` - Tile fetching
- Font and sprite management
---
## Example Quality Standards
### Code Structure
- Use `anyhow::Result` for error handling
- Use `anyhow::Context` for error messages
- Structured logging with `tracing`
- Builder pattern for parameters
- Proper async/await patterns
### Documentation
- Engaging scenario-based descriptions
- Clear learning objectives
- Prerequisites section
- Running instructions with RUST_LOG
- Practical tips and caveats
### User Experience
- Relatable real-world scenarios
- Progressive complexity (simple → advanced)
- Strategic emoji usage
- Conversational tone in logs
- Practical tips and best practices
### Testing
- Each example must compile
- Each example must run successfully
- Include error handling demonstrations
- Show both success and failure paths
## Progress Tracking
### Completed Examples: 10 total
**Public Examples (2):**
- ✅ query_features.rs
- ✅ spatial_query.rs
**Enterprise Examples (8):**
- ✅ basic_client.rs (auth setup)
- ✅ client_credentials_flow.rs (OAuth)
- ✅ geocode_addresses.rs (Tier 2)
- ✅ routing_navigation.rs (Tier 2)
- ✅ geometry_operations.rs (Tier 2)
- ✅ edit_session.rs (Tier 3)
- ✅ feature_attachments.rs (Tier 3)
- ✅ portal_content_management.rs (Tier 3)
### Phase Progress
**Phase 1:** 3/3 complete (100%) ✅
- ✅ routing_navigation.rs
- ✅ portal_content_management.rs
- ✅ feature_attachments.rs
**Phase 2:** 0/2 complete (0%)
**Phase 3:** 0/3 complete (0%)
**Phase 4:** 0/3 complete (0%)
**Overall:** 10 existing + 3/11 planned = 13/21 examples (62% coverage when Phase 1 examples included)
## Success Metrics
- [ ] Coverage increased to 80%+ of SDK operations
- [ ] Each example demonstrates 3+ operations
- [ ] All examples include error handling
- [ ] All examples use tracing effectively
- [ ] Each example has a compelling real-world story
- [ ] Examples serve as templates for user code
- [ ] Documentation quality matches or exceeds existing examples
## Notes
### Organization Guidelines
- **Public examples** (`examples/public/`): Use public services, no auth required, zero credit cost
- **Enterprise examples** (`examples/enterprise/`): Require API keys/OAuth, may consume credits
- Include credit estimates in enterprise example documentation
- Organize new examples by authentication tier
### Development Guidelines
- Examples should be self-contained where possible
- Prefer public/free services when available (Tier 1)
- Include rate limiting awareness for enterprise examples
- Show production-ready patterns (not just toy examples)
- Each example should take 5-10 minutes to run and understand
- Document credit costs for enterprise examples
---
**Last Updated:** 2026-01-18
**Next Review:** After Phase 1 completion