Project: turkish_cities - The Ruby Toolbox

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
Localization
Documentation
- Finding city name by plate number
- Finding city name by phone code
- Finding plate number by city name
- Finding phone code by city name
- Listing all cities
  - Listing all cities with only name
  - Listing all cities with other parameters
- Listing all districts of given city
- Listing all subdistricts of given city and district
- Listing all neighborhoods of given city and district
  - With subdistrict info
  - Without subdistrict info
- Finding city, district and subdistrict name by postcode
- Finding city name with elevation data
  - Below given
  - Above given
  - Between search
- Finding city name with population data
  - Exact search
  - Below given
  - Above given
  - Between search
- Finding travel distance and time estimation between two cities
  - By land
  - By air
Data sources
Compatibility
Contributing
Changelog
Copyright

Installation

Installation is pretty standard:

$ gem install turkish_cities

or with using Bundler, add this line to your Gemfile

gem 'turkish_cities'

and run

$ bundle

Localization

Currently gem supports two different languages, Turkish and English. English is default, if no action taken.

Language can be easily changed by change_locale method. Valid parameters are 'tr' for Turkish and 'en' for English.

TurkishCities.change_locale('tr') # => "Dil Türkçe olarak ayarlandı."

After changing language all errors and result sets will be in desired language

TurkishCities.list_districts('Eskişehirrr') # => "'Eskişehirrr' ile bir şehir bulunamadı"
TurkishCities.distance_between('kirsehir', 'Ordu', 'land')
# => [533, "Kırşehir ile Ordu arasındaki karayolu mesafesi 533 km"]

Documentation

With using irb just require gem and start using

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.

Expand

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.'

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.

Expand

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.

Expand

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.

Expand

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.

Expand

TurkishCities.list_cities # => ["Adana", "Adıyaman" ... "Kilis", "Osmaniye", "Düzce"]

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.

Expand

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.

Expand

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.

Expand

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.

Expand

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.

Expand

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.

Expand

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

Expand

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 city name with elevation data

The lowest possible altitude for a city in Turkey is 4 meters with Kocaeli. The highest possible altitude is 1923 meters with Erzurum. Being far outside of the range may give errors.

Below given

Search city name with below elevation

Expand

TurkishCities.find_by_elevation('below', 10)
# => ["İzmir", "Kocaeli", "Yalova"]
TurkishCities.find_by_elevation('below', 50)
# => ["Adana", "Çanakkale" ... "Bartın", "Yalova"]
TurkishCities.find_by_elevation('below', 500)
# => ["Adana", "Amasya" ... "Karabük", "Osmaniye", "Düzce"]
TurkishCities.find_by_elevation('below', 2213)
# => ["Adana", "Adıyaman" ... "Kilis", "Osmaniye", "Düzce"]
TurkishCities.find_by_elevation('woleb', 213)
# => ArgumentError: "Elevation type 'woleb' is unsupported"
TurkishCities.find_by_elevation('below', 1)
# => RangeError: Given value [1] is outside bounds of 3 to Infinity

Above given

Search city name with above elevation

Expand

TurkishCities.find_by_elevation('above', 0)
# => ["Adana", "Adıyaman" ... "Osmaniye", "Düzce"]
TurkishCities.find_by_elevation('above', 100)
# => ["Adıyaman", "Afyon" ... "Osmaniye", "Düzce"]
TurkishCities.find_by_elevation('above', 500)
# => ["Adıyaman", "Afyon" ... "Iğdır", "Kilis"]
TurkishCities.find_by_elevation('above', 1750)
# => ["Erzurum", "Hakkari", "Kars", "Ardahan"]
TurkishCities.find_by_elevation('abov', 1000)
# => ArgumentError: "Elevation type 'abov' is unsupported"
TurkishCities.find_by_elevation('above', 2000)
# => RangeError: Given value [2000] is outside bounds of 0 to 1924

Between search

Search city name with between elevation

Expand

TurkishCities.find_by_elevation('between', 50, 100)
# => ["Antalya", "Aydın", "Hatay", "Manisa"]
TurkishCities.find_by_elevation('between', 100, 250)
# => ["Balıkesir", "Bursa", "Kırklareli", "Osmaniye", "Düzce"]
TurkishCities.find_by_elevation('between', 250, 1000)
# => ["Adıyaman", "Amasya" ... "Karabük", "Kilis"]
TurkishCities.find_by_elevation('between', 0, 2000)
# => ["Adana", "Adıyaman" ... "Osmaniye", "Düzce"]
TurkishCities.find_by_elevation('between', 2000, 5000)
# => []

