turkish_cities 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0522e7708e876a18f959cb45c4707a4d2490201a605c31b2175af4497369214
-  data.tar.gz: '0853e0da391ef43b97806c40ee2094fdbc94901ff97dcd3f67ee6079428270da'
+  metadata.gz: 14e3cb00362c30c66924e86fb009a79dd9ef16b086166ec0eb1be136653e7cc7
+  data.tar.gz: a1b61fbd9f3319d5973acf35b029bb315460b83d0d8ebcfb15d30405eab0e6cb
 SHA512:
-  metadata.gz: 3fe106b6c80be5368c405b09679ad3af659fd5655438a4ed357b55802cd4a7f1dc261c83be5638e2144f97bd608198393216638de8591419764ae2223c6fc099
-  data.tar.gz: ba31383c0eb87f4d79a5d4d779cb99fbf00a3aebeb15ead25c8afe2fb2865bee1c1fe1fe87bbb62e641fdf009afb0f880f5c6b76dd5ec6659b9783db2913d7c9
+  metadata.gz: 4a0d5834616ddfe7cf080efd3182d599f7901a1d139f831aa85a7ff81d66498bb2ad8a2e118e9c935fadf679cb86f249ae6210f986a38408a1d21c8e5e313b17
+  data.tar.gz: ea17bd392eb05c6bfa1413cc0754d749a2dc53874d5944bc37603c98cf2f65c9de9c9c9a68d208bcbde738c73f59e9b09740f23d5899526ff7a8080e15732197

data/.codeclimate.yml

@@ -0,0 +1,5 @@
+version: "2"
+checks:
+  method-complexity:
+    config:
+      threshold: 10

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] - (Fill here)"
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. In terminal ```require 'turkish_cities'```
+2. Call method ```'....'```
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[FEAT] - (Fill here)"
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

data/.github/pull_request_template.md

@@ -0,0 +1,38 @@
+### Related github issue for this PR
+
+Resolves #001 <!--fill issue number-->
+
+### Checklist
+
+* [ ] I have performed a self-review of my own code
+* [ ] I added comments, particularly in hard-to-understand areas
+* [ ] I have made corresponding changes to the documentation `README.md`
+* [ ] I added tests that prove my fix is effective or that my feature works
+* [ ] `bundle exec rake` passes locally
+* [ ] `rubocop` gives no error locally
+* [ ] My PR title includes "WIP" or is [draft PR](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests) if work is in progress
+
+### Description
+
+<!-- Please include a summary of the change and which issue is fixed.
+Please also include relevant motivation and context.
+Guide questions:
+  - What changed, and why?
+  - What alternative solutions did you consider?
+  - What are the tradeoffs for your solution?
+
+Include anything else we should know about. -->
+
+### Type of change
+
+<!-- Please delete options that are not relevant. -->
+
+* Bug fix (non-breaking change which fixes an issue)
+* New feature (non-breaking change which adds functionality)
+* Breaking change (fix or feature that would cause existing functionality to not
+work as expected)
+* Documentation update
+
+### Which tests are written for this PR? And what are the expected results for these tests?
+
+<!-- Please describe the tests that you ran to verify your changes. -->

data/.hound.yml

@@ -1,3 +1,3 @@
 rubocop:
-  version: 0.80.0
+  version: 0.83.0
   config_file: .rubocop.yml

data/.rubocop.yml

@@ -3,18 +3,14 @@ AllCops:
   Exclude:
     - 'Gemfile'
     - 'turkish_cities.gemspec'
+  NewCops: enable
 Layout/LineLength:
-  Max: 100
+  Max: 120
+Metrics/AbcSize:
+  Max: 20
 Metrics/BlockLength:
   ExcludedMethods: ['describe', 'context']
+Metrics/MethodLength:
+  Max: 15
 Style/Documentation:
   Enabled: false
-Style/HashEachMethods:
-  Enabled: true
-Style/HashTransformKeys:
-  Description: 'Prefer `transform_keys` over `each_with_object` and `map`.'
-  Enabled: true
-Style/HashTransformValues:
-  Description: 'Prefer `transform_values` over `each_with_object` and `map`.'
-  Enabled: true
-    

data/.travis.yml

@@ -1,3 +1,6 @@
+env:
+  global:
+    - CC_TEST_REPORTER_ID=23062197f289fd0ae7601ae06c2dd4a0af4e16c436f2428b99ab4b64a7e4a587
 language: ruby
 dist: trusty
 rvm:
