Adres API

Temel Kullanım ¶

Adres API’yi sayfanıza eklemek için:

• Adres API kütüphanesini ve stil dosyasını ekleyiniz

<script src="adresApi.min.js" type="text/javascript" charset="UTF-8"></script>

<link rel="stylesheet" href="adresApi.min.css">

• Daha sonra adres girişinin yapılacağı elementi tanımlayınız

<div id="aa-container"></div>

• Adres API’yi tanımladığınız elemente bağlayınız

<script>
    var aa = new AdresApi('aa-container');
</script>

ve artık kullanıcı adres girişini tamamladıktan sonra;

<script>
    var resultJson = aa.getValue();
</script>

getValue() fonksiyonu ile adrese ait tüm detaylara ulaşabilirsiniz.

Kullanım Seçenekleri ¶

Haritasız ¶

Adres API’nin en yalın kullanım şeklidir. Kullanıcı harita üzerinden adres doğrulaması yapmadan adres detaylarına geocoding işlemi ile ulaşılır.

Kullanıcının adresini yol seviyesinde seçmesi ve adrese ait ek bilgileri belirtmesi sonrasında getValue() methodu ile adres detayları erişilebilir olacaktır.

Bağlı Harita ¶

Bir sayfaya bağlanmış farklı Adres API bileşenleri haritalarını kendi bulundukları konuma göre ayrı ayrı gösterebilir.

Ortak Harita ¶

Bir sayfaya bağlanmış farklı Adres API bileşenleri haritalarını tek ve büyük bir alanda gösterebilir.

İl ve Serbest Giriş ¶

İl girişi yapıldıktan sonra adresin serbest formatta girilmesi şeklinde daha az kontrollü girişlere izin verilebilir.

Konfigürasyon ¶

Aktif Sunucu ¶

Adres API’nin adres sorgulamalarını yapmak için bağlanacağı sunucu adresidir.

var aa = new AdresApi('aa-container', {
        server :  'http://www.adresapi.com'
    });

Erişim Anahtarı ¶

Bağlanılacak sunucu üzerinde tanımlanmış, kullanıcıya özel erişim anahtarıdır.

var aa = new AdresApi('aa-container', {
        token :  'ABCDEFGHIJ0123456789'
    });

Kullanım Modu ¶

Adres API üç farklı kullanım modu sunmaktadır.

Otomatik ¶

Kullanıcının gireceği kelimelere göre otomatik önermenin yapıldığı ve bu önermelerden birinin seçilmesini gerektiren moddur.

Otomatik kullanım Adres API’nin sunduğu varsayılan moddur.

var aa = new AdresApi('aa-container', {
        mode :  1
    });

Hiyerarşik ¶

Adresin il, ilçe, mahalle ve yol hiyerarşisine göre girişinin yapıldığı moddur.

var aa = new AdresApi('aa-container', {
        mode :  2
    });

Hiyerarşik derinlik il:1, ilçe:2, mahalle:3 ve yol:4 değerlerine göre konfigüre edilebilmektedir.

var aa = new AdresApi('aa-container', {
        indexDepth : 2
    });

Serbest ¶

Kullanıcının düz metin girişi yapmasına izin verilen, otomatik önermelerden herhangi birini seçmesinin zorunlu olmadığı moddur.

Bu mod serbest geocoding kullanılarak adres detaylarına erişim sağlamaktadır. Girilen bileşenlerin adres verisi ile doğrulanmaması sebebiyle kullanıcı doğru adres girişi için yönlendirilemeyecektir.

var aa = new AdresApi('aa-container', {
        mode :  2
    });

Kullanıcılara mod değiştirme seçeneğini sunmak için modeSelect parametresi kullanılmalıdır.

var aa = new AdresApi('aa-container', {
       modeSelect : true
   });

Haritalar ¶

Adres API içerisinde harita kullanımının aktif olabilmesi için; ilgili harita kütüphanesinin de sayfaya eklenmiş olması gerekmektedir.

Adres API harita bileşeni olarak açık kaynak kodlu Leaflet Js kütüphanesi (v1.0 ve sonrası) kullanılmaktadır. Harita işlemleri, sayfaya ekli diğer Leaflet Js elementleri ile herhangi bir çakışma yaratmadan gerçekleşmektedir.

<script src="leaflet/leaflet.min.js" type="text/javascript"></script>

