Daehan Lim

PlaceFinder - Location Search App

📝 Overview

📌 App Introduction: Mobile app for finding nearby places using Naver Local Search API and GPS location services
🕒 Duration: April 20, 2025 ~ April 22, 2025 (3 days)
📱 Platform: Flutter cross-platform app (iOS, Android)
👥 Team Size: 1 developer (Personal project)
💼 Role: Entire app UI/UX design & development, API integration
🛠️ Key Technologies: Flutter Dart Naver Local API VWorld API Riverpod Geolocator InAppWebView URL Launcher Dio
🔗 GitHub: daehan-lim/flutter-place-finder

📖 Project Description

PlaceFinder helps users discover nearby places by searching by place names or addresses. The app uses Naver Local Search API and VWorld API to provide GPS-based location search and supports seamless redirection to popular map applications. Users can quickly explore local businesses, restaurants, and points of interest while accessing detailed information through in-app web view integration.

🛠️ Tech Stack

📋 Project Structure

├── app/                               # App configuration and setup files
│   ├── constants/                     # App-wide constant definitions
│   │   ├── app_colors.dart            # Color constants
│   │   ├── app_constants.dart         # General app constants
│   │   └── app_styles.dart            # Style definitions
│   ├── app_providers.dart             # Riverpod provider setup
│   └── theme.dart                     # App theme configuration
│
├── core/                              # Core functionality and common utilities
│   ├── exceptions/                    # App-wide exception classes
│   │   └── data_exceptions.dart       # Data-related exception classes
│   ├── services/                      # External service integrations
│   │   └── map_launcher_service.dart
│   └── utils/                         # Helper functions and utility classes
│       ├── geolocator_util.dart
│       ├── snackbar_util.dart
│       └── string_format_utils.dart
│
├── data/                              # Data layer and data access
│   ├── dto/                           # Data Transfer Objects
│   │   ├── naver_place_dto.dart
│   │   └── vworld_district_dto.dart
│   ├── model/                         # Data models
│   │   └── place.dart
│   ├── network/                       # Network communication
│   │   └── dio_clients.dart
│   └── repository/                    # Repository implementations
│       └── location_repository.dart
│
├── ui/                                # User interface
│   ├── pages/                         # App screens
│   │   ├── home/                      # Home screen
│   │   │   ├── home_page.dart
│   │   │   ├── home_view_model.dart
│   │   │   └── widgets/
│   │   │       └── home_list_item.dart
│   │   └── web/                       # WebView screen
│   │       ├── place_web_page.dart
│   │       └── place_web_page_view_model.dart
│   └── widgets/                       # Common widgets
│       └── error_layout.dart
│
└── main.dart                          # App entry point

🎯 Key Features

Place Search: Search for locations by entering place names or addresses through Naver Local Search API
GPS Location Search: Find nearby places using current GPS location with one-tap access
Detailed Place Information: Click on any search result to view detailed information through the place’s web page
Map App Integration: Launch places directly in device map apps (Google Maps, Apple Maps, Naver Map, etc.)
In-App Naver Search: Browse Naver search results within the app using Custom Tabs (Android) and SFSafariViewController (iOS)

🌟 Implementation & Achievements

Real-time Location-Based Search

Integrated Geolocator for GPS coordinate acquisition with VWorld API to automatically identify user’s current administrative district
Implemented automatic nearby place loading on app startup to enhance user convenience with immediate local results
Built reliable location detection with location permission handling and exception management

Naver Local Search API and VWorld API Integration

Implemented secure API communication through Bearer Token authentication and Dio HTTP client
Processed place names, categories, addresses, and links with HTML tag cleaning and string formatting utilities
Supported coordinate-to-address conversion via VWorld API for accurate location identification
Configured BaseOptions for consistent HTTP settings with 10-second connection/reception timeout and debug logging through LogInterceptor

Native App Integration and User Experience Enhancement

Platform-Specific Map App Integration
- Android: Implements Geo URI scheme allowing users to choose from installed map apps (Google Maps, Naver Map, KakaoMap)
- iOS: Detects Naver Map installation and automatically falls back to Apple Maps when unavailable
- Implemented URL Launcher integration for smooth transitions to map applications
- Added ‘Search on Naver’ buttons to each place listing for accessing additional details within the app
InAppWebView-Based Detailed Information Access
- Implemented mobile-optimized web page loading with Custom User Agent configuration
- Improved user wait time perception through loading indicators and error handling
- Provided integrated in-app experience using InAppBrowserView mode for Naver search integration

