PHPackages                             shivammathur/countrycity - 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. [HTTP & Networking](/categories/http)
4. /
5. shivammathur/countrycity

ActiveLibrary[HTTP & Networking](/categories/http)

shivammathur/countrycity
========================

API to get all countries and all cities in a country.

3.1.3(4y ago)10128251[1 issues](https://github.com/shivammathur/countrycity/issues)[1 PRs](https://github.com/shivammathur/countrycity/pulls)MITPHPPHP >=7.4

Since Sep 3Pushed 2y ago3 watchersCompare

[ Source](https://github.com/shivammathur/countrycity)[ Packagist](https://packagist.org/packages/shivammathur/countrycity)[ Docs](http://github.com/shivammathur)[ RSS](/packages/shivammathur-countrycity/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (9)Dependencies (13)Versions (13)Used By (0)

Country City API
================

[](#country-city-api)

[![Build Status](https://github.com/shivammathur/countrycity/workflows/Tests/badge.svg)](https://github.com/shivammathur/countrycity/actions)[![Code Climate](https://camo.githubusercontent.com/20219048e50bf543921d0c5be02a44a35d06e74a53ea2c5d0641d7bbcc93c20c/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f73686976616d6d61746875722f636f756e747279636974792f6261646765732f6770612e737667)](https://codeclimate.com/github/shivammathur/countrycity)[![codecov](https://camo.githubusercontent.com/be985db06d98324c329b41c9ae0e6ea69de83b8e67c25fe4bbd3f355f9f48428/68747470733a2f2f636f6465636f762e696f2f67682f73686976616d6d61746875722f636f756e747279636974792f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/shivammathur/countrycity)[![License](https://camo.githubusercontent.com/6ceea9edff51f0fae072df078f0d6a7db199014946b5b1e271097d0f07d546b1/68747470733a2f2f706f7365722e707567782e6f72672f73686976616d6d61746875722f636f756e747279636974792f6c6963656e7365)](license.md)

Geodata API to get the list of countries and cities in the world. This can be plugged in country and city picker drop-downs in forms. You can find a [select2](https://select2.org/) implementation [here](https://shivammathur.github.io/countrycity/). Code for this implementation is in [`example`](example) directory.

 [![](https://camo.githubusercontent.com/8193545fdded00e3a518c565c25783f385dedeb4a6b5a1681ca06a5e78095b5e/68747470733a2f2f73686976616d6d61746875722e636f6d2f636f756e747279636974792f636f756e747279636974792e676966)](https://camo.githubusercontent.com/8193545fdded00e3a518c565c25783f385dedeb4a6b5a1681ca06a5e78095b5e/68747470733a2f2f73686976616d6d61746875722e636f6d2f636f756e747279636974792f636f756e747279636974792e676966)

### ⚡ Installing the CountryCity API

[](#zap-installing-the-countrycity-api)

- Make sure you have PHP 7.4 or newer.

```
$ php -v
```

- Download this API using [composer](https://getcomposer.org/download/) using the command below.

```
composer global require shivammathur/countrycity "dev-main"
```

- Then install the API by executing the command below.

```
composer create-project shivammathur/countrycity countrycity "dev-main" --prefer-dist
```

- You are all set, you can use this API.

### \#️⃣ API Endpoints

[](#hash-api-endpoints)

All API responses are in `json` format.

- Get all countries

```
/countries

# Without URL Rewriting
/index.php/countries
```

- Get all countries containing a search keyword

```
/countries/{search_keyword}

# Without URL Rewriting
/index.php/countries/{search_keyword}
```

- Get all cities in a country

```
/cities/{country}

# Without URL Rewriting
/index.php/cities/{country}
```

- Get all cities in a country containing a search keyword

```
/cities/{country}/{search_keyword}

# Without URL Rewriting
/index.php/cities/{country}/{search_keyword}
```

### ✨ Rest API Features

[](#sparkles-rest-api-features)

- Built using Slim micro framework.
- Caching enabled with following headers
    - ETag
    - Expires
    - Last-Modified
- Fast and lightweight API
- PSR 7 Complaint
- CORS Middleware

### ☁️ Hosting configuration

[](#cloud-hosting-configuration)

Here are the [Configuration Instructions](http://www.slimframework.com/docs/v3/start/web-servers.html) if you want to host this on your server.

### 🔧 Error Format

[](#wrench-error-format)

If there is an error in the API, you will get an error in `json` format as response

```
{"error":"true", "message": "error message here"}
```

### 🚨 Testing

[](#rotating_light-testing)

```
$ vendor/bin/phpunit --configuration phpunit.xml.dist
```

📜 License
---------

[](#scroll-license)

The scripts and documentation in this project are released under the [MIT License](LICENSE). This project has multiple [dependencies](https://github.com/shivammathur/countrycity/network/dependencies) and their licenses can be found in their respective repositories.

👍 Contributions
---------------

[](#1-contributions)

Contributions are welcome! See [Contributor's Guide](.github/CONTRIBUTING.md).

💖 Support this project
----------------------

[](#sparkling_heart-support-this-project)

- Please star the project and share it with the community.
- Support the project by sponsoring my work on [GitHub sponsors](https://github.com/sponsors/shivammathur).

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 66.5% 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 ~81 days

Recently: every ~119 days

Total

10

Last Release

1756d ago

Major Versions

2.1.1 → 3.0.02020-05-19

PHP version history (4 changes)2.0.0PHP >=7.2.0

2.1.0PHP ^7.2

3.0.0PHP ^7.4

3.1.1PHP >=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/e49ce82189a9229680916da6a0c313da72415e8a335a954e02bfc384a7c0c4cb?d=identicon)[shivammathur](/maintainers/shivammathur)

---

Top Contributors

[![shivammathur](https://avatars.githubusercontent.com/u/1571086?v=4)](https://github.com/shivammathur "shivammathur (115 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (34 commits)")[![ajuchacko](https://avatars.githubusercontent.com/u/13982547?v=4)](https://github.com/ajuchacko "ajuchacko (21 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![klivak](https://avatars.githubusercontent.com/u/8767628?v=4)](https://github.com/klivak "klivak (1 commits)")

---

Tags

apicitiescountriescountry-city-apidropdowngeodataphpselect2slim-frameworkphprestpsr7countriesdropdowncitiesgeodata

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/shivammathur-countrycity/health.svg)

```
[![Health](https://phpackages.com/badges/shivammathur-countrycity/health.svg)](https://phpackages.com/packages/shivammathur-countrycity)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.5M378](/packages/easycorp-easyadmin-bundle)[api-platform/core

Build a fully-featured hypermedia or GraphQL API in minutes!

2.6k50.1M314](/packages/api-platform-core)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19664.8M1.6k](/packages/drupal-core)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M196](/packages/sulu-sulu)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M398](/packages/drupal-core-recommended)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)