awkwardideas/laravel_cities

Seed all countries/cities from geonames.org database. Searchable DB tree, ready to use API & a bonus vue.js component!

, _(*1)

Forked from igaster/laravel_cities

Introduction

• Deploy and use geonames.org (ex MaxCDN) database locally to query countries/cities
• Includes latitude/longitude
• Optimized DB tree structure 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), _(*2)

Instructions

• Install with copmoser. Run:

composer require awkwardideas/laravel_cities, _(*3)

• Add Service Provider in app.php:

'providers' => [
    //...
    AwkwardIdeas\LaravelCities\GeoServiceProvider::class,
];

• Create a folder geo into app's storage folder ('\storage\geo'). Download & unzip "hieararcy.txt" & "allCountries.txt" from geonames.org (http://download.geonames.org/export/dump)

[Tip] Quick script to download on your remote server with:, _(*4)

mkdir 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

• Migrate and Seed. Run:

php artisan migrate
php artisan geo:seed

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:, _(*5)

php artisan geo:seed US --append

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:, _(*6)

php 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), _(*7)

[
  {
    "id": 6252001,
    "name": "USA"
  },
  {
    "name": "USA Child Item",
    "parent_id": 6252001,
    "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..., _(*8)

An example file is provided: countryNames.json which updates the official country names with a most popular simplified version., _(*9)

Tip: You can get a json representation from the DB by quering the API (see below), _(*10)

Geo Model:

You can use AwkwardIdeas\LaravelCities\Geo Model to access the database. List of available properties:, _(*11)

$geo->name;       // name of geographical point in plain ascii
$geo->country;    // 2-letter country code (ISO-3166)
$geo->id;         // Original id from geonames.org database (geonameid)
$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 http://www.geonames.org > Info, for a more detailed description., _(*12)

Usage

Searching:

use AwkwardIdeas\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

$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:

$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)

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 AwkwardIdeas\LaravelCities\Geo model and add your methods., _(*13)

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:, _(*14)

\AwkwardIdeas\LaravelCities\Geo::ApiRoutes();

For example if you insert them in your routes\api.php (recommended) then the following URLs will be registered:, _(*15)

The response is always a JSON representation of either a Geo class or a Collection., _(*16)

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:, _(*17)

Vue Component

A Vue component 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:, _(*18)

Step 1: Select your location. Drop down lists loads asynchronous:, _(*19)

, _(*20)

Step 2: Reached to a destination. Path is displayed and button to edit selection:, _(*21)

, _(*22)

Step 3: On form submition several fields are beeing submited:, _(*23)

, _(*24)

Usage Guide

Assuming that you are using Webpack to compile your assets, and you have included vue-app.js:, _(*25)

Add in your application

In your main vue-app.js file add the component declaration:, _(*26)

Vue.component('geo-select', require('RELATIVE_PATH_TO/vendor/awkwardideas/laravel_cities/src/vue/geo-select.vue'));, _(*27)

Alternative you may publish the component with, _(*28)

artisan vendor:publish --provider="AwkwardIdeas\LaravelCities\GeoServiceProvider", _(*29)

Component will be exported at /resources/LaravelCities/geo-select.vue so that you can make modifications..., _(*30)

If you choose to do the exported component, make sure you register it in the vue-app.js file with, _(*31)

Vue.component('geo-select', require('RELATIVE_PATH_TO/resources/LaravelCities/geo-select.vue'));, _(*32)

Compile compoment

npm run dev (or npm run production), _(*33)

Use in blade files

Example:, _(*34)

<form action="post-url" method="POST">
    <geo-select></geo-select>
    <!-- Add more form fields here... -->
    <input type="submit">
</form>

The following inputs will be submited:, _(*35)

• geo-id
• geo-name
• geo-long
• geo-lat
• geo-country
• geo-country-code

Full syntax:

<geo-select
    prefix = "geo"                    <!-- change the  fields name prefix --> 
    api-root-url = "\api"             <!-- Root url for API -->
    :countries = "[390903,3175395]"   <!-- Limit to specific countries (defined by ids) -->
    :enable-breadcrumb = "true"       <!-- Enable/Disable Breadcrumb -->
></geo-select>