Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shivammathur/countrycity
:earth_americas: Geodata API - Get countries, and cities to plug in drop-downs.
https://github.com/shivammathur/countrycity
api cities countries country-city-api dropdown geodata php select2 slim-framework
Last synced: 13 days ago
JSON representation
:earth_americas: Geodata API - Get countries, and cities to plug in drop-downs.
- Host: GitHub
- URL: https://github.com/shivammathur/countrycity
- Owner: shivammathur
- License: mit
- Created: 2016-05-02T20:59:26.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2023-09-04T23:28:33.000Z (about 1 year ago)
- Last Synced: 2024-10-23T08:50:36.767Z (21 days ago)
- Topics: api, cities, countries, country-city-api, dropdown, geodata, php, select2, slim-framework
- Language: PHP
- Homepage: https://shivammathur.github.io/countrycity/
- Size: 6.01 MB
- Stars: 102
- Watchers: 5
- Forks: 51
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Country City API
[](https://github.com/shivammathur/countrycity/actions)
[](https://codeclimate.com/github/shivammathur/countrycity)
[](https://codecov.io/gh/shivammathur/countrycity)
[](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.
### :zap: Installing the CountryCity API
- Make sure you have PHP 7.4 or newer.
```bash
$ php -v
```
- Download this API using [composer](https://getcomposer.org/download/) using the command below.
```bash
composer global require shivammathur/countrycity "dev-main"
```
- Then install the API by executing the command below.
```bash
composer create-project shivammathur/countrycity countrycity "dev-main" --prefer-dist
```
- You are all set, you can use this API.
### :hash: API Endpoints
All API responses are in `json` format.
- Get all countries
```bash
/countries
# Without URL Rewriting
/index.php/countries
```
- Get all countries containing a search keyword
```bash
/countries/{search_keyword}
# Without URL Rewriting
/index.php/countries/{search_keyword}
```
- Get all cities in a country
```bash
/cities/{country}
# Without URL Rewriting
/index.php/cities/{country}
```
- Get all cities in a country containing a search keyword
```bash
/cities/{country}/{search_keyword}
# Without URL Rewriting
/index.php/cities/{country}/{search_keyword}
```
### :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
### :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.
### :wrench: Error Format
If there is an error in the API, you will get an error in `json` format as response
```json
{"error":"true", "message": "error message here"}
```
### :rotating_light: Testing
```bash
$ vendor/bin/phpunit --configuration phpunit.xml.dist
```
## :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.
## :+1: Contributions
Contributions are welcome! See [Contributor's Guide](.github/CONTRIBUTING.md).
## :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).