Robust Exception Handling and User Feedback

Layered Exception Handling System
- Implemented custom exception classes including ApiException, NetworkException, EnvFileException for specific scenarios
- Provided intuitive error messages for network connection errors, no search results, missing environment variables, etc.
- Optimized user notification experience with duplicate snackbar prevention logic
- Implemented input validation to block empty search queries and prevent duplicate API requests during active searches, reducing unnecessary network calls
- Improved user feedback for place details by preventing access to invalid or empty links and displaying snackbar notifications
User-Friendly UI/UX Implementation
- Added search bar with clear button, GPS icon, and loading indicators for better user interaction
- Enhanced readability by providing Tooltip for long addresses
- Implemented card-style list items using InkWell effects and shadows
- Added automatic keyboard hiding on screen touch through GestureDetector for better user convenience

Development Efficiency and Code Quality

Riverpod-Based State Management
- Implemented testable architecture through Provider pattern and dependency injection
- Achieved consistent management of loading, error, and data states using AsyncValue
- Ensured data integrity and minimized external API dependencies through separation of DTO and Model
Environment Variable Security Management
- Secured API keys and separated environment-specific configurations using flutter_dotenv
- Provided a .env.example file to guide development environment configuration
Reusable Component Design
- Implemented independent widget components including HomeListItem, MessageLayout
- Eliminated code duplication through common utility classes like StringFormatUtils, SnackbarUtil
- Ensured design consistency through unified app theme file and color system

🌱 Problem Solving

iOS Map App Integration Silent Failure

Problem
On iOS, when Naver Map is not installed and launchUrl() is called with the nmap:// custom scheme, it fails silently without any response. The Apple Maps fallback configured with try/catch never executes, leaving users with no feedback or alternative action.
Initial Approach and Reasoning
- I had experienced reliability issues with canLaunchUrl() in the Android implementation. It would return false even for executable geo: URIs:
```
if (await canLaunchUrl(Uri.parse('geo:0,0?q=$encoded'))) {
  // Would return false despite being executable
}
```
- After encountering this Android behavior, I assumed canLaunchUrl() would be equally unreliable on iOS, so I used try/catch for failure handling on both platforms

Why the Initial Solution Failed

static Future<void> openInMap(String queryAddress) async {
  if (Platform.isIOS) { 
    try {
      await launchUrl(naverUri, mode: LaunchMode.externalApplication);
    } catch (e) {
      // This catch block never executes on iOS
      final appleUri = Uri.parse('http://maps.apple.com/?q=$encoded');
      await launchUrl(appleUri, mode: LaunchMode.externalApplication);
      
    }
  }
}

The approach failed because iOS launchUrl() doesn’t throw exceptions for unavailable apps - it just silently does nothing, so the catch block never executes and Apple Maps never launches.

Platform-Specific Behavior Analysis
After reviewing documentation and GitHub issues, I discovered the key differences:
- iOS: Fails silently when no app can handle the URL scheme, requiring pre-validation with canLaunchUrl()
- Android: Exception-based handling works reliably for standard schemes like geo:

Final Solution
Implemented platform-specific handling that works with each OS’s characteristics:

static Future<void> openInMap(String queryAddress) async {
  if (Platform.isIOS) { 
    final naverUri = Uri.parse('nmap://search?query=$encoded&appname=$appName');
    if (await canLaunchUrl(naverUri)) {
      await launchUrl(naverUri, mode: LaunchMode.externalApplication);
    } else {
      // Naver Map unavailable, use Apple Maps
      final appleUri = Uri.parse('http://maps.apple.com/?q=$encoded');
      if (await canLaunchUrl(appleUri)) {
        await launchUrl(appleUri, mode: LaunchMode.externalApplication);
      }
    }
  } else {
    // Android: Keep try/catch approach for geo URIs
    try {
      await launchUrl(geoUri, mode: LaunchMode.externalApplication);
    } catch (e) {
      log('Could not launch map: $e');
    }
  }
}

Key Insights
- Platform-Specific Behavior: Realized the importance of understanding each platform’s unique handling of external app integration in cross-platform development. Experiences from one platform should not be directly applied to another
- Importance of canLaunchUrl() on iOS: Unlike the reliability issues on Android, it’s an essential pre-check tool on iOS
- Debugging Silent Failures: Learned approaches for troubleshooting issues where no exceptions occur
Results
Resolved issue and achieved reliable map app integration on both platforms: iOS users get Naver Map when available, with Apple Maps fallback, while Android users can choose from their installed map applications