PHPackages alimentalos/laravel\_cities - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. alimentalos/laravel\_cities ActiveLibrary[API Development](/categories/api) alimentalos/laravel\_cities =========================== Seed all countries/cities from geonames.org database. Searchable DB tree, ready to use API & a bonus vue.js component! v1.3.12(5y ago)013MITPHP Since Feb 28Pushed 5y agoCompare [ Source](https://github.com/Alimentalos/laravel_cities)[ Packagist](https://packagist.org/packages/alimentalos/laravel_cities)[ Docs](https://github.com/igaster/laravel_cities.git)[ RSS](/packages/alimentalos-laravel-cities/feed)WikiDiscussions master Synced yesterday READMEChangelog (1)Dependencies (3)Versions (20)Used By (0) [![License](https://camo.githubusercontent.com/589340e4d38c06303314e5b71c133ff2e3cadd15c677f1bfc9e8c11233b359a3/687474703a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d6f72616e67652e737667)](https://tldrlegal.com/license/mit-license)[![Downloads](https://camo.githubusercontent.com/b803236aa75c82661210573d0d8ca2ee3a200475264a24a48988600d2cb621be/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696761737465722f6c61726176656c5f6369746965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/igaster/laravel_cities) Introduction ============ [](#introduction) What you get: - Deploy and use geonames.org (ex MaxCDN) database localy to query countries/cities - Get information like lattitude/longtityde, population etc - Optimized [DB tree structure](https://en.wikipedia.org/wiki/Nested_set_model) for searching and traversing the tree. - Provides an Eloquent model (geo) with multiple query-scopes to help you build your queries. - Exposes a simple API that you can use to create AJAX calls. (Eg search while typing etc). - A sample vue.js component that that can be inserted into your forms and provides a UI to pick a location What you dont get: - geoIP & Postalcodes (not included in free sets) - Map elements smaller than "3rd Administration Division" (=Cities) Instructions ============ [](#instructions) - Install with copmoser. Run: `composer require igaster/laravel_cities` The Service provider will be autodiscovered and registered by Laravel. If you are using Laravel version <5.5 then you must manually add the Service Provider in app.php: ``` 'providers' => [ //... Igaster\LaravelCities\GeoServiceProvider::class, ]; ``` - Create a folder `geo` into app's storage folder ('\\storage\\geo'). Download & unzip "hieararcy.txt" & "allCountries.txt" from geonames.org () \[Tip\] Quick script to download on your remote server with: ``` mkdir -p storage/geo && cd storage/geo wget http://download.geonames.org/export/dump/allCountries.zip && unzip allCountries.zip && rm allCountries.zip wget http://download.geonames.org/export/dump/hierarchy.zip && unzip hierarchy.zip && rm hierarchy.zip ``` or otherwise you can use ``` artisan geo:download ``` Download a \*.txt files from geonames.org By default it will download allcountries and hierarchy files otherwise you can pass flag --countries for specific countries - Migrate and Seed. Run: ``` artisan migrate artisan geo:seed ``` you can increase the memory limit for the cli invocation on demand to have process the command at once ``` php -d memory_limit=8000M artisan geo:seed --chunk=100000 ``` So this will increase the memory limit for the command to 8GB with large chunk for each batches You can also pass `--chunk` argument to specify how much chunk you want to process at once suppose you want `3000` records to be processed at once you can pass. This gives flexibility to make the import with low memory footprints ``` artisan geo:seed --chunk=3000 ``` by default it is `1000` Note: If you don't want all the countries, you can download only country specific files (eg US.txt) and import each one of them with: ``` artisan geo:seed US --append ``` Seed with custom data ===================== [](#seed-with-custom-data) Create a json file with custom data at `storage\geo` and run the following command to pick a file to seed: ``` artisan geo:json ``` If an item exists in the DB (based on the 'id' value), then it will be updated else a new entry will be inserted. For example the following json file will rename `United States` to `USA` and it will add a child item (set by the parent\_id value) ``` [ { "id": 6252001, "name": "USA" }, { "name": "USA Child Item", "parent_id": 6252001, "alternames": ["51st State", "dummy name"], "population": 310232863, "lat": "39.760000", "long": "-98.500000" } ] ``` Please note that adding new items to the DB will reindex ALL items to rebuild the tree structure. Please be patient... An example file is provided: [countryNames.json](https://github.com/igaster/laravel_cities/blob/master/data/countryNames.json) which updates the official country names with a most popular simplified version. Tip: You can get a json representation from the DB by quering the API (see below) Geo Model: ========== [](#geo-model) You can use `Igaster\LaravelCities\Geo` Model to access the database. List of available properties: ``` $geo->name; // name of geographical point in plain ascii $geo->alternames; // Array of alternate names (Stored as Json) $geo->country; // 2-letter country code (ISO-3166) $geo->id; // Original id from geonames.org database (geonameid) $geo->population; // Population (Where provided) $geo->lat; // latitude in decimal degrees (wgs84) $geo->long; // longitude in decimal degrees (wgs84) $geo->level; // Administrator level code (feature code) // parent_id, left, right, depth: Used to build hierarcy tree ``` Visit > Info, for a more detailed description. Usage ===== [](#usage) Searching: ---------- [](#searching) ``` use Igaster\LaravelCities\Geo; Geo::getCountries(); // Get a Collection of all countries Geo::getCountry('US'); // Get item by Country code Geo::findName('Nomos Kerkyras'); // Find item by (ascii) name Geo::searchNames('york'); // Search item by all alternative names. Case insensitive Geo::searchNames('vegas', Geo::getCountry('US')); // ... and belongs to an item Geo::getByIds([390903,3175395]); // Get a Collection of items by Ids ``` Traverse tree ------------- [](#traverse-tree) ``` $children = $geo->getChildren(); // Get direct Children of $geo (Collection) $parent = $geo->getParent(); // Get single Parent of $geo (Geo) $ancenstors = $geo->getAncensors(); // Get Ancenstors tree of $geo from top->bottom (Collection) $descendants = $geo->getDescendants(); // Get all Descentants of $geo alphabetic (Collection) ``` Check Hierarchy Relations: -------------------------- [](#check-hierarchy-relations) ``` $geo1->isParentOf($geo2); // (Bool) Check if $geo2 is direct Parent of $geo1 $geo2->isChildOf($geo1); // (Bool) Check if $geo2 is direct Child of $geo1 $geo1->isAncenstorOf($geo2); // (Bool) Check if $geo2 is Ancenstor of $geo1 $geo2->isDescendantOf($geo1); // (Bool) Check if $geo2 is Descentant of $geo1 ``` Query scopes (Use them to Build custom queries) ----------------------------------------------- [](#query-scopes-use-them-to-build-custom-queries) ``` Geo::level($level); // Filter by Administration level: // Geo::LEVEL_COUNTRY, Geo::LEVEL_CAPITAL, Geo::LEVEL_1, Geo::LEVEL_2, Geo::LEVEL_3 Geo::country('US'); // (Shortcut) Items that belongs to country US Geo::capital(); // (Shortcut) Items that are capitals Geo::search($name); // Items that conain $name in name OR alternames (Case InSensitive) Geo::areDescentants($geo); // Items that belong to $geo $geo->ancenstors(); // Items that contain $geo $geo->descendants(); // Items that belong to $geo $geo->children(); // Items that are direct children of $geo //--Scope usage Examples: // Get the States of USA in aplhabetic order Geo::getCountry('US') ->children() ->orderBy('name') ->get(); // Get the 3 biggest cities of Greece Geo::getCountry('GR') ->level(Geo::LEVEL_3) ->orderBy('population','DESC') ->limit(3) ->get(); ``` If you need more functionality you can extend `Igaster\LaravelCities\Geo` model and add your methods. HTTP API ======== [](#http-api) This package defines some API routes that can be used to query the DB through simple HTTP requests. To use them insert in your routes file: ``` \Igaster\LaravelCities\Geo::ApiRoutes(); ``` For example if you insert them in your `routes\api.php` (recomended) then the following URLs will be registered: URL Endpoind (GET)DescriptionReturns (JSON)api/geo/search/{name}/{parent-id?}Search items containing 'name', (and belong to parent-id)Collectionapi/geo/item/{id}Get item by idGeoapi/geo/items/{ids}Get multiple items by ids (comma seperated list)Collectionapi/geo/children/{id}Get children of itemCollectionapi/geo/parent/{id}Get parent of itemGeoapi/geo/country/{code}get country by two-letter codeGeoapi/geo/countrieslist of countriesCollectionThe response is always a JSON representation of either a Geo class or a Collection. To reduce bandwith, all Geo model attributes will be returned except from `alternames`, `left`, `right` and `depth`. You can change this behavior by passing an optional parameter on any request: URL Params (aplly to all routes)DescriptionExamplefields=field1,field2Returns only the specified attributesapi/geo/countries?fields=id,namefields=allReturns all attributesapi/geo/countries?fields=allVue Component ============= [](#vue-component) A [Vue component](https://github.com/igaster/laravel_cities/blob/master/vue/geo-slect.vue) is shipped with this package that plugs into the provided API and provides an interactive way to pick a location through a series of steps. Sorry, no live demo yet, just some screenshots: Step 1: Select your location. Drop down lists loads asynchronous: [![Select Location](/docs/1.jpg?raw=true)](/docs/1.jpg?raw=true) Step 2: Reached to a destination. Path is displayed and button to edit selection: [![Finished Selection](/docs/2.jpg?raw=true)](/docs/2.jpg?raw=true) Step 3: On form submition several fields are beeing submited: [![Form Submited](/docs/3.jpg?raw=true)](/docs/3.jpg?raw=true) ### Usage Guide [](#usage-guide) Assuming that you are using Webpack to compile your assets, and you have included `vue-app.js`: ### Add in your application [](#add-in-your-application) In your main vue-app.js file add the component declaration: `Vue.component('geo-select', require('RELATIVE_PATH_TO/vendor/igaster/laravel_cities/src/vue/geo-select.vue'));` Alternative you may publish the component with `artisan vendor:publish --provider="Igaster\LaravelCities\GeoServiceProvider"` Component will be exported at `/resources/LaravelCities/geo-select.vue` so that you can make modifications... ### Compile compoment [](#compile-compoment) `npm run dev` (or `npm run production`) ### Use in blade files [](#use-in-blade-files) Example: ``` ``` The following inputs will be submited: - geo-id - geo-name - geo-long - geo-lat - geo-country - geo-country-code ### Full syntax: [](#full-syntax) ``` ``` ### Health Score 30 — LowBetter than 64% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity5 Limited adoption so far Community13 Small or concentrated contributor base Maturity72 Established project with proven stability Bus Factor1 Top contributor holds 78.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~78 days Recently: every ~86 days Total 19 Last Release 1956d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/8731267?v=4)[Ian Torres](/maintainers/zen0x7)[@Zen0x7](https://github.com/Zen0x7) --- Top Contributors [![igaster](https://avatars.githubusercontent.com/u/4586319?v=4)](https://github.com/igaster "igaster (93 commits)")[![msonowal](https://avatars.githubusercontent.com/u/6334484?v=4)](https://github.com/msonowal "msonowal (15 commits)")[![Zen0x7](https://avatars.githubusercontent.com/u/8731267?v=4)](https://github.com/Zen0x7 "Zen0x7 (3 commits)")[![beingjungshahi](https://avatars.githubusercontent.com/u/3274491?v=4)](https://github.com/beingjungshahi "beingjungshahi (2 commits)")[![mohamedsabil83](https://avatars.githubusercontent.com/u/10126040?v=4)](https://github.com/mohamedsabil83 "mohamedsabil83 (1 commits)")[![joefazee](https://avatars.githubusercontent.com/u/1267708?v=4)](https://github.com/joefazee "joefazee (1 commits)")[![ricardosierra](https://avatars.githubusercontent.com/u/5499444?v=4)](https://github.com/ricardosierra "ricardosierra (1 commits)")[![shaibow](https://avatars.githubusercontent.com/u/12056542?v=4)](https://github.com/shaibow "shaibow (1 commits)")[![stephenlake](https://avatars.githubusercontent.com/u/1300442?v=4)](https://github.com/stephenlake "stephenlake (1 commits)") --- Tags laravelgeolocationcountriescitiesGeoNames.org ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/alimentalos-laravel-cities/health.svg) ``` [![Health](https://phpackages.com/badges/alimentalos-laravel-cities/health.svg)](https://phpackages.com/packages/alimentalos-laravel-cities) ``` ### Alternatives [igaster/laravel_cities Seed all countries/cities from geonames.org database. Searchable DB tree, ready to use API & a bonus vue.js component! 17988.7k1](/packages/igaster-laravel-cities)[darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 2.9k34.0M112](/packages/darkaonline-l5-swagger)[knuckleswtf/scribe Generate API documentation for humans from your Laravel codebase.✍ 2.3k12.2M45](/packages/knuckleswtf-scribe)[nnjeim/world Laravel countries, states, cities, currencies, languages and IP geolocation 970361.2k3](/packages/nnjeim-world)[lwwcas/laravel-countries A comprehensive package for managing country data in Laravel applications, including multilingual support, geographic coordinates, and detailed metadata for seamless integration with Laravel. 12464.0k](/packages/lwwcas-laravel-countries)[scriptdevelop/whatsapp-manager Paquete para manejo de WhatsApp Business API en Laravel 762.6k](/packages/scriptdevelop-whatsapp-manager) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)