The World is a Laravel package that provides a comprehensive list of countries, states, cities, timezones, currencies, languages and IP geolocation. You can access the data using the World Facade or through defined API routes.

<img src="./geolocate-badge.svg" alt="New: IP Geolocation"/> 🌍 New in v1.1.38: IP Geolocation Module Detect user location from IP address with automatic fallback to free API. <code>World::geolocate()</code> · <code>GET /api/geolocate</code> <a href="#geolocate-action">Learn more →</a>

Installation
- Automated Installation
- Manual Installation
What's New in v1.1.38
Changelog
Contributing
Examples
Usage
Available Actions
Available API Routes
- Countries
- States
- Cities
- Timezones
- Currencies
- Languages
- Geolocate
Localization
Schema
Configuration
Testing

Installation

First, set your application environment to local:

set APP_ENV=local

Then, install the package via composer:

composer require nnjeim/world

Optionally, set the WORLD_DB_CONNECTION environment variable to your desired database connection.

Automated Installation

Run the following Artisan command to automate the installation process:

php artisan world:install

Manual Installation

If you prefer to install the package manually, follow these steps:

Publish the package configuration file:

php artisan vendor:publish --tag=world --force

Run the migrations:

php artisan migrate

Seed the database:

php artisan db:seed --class=WorldSeeder

Upgrading

⚠️ Important: When upgrading to a new version, you must re-publish the configuration file to ensure all new features work correctly:

php artisan vendor:publish --tag=world --force

This command updates the config/world.php file with new configuration options. Failing to run this command may result in missing features or errors.

What's new in v1.1.38?

New Geolocate Module: IP-based geolocation using MaxMind GeoLite2 database
Facade support: World::geolocate() to detect location from client IP
API endpoint: GET /api/geolocate with automatic IP detection from headers
Fallback to ip-api.com when GeoLite2 database is not installed (no setup required)
Automatic IP detection from proxy headers (Cloudflare, X-Forwarded-For, etc.)
Returns linked Country, State, City models with database IDs
New artisan command: php artisan world:geoip to download GeoLite2 database
Fixed seeder compatibility with non-seedable modules

⚠️ Required: After upgrading, run php artisan vendor:publish --tag=world --force to update your configuration file.

Changelog

For detailed information on recent changes, please see the CHANGELOG.

Contributing

We welcome contributions! For details on how to get started, please review our CONTRIBUTING guidlines.

Examples

Explore the API examples on our live site:

List all countries:
https://world.bmbc.cloud/api/countries
Search for a country:
https://world.bmbc.cloud/api/countries?search=rom
Get states by country code:
https://world.bmbc.cloud/api/states?filters[country_code]=RO&fields=cities

Usage

List all the countries

Use the World facade:

use Nnjeim\World\World;

$action =  World::countries();

if ($action->success) {
  $countries = $action->data;
}

response (object)
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Afghanistan"
    },
    {
      "id": 2,
      "name": "Åland Islands"
    },
    .
    .
    .
  ],
}

Use the API countries endpoint:

https://myDomain.local/api/countries

Fetch a country with its states and cities.

Use the World facade:

use Nnjeim\World\World;

$action =  World::countries([
	'fields' => 'states,cities',
	'filters' => [
		'iso2' => 'FR',
	]
]);

if ($action->success) {

	$countries = $action->data;
}

Response:

(object)
{
  "success": true,
  "data": [
    "id": 77,
    "name": "France",
    "states": [
        {
          "id": 1271,
          "name": "Alo"
        },
        {
          "id": 1272,
          "name": "Alsace"
        },
        .
        .
        .
    ],
    "cities": [
        {
          "id": 25148,
          "name": "Abondance"
        },
        {
          "id": 25149,
          "name": "Abrest"
        },
        .
        .
        .
      ]
    ],
}

Use the API countries endpoint:

https://myDomain.local/api/countries?fields=states,cities&filters[iso2]=FR

List all the cities by country id

use Nnjeim\World\WorldHelper;

new class {
    protected $world;
    
    public function __construct(WorldHelper $world) {
        $this->world = $world;
    }
    
    $action = $this->world->cities([
        'filters' => [
            'country_id' => 182,
        ],
    ]);
    
    if ($action->success) {
        $cities = $action->data;
    }
}

Use the API cities endpoint:

https://myDomain.local/api/cities?filters[country_code]=RO

Available actions

| Name | Description | |:-----------|:------------------------------| | countries | lists all the world countries | | states | lists all the states | | cities | lists all the cities | | timezones | lists all the timezones | | currencies | lists all the currencies | | languages | lists all the languages | | geolocate | geolocates an IP address |

An action response is formed as below:

success (boolean)
message (string)
data (instance of Illuminate\Support\Collection)
errors (array)

Countries action

fields*: comma seperated string (countries table fields in addition to states, cities, currency and timezones).
filters*: array of keys (countries table fields) and their corresponding values.
search*: string.

States action

fields*: comma seperated string (states table fields in addition to country and states).
filters*: array of keys (states table fields) and their corresponding values.
search*: string.

Cities action

fields*: comma seperated string (cities table fields in addition to country and state).
filters*: array of keys (cities table fields) and their corresponding values.
search*: string.

Timezones action

fields*: comma seperated string (timezones table fields in addition to country).
filters*: array of keys (timezones table fields) and their corresponding values.
search*: string.

Currencies action

fields*: comma seperated string (currencies table fields in addition to country).
filters*: array of keys (currencies table fields) and their corresponding values.
search*: string.

Languages action

fields*: comma seperated string (languages table fields).
filters*: array of keys (languages table fields) and their corresponding values.
search*: string.

Geolocate action

Geolocate an IP address. Returns country, state, city, coordinates, and timezone information linked to existing World data.

ip*: string (optional - auto-detects from request if not provided).

Data Sources:

MaxMind GeoLite2 (local database, recommended for production)
ip-api.com (free fallback, no setup required, 45 req/min limit)

The package automatically falls back to ip-api.com if the GeoLite2 database is not installed. For production use, we recommend downloading the GeoLite2 database:

# Get a free license key at: https://www.maxmind.com/en/geolite2/signup
php artisan world:geoip --license=YOUR_LICENSE_KEY

Or set the MAXMIND_LICENSE_KEY environment variable and run:

php artisan world:geoip

To disable the fallback API, set WORLD_GEOLOCATE_FALLBACK_API=false in your .env file.

Usage:

use Nnjeim\World\World;

// Auto-detect IP from request
$action = World::geolocate();

// Geolocate specific IP
$action = World::geolocate(['ip' => '8.8.8.8']);

if ($action->success) {
    $location = $action->data;
    // $location['country'], $location['state'], $location['city'], etc.
}

How IP Detection Works:

The client IP is automatically detected from request headers in this order:

CF-Connecting-IP (Cloudflare)
X-Forwarded-For (Standard proxy header)
X-Real-IP (Nginx proxy)
CLIENT-IP (Generic)
Laravel's request()->ip() fallback

Response Format:

{
  "success": true,
  "message": "geolocations",
  "data": {
    "ip": "8.8.8.8",
    "country": {
      "id": 236,
      "iso2": "US",
      "iso3": "USA",
      "name": "United States",
      "phone_code": "1",
      "region": "Americas",
      "subregion": "Northern A

World

Install / Use

README

Table of Contents