Add MongoDB support for Geonames data import

- Implement MongoDB converters for postal codes and gazetteer data
- Add new CLI options for MongoDB connection and import
- Create geospatial indexes for efficient querying
- Update README with MongoDB usage examples and documentation
- Add MongoDB library as a suggested dependency in composer.json

Author: parsilver

README.md

@@ -11,6 +11,7 @@ A PHP library for downloading and converting Geonames data. This library provide
 - Download postal codes data for specific countries or all countries
 - Download detailed geographical data (Gazetteer) including administrative divisions
 - Convert data to JSON format with proper structure
+- Import data directly to MongoDB with proper indexing
 - Memory-efficient processing for large datasets
 - Progress bars for all operations
 - Support for filtering by feature types (for Gazetteer data)
@@ -39,7 +40,10 @@ Download postal codes for all countries:
 
 Options:
 - `--output (-o)`: Output directory (default: ./data)
-- `--format (-f)`: Output format (default: json)
+- `--format (-f)`: Output format (default: json, options: json, mongodb)
+- `--mongodb-uri`: MongoDB connection URI (default: mongodb://localhost:27017)
+- `--mongodb-db`: MongoDB database name (default: geonames)
+- `--mongodb-collection`: MongoDB collection name (default: postal_codes)
 
 The postal codes data includes:
 - Country code
@@ -65,8 +69,11 @@ Download geographical data for all countries:
 
 Options:
 - `--output (-o)`: Output directory (default: ./data)
-- `--format (-f)`: Output format (default: json)
+- `--format (-f)`: Output format (default: json, options: json, mongodb)
 - `--feature-class (-c)`: Filter by feature class (default: P)
+- `--mongodb-uri`: MongoDB connection URI (default: mongodb://localhost:27017)
+- `--mongodb-db`: MongoDB database name (default: geonames)
+- `--mongodb-collection`: MongoDB collection name (default: gazetteer)
 
 Available feature classes:
 - `A`: Country, state, region
@@ -93,7 +100,9 @@ The Gazetteer data includes:
 
 ## Data Structure
 
-### Postal Codes JSON Structure
+### Postal Codes Structure
+
+#### JSON Format
 
 ```json
 {
@@ -112,7 +121,40 @@ The Gazetteer data includes:
 }
 ```
 
-### Gazetteer JSON Structure
+#### MongoDB Format
+
+In MongoDB, the postal codes data has the same structure as JSON but includes an additional `location` field for geospatial queries:
+
+```json
+{
+    "country_code": "TH",
+    "postal_code": "10200",
+    "place_name": "Bang Rak",
+    "admin_name1": "Bangkok",
+    "admin_code1": "10",
+    "admin_name2": "",
+    "admin_code2": "",
+    "admin_name3": "",
+    "admin_code3": "",
+    "latitude": 13.7235,
+    "longitude": 100.5147,
+    "accuracy": 1,
+    "location": {
+        "type": "Point",
+        "coordinates": [100.5147, 13.7235]
+    }
+}
+```
+
+The MongoDB collection is indexed for efficient queries:
+- Compound index on `country_code` and `postal_code` (unique)
+- Index on `country_code`
+- Index on `postal_code`
+- Geospatial index on `location`
+
+### Gazetteer Structure
+
+#### JSON Format
 
 ```json
 {
@@ -140,6 +182,91 @@ The Gazetteer data includes:
 }
 ```
 
+#### MongoDB Format
+
+In MongoDB, the gazetteer data has the same structure as JSON but includes an additional `location` field for geospatial queries:
+
+```json
+{
+    "geoname_id": 1609350,
+    "name": "Bangkok",
+    "ascii_name": "Bangkok",
+    "alternate_names": ["Krung Thep", "กรุงเทพมหานคร"],
+    "latitude": 13.75,
+    "longitude": 100.51667,
+    "location": {
+        "type": "Point",
+        "coordinates": [100.51667, 13.75]
+    },
+    "feature_class": "P",
+    "feature_code": "PPLC",
+    "country_code": "TH",
+    "cc2": [],
+    "admin1_code": "40",
+    "admin1_name": "Bangkok",
+    "admin2_code": "",
+    "admin2_name": "",
+    "admin3_code": "",
+    "admin4_code": "",
+    "population": 5104476,
+    "elevation": 2,
+    "dem": 4,
+    "timezone": "Asia/Bangkok",
+    "modification_date": "2023-01-12"
+}
+```
+
+The MongoDB collection is indexed for efficient queries:
+- Unique index on `geoname_id`
+- Index on `country_code`
+- Index on `feature_class`
+- Index on `feature_code`
+- Text index on `name` and `ascii_name`
+- Geospatial index on `location`
+
+## MongoDB Usage Examples
+
+### Finding locations near a point
+
+```php
+$client = new MongoDB\Client('mongodb://localhost:27017');
+$collection = $client->geonames->gazetteer;
+
+// Find all places within 5km of Bangkok
+$result = $collection->find([
+    'location' => [
+        '$near' => [
+            '$geometry' => [
+                'type' => 'Point',
+                'coordinates' => [100.51667, 13.75] // [longitude, latitude]
+            ],
+            '$maxDistance' => 5000 // 5km in meters
+        ]
+    ]
+]);
+
+foreach ($result as $place) {
+    echo $place['name'] . ' - ' . $place['feature_code'] . PHP_EOL;
+}
+```
+
+### Finding postal codes by country
+
+```php
+$client = new MongoDB\Client('mongodb://localhost:27017');
+$collection = $client->geonames->postal_codes;
+
+// Find all postal codes in Bangkok, Thailand
+$result = $collection->find([
+    'country_code' => 'TH',
+    'admin_name1' => 'Bangkok'
+]);
+
+foreach ($result as $postalCode) {
+    echo $postalCode['postal_code'] . ' - ' . $postalCode['place_name'] . PHP_EOL;
+}
+```
+
 ## License
 
 This package is open-sourced software licensed under the MIT license.

composer.json

@@ -49,7 +49,8 @@
     },
     "suggest": {
         "guzzlehttp/guzzle": "Required to download the data from Geonames.",
-        "ext-zip": "Required to extract the downloaded data."
+        "ext-zip": "Required to extract the downloaded data.",
+        "mongodb/mongodb": "Required for MongoDB output format support."
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

src/Console/Commands/DownloadGazetteerCommand.php

@@ -5,6 +5,7 @@
 namespace Farzai\Geonames\Console\Commands;
 
 use Farzai\Geonames\Converter\GazetteerConverter;
+use Farzai\Geonames\Converter\MongoDBGazetteerConverter;
 use Farzai\Geonames\Downloader\GazetteerDownloader;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
@@ -35,8 +36,11 @@ protected function configure(): void
         $this
             ->addArgument('country', InputArgument::OPTIONAL, 'Country code (e.g., TH, US) or "all" for all countries')
             ->addOption('output', 'o', InputOption::VALUE_REQUIRED, 'Output directory', getcwd().'/data')
-            ->addOption('format', 'f', InputOption::VALUE_REQUIRED, 'Output format (json)', 'json')
-            ->addOption('feature-class', 'c', InputOption::VALUE_REQUIRED, 'Filter by feature class (A,H,L,P,R,S,T,U,V)', 'P');
+            ->addOption('format', 'f', InputOption::VALUE_REQUIRED, 'Output format (json, mongodb)', 'json')
+            ->addOption('feature-class', 'c', InputOption::VALUE_REQUIRED, 'Filter by feature class (A,H,L,P,R,S,T,U,V)', 'P')
+            ->addOption('mongodb-uri', null, InputOption::VALUE_REQUIRED, 'MongoDB connection URI', 'mongodb://localhost:27017')
+            ->addOption('mongodb-db', null, InputOption::VALUE_REQUIRED, 'MongoDB database name', 'geonames')
+            ->addOption('mongodb-collection', null, InputOption::VALUE_REQUIRED, 'MongoDB collection name', 'gazetteer');
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
@@ -83,6 +87,41 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
             $output->writeln('<info>Data has been downloaded and converted successfully!</info>');
             $output->writeln(sprintf('<info>Output file: %s</info>', $jsonFile));
+        } elseif ($format === 'mongodb') {
+            $output->writeln('<info>Converting to MongoDB format...</info>');
+            
+            // Create MongoDB converter
+            $mongodbUri = $input->getOption('mongodb-uri');
+            $mongodbDb = $input->getOption('mongodb-db');
+            $mongodbCollection = $input->getOption('mongodb-collection');
+            
+            $mongoConverter = new MongoDBGazetteerConverter(
+                $mongodbUri,
+                $mongodbDb,
+                $mongodbCollection
+            );
+            $mongoConverter->setOutput($output);
+            
+            // Convert and import to MongoDB
+            $jsonFile = str_replace('.zip', '.json', $zipFile); // Dummy file name, not used
+            $mongoConverter->convert($zipFile, $jsonFile, $outputDir);
+            
+            // Remove ZIP file after conversion
+            unlink($zipFile);
+            
+            // Remove admin code files
+            if (file_exists($outputDir.'/admin1CodesASCII.txt')) {
+                unlink($outputDir.'/admin1CodesASCII.txt');
+            }
+            if (file_exists($outputDir.'/admin2Codes.txt')) {
+                unlink($outputDir.'/admin2Codes.txt');
+            }
+            
+            $output->writeln('<info>Data has been downloaded and imported to MongoDB successfully!</info>');
+            $output->writeln(sprintf('<info>MongoDB: %s.%s</info>', $mongodbDb, $mongodbCollection));
+        } else {
+            $output->writeln(sprintf('<error>Unsupported format: %s</error>', $format));
+            return Command::FAILURE;
         }
 
         return Command::SUCCESS;

src/Console/Commands/DownloadPostalCodesCommand.php

@@ -4,6 +4,7 @@
 
 namespace Farzai\Geonames\Console\Commands;
 
+use Farzai\Geonames\Converter\MongoDBPostalCodeConverter;
 use Farzai\Geonames\Converter\PostalCodeConverter;
 use Farzai\Geonames\Downloader\GeonamesDownloader;
 use Symfony\Component\Console\Command\Command;
@@ -35,7 +36,10 @@ protected function configure(): void
         $this
             ->addArgument('country', InputArgument::OPTIONAL, 'Country code (e.g., TH, US) or "all" for all countries')
             ->addOption('output', 'o', InputOption::VALUE_REQUIRED, 'Output directory', getcwd().'/data')
-            ->addOption('format', 'f', InputOption::VALUE_REQUIRED, 'Output format (json)', 'json');
+            ->addOption('format', 'f', InputOption::VALUE_REQUIRED, 'Output format (json, mongodb)', 'json')
+            ->addOption('mongodb-uri', null, InputOption::VALUE_REQUIRED, 'MongoDB connection URI', 'mongodb://localhost:27017')
+            ->addOption('mongodb-db', null, InputOption::VALUE_REQUIRED, 'MongoDB database name', 'geonames')
+            ->addOption('mongodb-collection', null, InputOption::VALUE_REQUIRED, 'MongoDB collection name', 'postal_codes');
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
@@ -74,6 +78,33 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
             $output->writeln('<info>Data has been downloaded and converted successfully!</info>');
             $output->writeln(sprintf('<info>Output file: %s</info>', $jsonFile));
+        } elseif ($format === 'mongodb') {
+            $output->writeln('<info>Converting to MongoDB format...</info>');
+            
+            // Create MongoDB converter
+            $mongodbUri = $input->getOption('mongodb-uri');
+            $mongodbDb = $input->getOption('mongodb-db');
+            $mongodbCollection = $input->getOption('mongodb-collection');
+            
+            $mongoConverter = new MongoDBPostalCodeConverter(
+                $mongodbUri,
+                $mongodbDb,
+                $mongodbCollection
+            );
+            $mongoConverter->setOutput($output);
+            
+            // Convert and import to MongoDB
+            $jsonFile = str_replace('.zip', '.json', $zipFile); // Dummy file name, not used
+            $mongoConverter->convert($zipFile, $jsonFile);
+            
+            // Remove ZIP file after conversion
+            unlink($zipFile);
+            
+            $output->writeln('<info>Data has been downloaded and imported to MongoDB successfully!</info>');
+            $output->writeln(sprintf('<info>MongoDB: %s.%s</info>', $mongodbDb, $mongodbCollection));
+        } else {
+            $output->writeln(sprintf('<error>Unsupported format: %s</error>', $format));
+            return Command::FAILURE;
         }
 
         return Command::SUCCESS;