@@ -6,7 +9,13 @@ rvm:
   - 2.7
 before_install:
   - gem install bundler
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
 script: bundle exec rspec spec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
 notifications:
   email:
     - arslanoglusemih93@gmail.com

data/CHANGELOG.md

@@ -1,18 +1,76 @@
 # Changelog
 
+## 0.4.0 (2021-04-25)
+
+### New features
+
+* [#66](https://github.com/sarslanoglu/turkish_cities/issues/66): Add ```distance_between_land``` method for calculating land travel distances between cities
+
+## 0.3.0 (2020-11-22)
+
+### New features
+
+* [#13](https://github.com/sarslanoglu/turkish_cities/issues/13): Add ```distance``` class and ```distance_between``` method for calculating air travel distance and time estimation between cities
+
+### Changes
+
+* [#50](https://github.com/sarslanoglu/turkish_cities/issues/50): Additional improvements on `District` class methods
+
+* [#45](https://github.com/sarslanoglu/turkish_cities/issues/45): Refactor `District` class
+
+## 0.2.1 (2020-06-29)
+
+### Bug fixes
+
+* [#38](https://github.com/sarslanoglu/turkish_cities/issues/38): ```NoMethodError``` on ```list_neighborhoods``` when called with wrong subdistrict name
+
+### Changes
+
+* [#39](https://github.com/sarslanoglu/turkish_cities/issues/39): May maintenance of gem - 2020-05-24
+
+## 0.2.0 (2020-05-18)
+
+### New features
+
+* [#36](https://github.com/sarslanoglu/turkish_cities/issues/36): Add ```postcode``` class and ```find_by_postcode``` method for finding city, district and subdistrict information by given postcode
+
+* [#33](https://github.com/sarslanoglu/turkish_cities/issues/33): Add ```list_neighborhoods``` method for listing neighborhoods and fix some wrong district names
+
+* [#29](https://github.com/sarslanoglu/turkish_cities/issues/29): Add ```district``` class and ```list_subdistricts``` method for listing subdistricts
+
+* [#27](https://github.com/sarslanoglu/turkish_cities/issues/27): Add all subdistricts and neighborhoods of all Turkish cities
+
+* [#25](https://github.com/sarslanoglu/turkish_cities/issues/25): Add district data to each city at yaml file and add new method ```list_districts``` for listing disctricts of cities alphabetically sorted
+
+### Changes
+
+* [#24](https://github.com/sarslanoglu/turkish_cities/issues/24): Add listing support with ```metropolitan_municipality_since, phone_code, plate_number, region``` to ```listing_cities``` method
+
+## 0.1.3 (2020-04-20)
+
+### New features
+
+* [#22](https://github.com/sarslanoglu/turkish_cities/issues/22): Add region data to cities.yaml and update ```list_cities``` method to support regions
+
+* [#20](https://github.com/sarslanoglu/turkish_cities/issues/20): Add city finding with phone code and vice versa. ```find_name_by_phone_code``` and ```find_phone_code_by_name``` methods are added
+
+### Bug fixes
+
+* [#18](https://github.com/sarslanoglu/turkish_cities/issues/18): Fix yaml file read error while deploying apps to Heroku
+
 ## 0.1.2 (2020-04-13)
 
 ### New features
 
-* [#11](https://github.com/sarslanoglu/turkish_cities/pull/11): Change city_list data to yaml file format
+* [#3](https://github.com/sarslanoglu/turkish_cities/issues/3): Change city_list data to yaml file format
 
 ### Bug fixes
 
-* [#6](https://github.com/sarslanoglu/turkish_cities/pull/6): Fix capital Turkish characters bug on cities with capital 'I' letter
+* [#2](https://github.com/sarslanoglu/turkish_cities/issues/2): Fix capital Turkish characters bug on cities with capital 'I' letter
 
 ### Changes
 
-* [#16](https://github.com/sarslanoglu/turkish_cities/pull/16): Handle error messages at ```find_name_by_plate_number``` and ```find_plate_number_by_name``` methods
+* [#15](https://github.com/sarslanoglu/turkish_cities/issues/15): Handle error messages at ```find_name_by_plate_number``` and ```find_plate_number_by_name``` methods
 
 ## 0.1.1 (2020-03-31)
 

data/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+If you discover issues, have ideas for improvements or new features,
+please report them to the [issue tracker][1] of the repository or
+submit a pull request. Please, try to follow these guidelines when you
+do so.
+
+## Guidelines
+
+* Read [how to properly contribute to open source projects on GitHub][2].
+* Fork the project.
+* Write [good commit messages][3].
+* Use the same coding conventions as the rest of the project.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it.
+* Add an entry to the [Changelog](CHANGELOG.md) accordingly. See [changelog entry format](#changelog-entry-format).
+* Make sure the test suite is passing and the code you wrote doesn't produce RuboCop offenses.
+* [Squash related commits together][4].
+
+### Changelog entry format
+
+Here are a few examples:
+
+```
+* [#11](https://github.com/sarslanoglu/turkish_cities/pull/11): Change city_list data to yaml file format
+* [#6](https://github.com/sarslanoglu/turkish_cities/pull/6): Fix capital Turkish characters bug on cities with capital 'I' letter
+* [#16](https://github.com/sarslanoglu/turkish_cities/pull/16): Handle error messages at ```find_name_by_plate_number``` and ```find_plate_number_by_name``` methods
+```
+
+* Mark it up in [Markdown syntax][5].
+* The entry line should start with `* ` (an asterisk and a space).
+* If the change has a related GitHub issue (e.g. a bug fix for a reported issue), put a link to the issue as `[#11](https://github.com/sarslanoglu/turkish_cities/issues/11): `.
+
+[1]: https://github.com/sarslanoglu/turkish_cities/issues
+[2]: https://www.gun.io/blog/how-to-github-fork-branch-and-pull-request
+[3]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[4]: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
+[5]: https://daringfireball.net/projects/markdown/syntax

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in turkish_cities.gemspec
 gemspec

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    turkish_cities (0.1.2)
+    turkish_cities (0.4.0)
       i18n (>= 0.6.4, <= 2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.0)
+    ast (2.4.1)
     concurrent-ruby (1.1.6)
     coveralls (0.8.23)
       json (>= 1.8, < 3)
@@ -15,38 +15,41 @@ GEM
       term-ansicolor (~> 1.3)
       thor (>= 0.19.4, < 2.0)
       tins (~> 1.6)
-    diff-lcs (1.3)
+    diff-lcs (1.4.4)
     docile (1.3.2)
-    i18n (1.8.2)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.4)
     json (2.3.0)
-    parallel (1.19.1)
-    parser (2.7.1.0)
-      ast (~> 2.4.0)
+    parallel (1.20.0)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
     rainbow (3.0.0)
+    regexp_parser (1.8.2)
     rexml (3.2.4)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.1)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
-    rubocop (0.80.1)
-      jaro_winkler (~> 1.5.1)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
+    rubocop (1.3.1)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 2.7.1.5)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8)
       rexml
+      rubocop-ast (>= 1.1.1)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.1.1)
+      parser (>= 2.7.1.5)
     ruby-progressbar (1.10.1)
     simplecov (0.16.1)
       docile (~> 1.1)
@@ -57,19 +60,19 @@ GEM
     term-ansicolor (1.7.1)
       tins (~> 1.0)
     thor (1.0.1)
-    tins (1.24.1)
+    tins (1.25.0)
       sync
-    unicode-display_width (1.6.1)
+    unicode-display_width (1.7.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 2.1.4)
+  bundler (~> 2.2.16)
   coveralls (~> 0.8.23)
-  rspec (~> 3.9.0)
-  rubocop (~> 0.80.1)
+  rspec (~> 3.10.0)
+  rubocop (~> 1.3.1)
   turkish_cities!
 
 BUNDLED WITH
-   2.1.4
+   2.2.16

data/README.md

@@ -1,12 +1,47 @@
-# 🏙️ Turkish Cities
-[![Gem Version](https://badge.fury.io/rb/turkish_cities.svg)](https://rubygems.org/gems/turkish_cities)
-[![Build Status](https://travis-ci.org/sarslanoglu/turkish_cities.svg?branch=master)](https://travis-ci.org/sarslanoglu/turkish_cities)
-[![Code Climate](https://codeclimate.com/github/sarslanoglu/turkish_cities.svg)](https://codeclimate.com/github/sarslanoglu/turkish_cities)
-[![Coverage Status](https://coveralls.io/repos/github/sarslanoglu/turkish_cities/badge.svg?branch=master)](https://coveralls.io/github/sarslanoglu/turkish_cities?branch=master)
-[![Protected by Hound](https://img.shields.io/badge/Protected_by-Hound-a873d1.svg)](https://houndci.com)
-[![License](https://img.shields.io/github/license/sarslanoglu/turkish_cities.svg)](https://opensource.org/licenses/MIT)
+# ![TurkishCities](./public/assets/img/TurkishCities_yellow-on-darkblue_horizontal_914X343@3x-8.png)
 
-**turkish_cities** is a Ruby gem which makes searching and listing Turkish cities easy. https://rubygems.org/gems/turkish_cities
+<p align="center">
+    <a href="https://rubygems.org/gems/turkish_cities">
+        <img src="https://badge.fury.io/rb/turkish_cities.svg" alt="GemVersion"/></a>
+    <a href="https://travis-ci.org/sarslanoglu/turkish_cities">
+        <img src="https://travis-ci.org/sarslanoglu/turkish_cities.svg?branch=master" alt="BuildStatus"/></a>
+    <a href="https://coveralls.io/github/sarslanoglu/turkish_cities?branch=master">
+        <img src="https://coveralls.io/repos/github/sarslanoglu/turkish_cities/badge.svg?branch=master" alt="CoverageStatus"/></a>
+    <a href="https://codeclimate.com/github/sarslanoglu/turkish_cities/maintainability">
+        <img src="https://api.codeclimate.com/v1/badges/c1dbe0cef353b152956e/maintainability" alt="Maintainability"/></a>
+    <a href="https://houndci.com">
+        <img src="https://img.shields.io/badge/Protected_by-Hound-a873d1.svg" alt="Hound"/></a>
+    <a href="https://opensource.org/licenses/MIT">
+        <img src="https://img.shields.io/github/license/sarslanoglu/turkish_cities.svg" alt="License"/></a>
+</p>
+
+**Turkish Cities** is a Ruby gem which makes listing and finding Turkish cities easy. Search can be via name, post code, plate number, district name etc. Also calculate your travel distance and travel time between cities via distance methods.
+https://rubygems.org/gems/turkish_cities
+
+## Table of Contents
+* [Installation](#installation)
+* [Documentation](#documentation)
+  * [Finding city name by plate number](#finding-city-name-by-plate-number)
+  * [Finding city name by phone code](#finding-city-name-by-phone-code)
+  * [Finding plate number by city name](#finding-plate-number-by-city-name)
+  * [Finding phone code by city name](#finding-phone-code-by-city-name)
+  * [Listing all cities](#listing-all-cities)
+    * [Listing all cities with only name](#listing-all-cities-with-only-name)
+    * [Listing all cities with other parameters](#listing-all-cities-with-other-parameters)
+  * [Listing all districts of given city](#listing-all-districts-of-given-city)
+  * [Listing all subdistricts of given city and district](#listing-all-subdistricts-of-given-city-and-district)
+  * [Listing all neighborhoods of given city and district](#listing-all-neighborhoods-of-given-city-and-district)
+    * [With subdistrict info](#with-subdistrict-info)
+    * [Without subdistrict info](#without-subdistrict-info)
+  * [Finding city, district and subdistrict name by postcode](#finding-city-district-and-subdistrict-name-by-postcode)
+  * [Finding travel distance and time estimation between two cities](#finding-travel-distance-and-time-estimation-between-two-cities)
+    * [By land](#by-land)
+    * [By air](#by-air)
+* [Data sources](#data-sources)
+* [Compatibility](#compatibility)
+* [Contributing](#contributing)
+* [Changelog](#changelog)
+* [Copyright](#copyright)
 
 ## Installation
 
@@ -32,73 +67,295 @@ $ bundle
 
 With using irb just require gem and start using
 
-```ruby
+```rb
 require 'turkish_cities'
 ```
 
 ### Finding city name by plate number
 
-There are 81 cities in Turkey. By calling a plate number between 1-81 will give city_name
+There are 81 cities in Turkey. By calling a plate number between 1-81 will give city_name.
 
-```ruby
-TurkishCities.find_name_by_plate_number(26) # => "Eskişehir"
-TurkishCities.find_name_by_plate_number(7) # => "Antalya"
+```rb
+TurkishCities.find_name_by_plate_number(26)   # => "Eskişehir"
+TurkishCities.find_name_by_plate_number(7)    # => "Antalya"
 TurkishCities.find_name_by_plate_number(0007) # => "Antalya"
 TurkishCities.find_name_by_plate_number(43.0) # => "Kütahya"
 TurkishCities.find_name_by_plate_number('78') # => "Karabük"
-TurkishCities.find_name_by_plate_number(100) # => 'Given value [100] is outside bounds of 1 to 81.'
+TurkishCities.find_name_by_plate_number(100)  # => 'Given value [100] is outside bounds of 1 to 81.'
+```
+
+### Finding city name by phone code
+
+There are 82 phone codes for each city in Turkey (Istanbul is an exception with different phone codes for Anatolian side and European side). By calling a phone code between 212-488 will give city_name. All phone codes ending with even numbers. So sending an odd number will give an error without searching.
+
+```rb
+TurkishCities.find_name_by_phone_code(312)    # => "Ankara"
+TurkishCities.find_name_by_phone_code(242)    # => "Antalya"
+TurkishCities.find_name_by_phone_code(000222) # => "Eskişehir"
+TurkishCities.find_name_by_phone_code(274.0)  # => "Kütahya"
+TurkishCities.find_name_by_phone_code('212')  # => "İstanbul"
+TurkishCities.find_name_by_phone_code(216)    # => "İstanbul"
+TurkishCities.find_name_by_phone_code(360)    # => 'Couldn't find city name with phone code 360'
+TurkishCities.find_name_by_phone_code(0)      # => 'Given value [0] is outside bounds of 212 to 488.'
+TurkishCities.find_name_by_phone_code(213)    # => 'Given value [213] must be an even number.'
 ```
 
 ### Finding plate number by city name
 
-City name can be given case and turkish character insensitive
+City name can be given case and turkish character insensitive.
 
-```ruby
-TurkishCities.find_plate_number_by_name('Ankara') # => 6
-TurkishCities.find_plate_number_by_name('Eskişehir') # => 26
-TurkishCities.find_plate_number_by_name('Canakkale') # => 17
-TurkishCities.find_plate_number_by_name('kirsehir') # => 40
+```rb
+TurkishCities.find_plate_number_by_name('Ankara')     # => 6
+TurkishCities.find_plate_number_by_name('Eskişehir')  # => 26
+TurkishCities.find_plate_number_by_name('Canakkale')  # => 17
+TurkishCities.find_plate_number_by_name('Istanbul')   # => 34
+TurkishCities.find_plate_number_by_name('kirsehir')   # => 40
 TurkishCities.find_plate_number_by_name('falansehir') # => "Couldn't find city name with 'falansehir'"
 ```
 
+### Finding phone code by city name
+
+City name can be given case and turkish character insensitive.
+
+```rb
+TurkishCities.find_phone_code_by_name('Ankara')     # => 312
+TurkishCities.find_phone_code_by_name('Eskişehir')  # => 222
+TurkishCities.find_phone_code_by_name('Canakkale')  # => 286
+TurkishCities.find_phone_code_by_name('Istanbul')   # => [212, 216]
+TurkishCities.find_phone_code_by_name('kirsehir')   # => 386
+TurkishCities.find_phone_code_by_name('filansehir') # => "Couldn't find city name with 'filansehir'"
+```
+
 ### Listing all cities
 
 By default cities will be listed by their plate number ascending.
 
-```ruby
+```rb
 TurkishCities.list_cities # => ["Adana", "Adıyaman" ... "Kilis", "Osmaniye", "Düzce"]
 ```
 
-While listing cities two additional parameters can be send ```alphabetically_sorted``` and ```metropolitan_municipality``` Both parameters can be send seperately and together.
+### Listing all cities with only name
+
+While listing cities three additional parameters can be sent ```alphabetically_sorted```, ```metropolitan_municipality``` and ```region```. All parameters can be sent separately and together.
 
-```ruby
+```rb
 TurkishCities.list_cities({ alphabetically_sorted: true })
 # => ["Adana", "Adıyaman" ... "Yalova", "Yozgat", "Zonguldak"]
 TurkishCities.list_cities({ metropolitan_municipality: true })
 # => ["Adana", "Ankara" ... "Trabzon", "Şanlıurfa", "Van"]
+TurkishCities.list_cities({ region: 'Karadeniz' })
+# => ["Amasya", "Artvin" ... "Bartın", "Karabük", "Düzce"]
+TurkishCities.list_cities({ alphabetically_sorted: true, region: 'Karadeniz' })
+# => ["Amasya", "Artvin" ... "Tokat", "Trabzon", "Zonguldak"]
+TurkishCities.list_cities({ metropolitan_municipality: true, region: 'Karadeniz' })
+# => ["Ordu", "Samsun", "Trabzon"]
 TurkishCities.list_cities({ alphabetically_sorted: true, metropolitan_municipality: true })
 # => ["Adana", "Ankara" ... "Tekirdağ", "Trabzon", "Van"]
 ```
 
+### Listing all cities with other parameters
+
+While listing cities ```with``` parameter can be used for listing cities with other attributes. These parameters are ```alphabetically_sorted```, ```metropolitan_municipality``` and ```region```. All parameters can be sent separately and together.
+
+```rb
+TurkishCities.list_cities({ alphabetically_sorted: true, with: { phone_code: true } })
+# => [{:name=>"Adana", :phone_code=>322}, {:name=>"Adıyaman", :phone_code=>416}, {:name=>"Afyon", :phone_code=>272} .
+# .. {:name=>"Yozgat", :phone_code=>354}, {:name=>"Zonguldak", :phone_code=>372}]
+TurkishCities.list_cities({ with: { plate_number: true } })
+# => [{:name=>"Adana", :plate_number=>1}, {:name=>"Adıyaman", :plate_number=>2}, {:name=>"Afyon", :plate_number=>3} .
+# .. {:name=>"Osmaniye", :plate_number=>80}, {:name=>"Düzce", :plate_number=>81}]
+TurkishCities.list_cities({ metropolitan_municipality: true, region: 'Karadeniz', with: { all: true } })
+# => [{:name=>"Ordu", :plate_number=>52, :phone_code=>452, :metropolitan_municipality_since=>2012,
+#      :region=>"Karadeniz"},{:name=>"Samsun", :plate_number=>55, :phone_code=>362,
+#      :metropolitan_municipality_since=>1993, :region=>"Karadeniz"}, {:name=>"Trabzon", :plate_number=>61,
+#      :phone_code=>462, :metropolitan_municipality_since=>2012, :region=>"Karadeniz"}]
+```
+
+### Listing all districts of given city
+
+City name can be given case and turkish character insensitive. Listing of districts are alphabetically sorted.
+
+```rb
+TurkishCities.list_districts('Ankara')
+# => ["Akyurt", "Altındağ" ... "Sincan", "Şereflikoçhisar", "Yenimahalle"]
+TurkishCities.list_districts('Eskişehir')
+# => ["Alpu", "Beylikova", "Çifteler" ... "Sivrihisar", "Tepebaşı"]
+TurkishCities.list_districts('Canakkale')
+# => ["Ayvacık", "Bayramiç" ... "Lapseki", "Merkez", "Yenice"]
+TurkishCities.list_districts('Bayburt')
+# => ["Aydıntepe", "Demirözü", "Merkez"]
+TurkishCities.list_districts('Istanbul').length
+# => 39
+TurkishCities.list_districts('filansehir')
+# => "Couldn't find city name with 'filansehir'"
+```
+
+### Listing all subdistricts of given city and district
+
+City name can be given case and turkish character insensitive. District name should be case and turkish character sensitive.(Correct district names can be obtained by ```list_districts``` method.) Listing of subdistricts are alphabetically sorted.
+
+```rb
+TurkishCities.list_subdistricts('Adana', 'Seyhan')
+# => ["Akkapı", "Denizli" ... "Yeşiloba", "Yeşilyurt", "Ziyapaşa"]
+TurkishCities.list_subdistricts('Eskişehir', 'Odunpazarı')
+# => ["Alanönü", "Arifiye", "Büyükdere" ... "Vişnelik", "Yenikent"]
+TurkishCities.list_subdistricts('Istanbul', 'Beşiktaş')
+# => ["Abbasağa", "Akatlar", "Arnavutköy", "Bebek", "Etiler", "Gayrettepe", "Levazım", "Levent", "Ortaköy", "Türkali"]
+TurkishCities.list_subdistricts('filansehir', 'Beşiktaş')
+# => "Couldn't find district name with 'Beşiktaş' of 'filansehir'"
+TurkishCities.list_subdistricts('İstanbul', 'Kadılarköyü')
+# => "Couldn't find district name with 'Kadılarköyü' of 'İstanbul'"
+```
+
+### Listing all neighborhoods of given city and district
+
+### With subdistrict info
+
+City name can be given case and turkish character insensitive. District name and subdistrict name should be case and turkish character sensitive.(Correct district names can be obtained by the ```list_districts``` method. Correct subdistrict names can be obtained by ```list_subdistricts``` method.) Listings of neighborhoods are alphabetically sorted.
+
+```rb
+TurkishCities.list_neighborhoods('Adana', 'Seyhan', 'Emek')
+# => ["Emek Mah", "Ova Mah", "Şakirpaşa Mah", "Uçak Mah"]
+TurkishCities.list_neighborhoods('Eskişehir', 'Odunpazarı', 'Büyükdere')
+# => ["Büyükdere Mah", "Göztepe Mah", "Gültepe Mah", "Yıldıztepe Mah"]
+TurkishCities.list_neighborhoods('Istanbul', 'Beşiktaş', 'Gayrettepe')
+# => ["Balmumcu Mah", "Dikilitaş Mah", "Gayrettepe Mah", "Yıldız Mah"]
+TurkishCities.list_neighborhoods('Adana', 'Beşiktaş', 'Emek')
+# => "Couldn't find district name with 'Beşiktaş' of 'Adana'"
+TurkishCities.list_neighborhoods('Eskişehir', 'Odunpazarı', 'Büyükkkkkdere')
+# => "Couldn't find subdistrict with 'Büyükkkkkdere' of 'Odunpazarı'/'Eskişehir'"
+```
+
+### Without subdistrict info
+
+Also ```list_neighborhoods``` can work without subdistrict information. This time neighborhoods result will be larger based on searched city and district.
+
+City name can be given case and turkish character insensitive. District name should be case and turkish character sensitive.(Correct district names can be obtained by the ```list_districts``` method.) Listings of neighborhoods are alphabetically sorted.
+
+```rb
+TurkishCities.list_neighborhoods('Adana', 'Seyhan')
+# => ["2000 Evler Mah", "Ahmet Remzi Yüreğir Mah", "Akkapı Mah" ... "Zeytinli Mah", "Ziyapaşa Mah"]
+TurkishCities.list_neighborhoods('Eskişehir', 'Odunpazarı')
+# => ["71 Evler Mah", "75. Yıl Osb Mah" ... "Yukarıkalabak Mah", "Yürükkaracaören Mah", "Yürükkırka Mah"]
+TurkishCities.list_neighborhoods('Istanbul', 'Beşiktaş')
+# => ["Abbasağa Mah", "Akat Mah", "Arnavutköy Mah" ... "Türkali Mah", "Ulus Mah", "Vişnezade Mah", "Yıldız Mah"]
+TurkishCities.list_neighborhoods('İstanbul', 'filanmevki')
+# => "Couldn't find district name with 'filanmevki' of 'İstanbul'"
+```
+
+### Finding city, district and subdistrict name by postcode
+
+In Turkey postcodes are uniq for subdistricts. Basically when a postcode is search through ```find_by_postcode``` it will give city, district and subdistrict information of postcode if valid and found
+
+```rb
+TurkishCities.find_by_postcode(34380)    # => ["İstanbul", "Şişli", "Cumhuriyet"]
+TurkishCities.find_by_postcode(34433)    # => ["İstanbul", "Beyoğlu", "Cihangir"]
+TurkishCities.find_by_postcode('26040')  # => ["Eskişehir", "Odunpazarı", "Büyükdere"]
+TurkishCities.find_by_postcode(34382)    # => "Couldn't find any subdistrict with postcode '34382'"
+TurkishCities.find_by_postcode('100000') # => Given value [100000] is outside bounds of 1010 to 81952.
+```
+
+### Finding travel distance and time estimation between two cities
+
+### By land
+
+City names can be given case and turkish character insensitive. Travel method should be lower case. Array with 2 elements will be returned. First element is distance between cities in kilometers and the second element is the description created by the first element.
+
+```rb
+TurkishCities.distance_between('Eskişehir', 'Kastamonu', 'land')
+# => [480, "Land travel distance between Eskişehir and Kastamonu is 480 km."]
+TurkishCities.distance_between('kirsehir', 'Ordu', 'land')
+# => [533, "Land travel distance between Kırşehir and Ordu is 533 km."]
+TurkishCities.distance_between('İzmir', 'Antalya', 'land')
+# => [444, "Land travel distance between İzmir and Antalya is 444 km."]
+TurkishCities.distance_between('istanbul', 'kars', 'land')
+# => [1427, "Land travel distance between İstanbul and Kars is 1427 km."]
+TurkishCities.distance_between('Adana', 'Adıyaman', 'time')
+# => "Travel method 'time' is unsupported"
+TurkishCities.distance_between('filansa', 'falansa', 'land')
+# => "Couldn't find cities combination with 'filansa/falansa'"
+```
+
+### By air
+
+City names can be given case and turkish character insensitive. Travel method should be lower case. Array with 3 elements will be returned. First element is distance between cities in kilometers, the second element is estimated travel time and the last element is the description created by the first two elements.
+
+```rb
+TurkishCities.distance_between('Eskişehir', 'Kastamonu', 'air')
+# => [327.74, 62, "Air travel distance between Eskişehir and Kastamonu is 327.74 km. Estimated air travel would take 62 minutes."]
+TurkishCities.distance_between('kirsehir', 'Ordu', 'air')
+# => [376.89, 67, "Air travel distance between Kırşehir and Ordu is 376.89 km. Estimated air travel would take 67 minutes."]
+TurkishCities.distance_between('İzmir', 'Antalya', 'air')
+# => [357.18, 65, "Air travel distance between İzmir and Antalya is 357.18 km. Estimated air travel would take 65 minutes."]
+TurkishCities.distance_between('istanbul', 'kars', 'air')
+# => [1187.94, 120, "Air travel distance between İstanbul and Kars is 1187.94 km. Estimated air travel would take 120 minutes."]
+TurkishCities.distance_between('Adana', 'Adıyaman', 'time')
+# => "Travel method 'time' is unsupported"
+TurkishCities.distance_between('filansa', 'falansa', 'air')
+# => "Couldn't find cities combination with 'filansa/falansa'"
+```
+
+## Data sources
+
+All information related with cities can be found at:
+
+```
+https://tr.wikipedia.org/wiki/{#city_name_here}
+```
+
+Districts, subdisctricts, neighborhoods and postcodes can be found at:
+
+```
+https://postakodu.ptt.gov.tr/
+```
+
+Land distance information can be found at:
+
+```
+https://www.kgm.gov.tr/SiteCollectionDocuments/KGMdocuments/Root/Uzakliklar/ilmesafe.xls
+```
+
 ## Compatibility
 
-- ✅ `2.7.0` (stable)
-- ✅ `2.6.3` (stable)
-- ✅ `2.5.5` (stable)
+| Ruby Version | Supported          |
+| ------------ | ------------------ |
+| 2.7.1        | :white_check_mark: |
+| 2.6.6        | :white_check_mark: |
+| 2.5.8        | :white_check_mark: |
+| < 2.5.1      | :x:                |
+
+- TurkishCities heavily depends on ```:turkic``` case mapping support of Ruby string downcase method. Below Ruby version 2.5.1 some functions will run buggy/false or even won't run at all.
 
-- This gem heavily depends of ```:turkic``` case mapping support of Ruby string downcase method. Below Ruby version 2.5.1 some functions will run buggy/false or even won't run at all.
+## Roadmap
+
+- Add missing sea travel method
+- Add localization to gem
+- Refactor tests (separate test suites with more edge case tests)
 
 ## Contributing
 
-1. Fork it ( https://github.com/sarslanoglu/turkish_cities/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Contributing guidelines are available [here](CONTRIBUTING.md).
+
+People behind the 💻
+<table>
+  <tr>
+    <td align="center"><a href="https://enderahmetyurt.com/"><img src="https://avatars2.githubusercontent.com/u/447588" width="100px;" alt=""/><br /><sub><b>Ender Ahmet Yurt</b></sub></a><br /></td>
+    <td align="center"><a href="https://www.linkedin.com/in/serpilacar/"><img src="https://avatars0.githubusercontent.com/u/17191440" width="100px;" alt=""/><br /><sub><b>Serpil Acar</b></sub></a><br /></td>
+    <td align="center"><a href="https://www.linkedin.com/in/semiharslanoglu/"><img src="https://avatars2.githubusercontent.com/u/10260283" width="100px;" alt=""/><br /><sub><b>Semih Arslanoğlu</b></sub></a><br /></td>
+  </tr>
+</table>
 
 ## Changelog
 
-turkish_cities changelog is available [here](CHANGELOG.md).
+Changelog is available [here](CHANGELOG.md).
+
+## Logo
+
+TurkishCities's logo created by [Nebal Çolpan](https://www.behance.net/nebalcolpan). You can find the logo in various
+formats [here](https://github.com/sarslanoglu/turkish_cities/tree/master/public/assets/img/).
+
+The logo is licensed under a
+[Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/deed.en_GB).
 
 ## Copyright