Finding city name with population data

The least populated city in Turkey is Tunceli with 83645. The highest populated is Istanbul with 15840900. Being far outside of the range may give errors.

Exact search

Search city name with exact population

Expand

TurkishCities.find_by_population('exact', 15840900)
# => ["İstanbul"]
TurkishCities.find_by_population('exact', 104320)
# => "Couldn't find any city with population data"
TurkishCities.find_by_population('exatc', 2130432)
# => "Population type 'exatc' is unsupported"
TurkishCities.find_by_population('exact', 10432)
# => Given value [10432] is outside bounds of 83644 to 15840901
TurkishCities.find_by_population('exact', 22130432)
# => Given value [22130432] is outside bounds of 83644 to 15840901

Below given

Search city name with below population

Expand

TurkishCities.find_by_population('below', 86000)
# => ["Tunceli", "Bayburt"]
TurkishCities.find_by_population('below', 500000)
# => ["Amasya", "Artvin" ... "Kilis", "Düzce"]
TurkishCities.find_by_population('below', 1000000)
# => ["Adıyaman", "Afyon" ... "Kilis", "Osmaniye", "Düzce"]
TurkishCities.find_by_population('below', 22130432)
# => ["Adana", "Adıyaman" ... "Kilis", "Osmaniye", "Düzce"]
TurkishCities.find_by_population('woleb', 2130432)
# => "Population type 'woleb' is unsupported"
TurkishCities.find_by_population('below', 10432)
# => Given value [10432] is outside bounds of 83644 to Infinity

Above given

Search city name with above population

Expand

TurkishCities.find_by_population('above', 860000)
# => ["Adana", "Ankara" ... "Şanlıurfa", "Van"]
TurkishCities.find_by_population('above', 2500000)
# => ["Ankara", "Antalya", "Bursa", "İstanbul", "İzmir"]
TurkishCities.find_by_population('above', 5000000)
# => ["Ankara", "İstanbul"]
TurkishCities.find_by_population('above', 10432)
# => ["Adana", "Adıyaman" ... "Kilis", "Osmaniye", "Düzce"]
TurkishCities.find_by_population('abov', 2130432)
# => "Population type 'abov' is unsupported"
TurkishCities.find_by_population('above', 22130432)
# => Given value [22130432] is outside bounds of 0 to 15840901

Between search

Search city name with between population

Expand

TurkishCities.find_by_population('between', 15840901, 3000000)
# => ["Ankara", "Bursa", "İstanbul", İzmir"]
TurkishCities.find_by_population('between', 828369, 985732)
# => ["Eskişehir", "Mardin"]
TurkishCities.find_by_population('between', 2130432, 3500000)
# => ["Adana", "Antalya", "Bursa", "Konya", "Şanlıurfa"]
TurkishCities.find_by_population('between', 10432, 100000)
# => ["Tunceli", "Bayburt", "Ardahan"]
TurkishCities.find_by_population('between', 11304320, 34000000)
# => ["İstanbul"]
TurkishCities.find_by_population('between', 100000, 100001)
# => "Couldn't find any city with population data"

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.

Expand

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.

Expand

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 information can be found at:

https://postakodu.ptt.gov.tr/

All districts/subdistricts are up to date at: 23 January 2022 with using PTT file released at 22 November 2021

Land distance information can be found at:

https://www.kgm.gov.tr/SiteCollectionDocuments/KGMdocuments/Root/Uzakliklar/ilmesafe.xls

Population of cities are up to date as 15 February 2022 as using February 2022 report of Türkiye İstatistik Kurumu (TÜİK) / Turkish Statistical Institute (TURKSTAT)

Statistics for gem can be found at:

https://bestgems.org/gems/turkish_cities

Compatibility

Ruby Version	Supported
3.2.x	❓
3.1.x	❓
3.0.x	✅
2.7.x	✅
2.6.x	✅
> 2.5.1	✅
< 2.5.1	❌

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.