<link rel="stylesheet" href="leaflet/leaflet.min.css">

Adres aramalarında harita, maps parametresi belirlendiği durumda aktif olacaktır.

maps parametresi ile harita altlıklarının neler olacağı sırasıyla belirlenir.

var aa = new AdresApi('aa-container', {
        maps : ["gStr", "gSat", "gHib", "ySat", "yVec", "osm"]
    });

Varsayılanlar dışında harita altıklarını bağlamak için mapServers parametresi kullanılmalıdır.

var aa = new AdresApi('aa-container', {
        mapServers : { "gStr": {name: "Google Yol", url: "http://{s}.google.com/vt/lyrs=m&x={x}&y={y}&z={z}", subD: ["mt0","mt1","mt2","mt3"]} }
    });

Harita elementi, mapElement parametresiyle belirlenebilecek iki farklı şekilde yüklenebilir.

• Haritalar, eğer bir değer atanmamış ise sayfaya eklenmiş farklı her Adres API bileşeni için ayrı bir harita olarak arama çubuklarının alt kısmında açılacaktır.

• Sayfada var olan önceden tanımlanmış bir Leaflet harita elementi belirtilmiş ise gösterim için bu harita kullanılacaktır. Eğer belirtilmiş harita üzerinde herhangi bir katman tanımlanmamış ise Adres API kendi katmanlarını bu harita üzerinde oluşturacaktır.

var map_element = L.map('my-map-div');

var aa = new AdresApi('aa-container', {
        mapElement : map_element
    });

Mesajlar ¶

Arama çubuklarında gösterilen mesajlar ilgili parametreler yardımıyla düzenlenebilir.

var aa = new AdresApi('aa-container', {
        text : 'Adres Seçiniz ...',
        freeText : 'Açık Adres ...',
        cityText : 'İl Seçiniz ...',
        districtText : 'İlçe Seçiniz ...',
        quarterText : 'Mahalle Seçiniz ...',
        streetText : 'Cadde/Sokak Seçiniz ...',
        numberText : 'Adres detayı (site, numara ..) ...'
    });

Ön Değer ¶

Adres güncelleme sayfalarında, kaydedilmiş adreslerin gösterimi için initial parametresi ile Adres API bileşenine ön değer bildirilmelidir.

• address parametresi ile gösterilecek kayıtlı adres metni

• lat parametresi ile adrese ait enlem değeri

• lon parametresi ile adrese ait boylam değeri

girilerek ön değer tanımı yapılabilir.

lat ve lon parametrelerinin belirtilmesi durumunda verilen adres haritada da gösterilecektir.

var aa = new AdresApi('aa-container', {
        initial : { address : "Göztepe Mah. Nergis Cad. No:B/271B Göksu Evleri Beykoz/İstanbul",
                    lat : 40.279248,
                    lon : 29.809723 }
    });

Stil ¶

Adres API gösterim stilinin düzenlenebilmesi için aşağıda belirtilen CSS elementleri kullanılabilir .

• adres-api
• adres-api-detail
• adres-api-with-mode
• adres-api-close
• adres-api-geo
• adres-api-loading
• adres-api-input-main
• adres-api-input-detail
• adres-api-area
• adres-api-area1
• adres-api-area2
• adres-api-map
• adres-api-inner-map
• adres-api-dropdown
• adres-api-dropdown-content
• adres-api-suggestion
• adres-api-suggestions
• adres-api-show
• adres-api-hide
• adres-api-map-text
• adres-api-map-button
• adres-api-map-marker

Sonuçlar ¶

Sonuç Methodları ¶

Belirlenen adres sonuçlarına kullanıcın davranışlarına göre ayrışan üç farklı şekilde ulaşılabilir.

• Kullanıcın aramış olduğu adres detaylarına ulaşmak için:

var resultJson = aa.getSearchedValue();

• Kullanıcının harita üzerinde onayladığı adres detaylarına ulaşmak için:

var resultJson = aa.getConfirmedValue();

• Sırasıyla onaylanan veya aratılan adres detaylarından birine ulaşmak için:

var resultJson = aa.getValue();

Sonuç Seviyesi ¶

Adres sonuçlarının seviyelerini hiyerarşik olarak:

1. Derinlik : İl seviyesi
2. Derinlik : İlçe seviyesi
3. Derinlik : Mahalle seviyesi
4. Derinlik : Yol (Cadde/Sokak) seviyesi
5. Derinlik : Nokta (POI/No) seviyesi

şeklinde sıralayabiliriz. Kullanıcıya bağlı olarak getValue() methodu ile alınacak sonuç seviyeleri ise:

• Seçim yapılmamış : Geocoding sonucu olarak 0 ila 5 arası derinlik
• Birinci derinlik seçilmiş : Geocoding sonucu 1 ila 5 arası derinlik
• İkinci derinlik seçilmiş : Geocoding sonucu 2 ila 5 arası derinlik
• Üçüncü derinlik seçilmiş : Geocoding sonucu 3 ila 5 arası derinlik
• Dördüncü derinlik seçilmiş : Geocoding sonucu 4üncü veya 5inci derinlik
• Harita Onaylanmış : Seçilmiş olan 4ncü veya geocoding sonucu 5nci derinlik

şeklinde olacaktır.

Sonuç Formatı ¶

Sonuç json içeriği aşağıda belirtildiği gibidir:

• code : Derinliğe bağlı olarak bileşen kodu

• address : Adres tam metni

• detail : Aranan adres detayı

• geocode : Geocode sonuç json’ı

X-Mashape-Authorization: APIKEY
Accept: text/plain

Content-Type: application/json

{
  "sorgu": "Dikilitaş Sok İstanbul",
  "bilesenler": "+il -ilç -mah -poi -cad +sok -bno",
  "beyan_skor": "1000",
  "arama_tip": "SOK",
  "eslesen_adet": "5",
  "sonuc_kumesi": [
    {
      "sembolik": "<ilç> <mh> [sok]",
      "skor": "633",
      "odak_tip": "SOK",
      "ilce": "BEYKOZ",
      "mah": "YENİ MAHALLE MH.",
      "odak_birim": "DİKİLİTAŞ SK.",
      "odak_alt_ad": "G-2 SK.",
      "pk": "34815",
      "enlem": "41.07287",
      "boylam": "29.076929",
      "posta_adresi": "Yeni Mahalle Mh. Dikilitaş Sk.(G-2 Sk.) 34815 Beykoz/İstanbul",
      "sira_no": "1"
    },
    {
      "sembolik": "<ilç> <mh> [sok]",
      "skor": "633",
      "odak_tip": "SOK",
      "ilce": "SULTANBEYLİ",
      "mah": "MECİDİYE MH.",
      "odak_birim": "DİKİLİTAŞ SK.",
      "enlem": "40.958003",
      "boylam": "29.294812",
      "posta_adresi": "Mecidiye Mh. Dikilitaş Sk. Sultanbeyli İstanbul",
      "sira_no": "2"
    },
    {
      "sembolik": "<ilç> <mh> [sok]",
      "skor": "633",
      "odak_tip": "SOK",
      "ilce": "BEŞİKTAŞ",
      "mah": "DİKİLİTAŞ MH.",
      "odak_birim": "DİKİLİTAŞ SK.",
      "enlem": "41.055319",
      "boylam": "29.005501",
      "posta_adresi": "Dikilitaş Mh. Dikilitaş Sk. Beşiktaş İstanbul",
      "sira_no": "3"
    },
    {
      "sembolik": "<ilç> <mh> [sok]",
      "skor": "633",
      "odak_tip": "SOK",
      "ilce": "KARTAL",
      "mah": "KORDONBOYU MH.",
      "odak_birim": "DİKİLİTAŞ SK.",
      "enlem": "40.893682",
      "boylam": "29.174463",
      "posta_adresi": "Kordonboyu Mh. Dikilitaş Sk. Kartal İstanbul",
      "sira_no": "4"
    },
    {
      "sembolik": "<ilç> <mh> [yol]+",
      "skor": "633",
      "odak_tip": "YOL",
      "ilce": "BEŞİKTAŞ",
      "mah": "DİKİLİTAŞ MH.",
      "odak_birim": "DİKİLİTAŞ ÇK.",
      "odak_alt_ad": "DİKRAT ÇK.",
      "enlem": "41.053935",
      "boylam": "29.004759",
      "posta_adresi": "Dikilitaş Mh. Dikilitaş Çk. Beşiktaş İstanbul",
      "sira_no": "5"
    }
  ]
}

Lisans ¶

© Gece Yazılım