জিওকোডিং এপিআই-এর সংস্করণ ৪ এখন সর্বসাধারণের জন্য উপলব্ধ। সংস্করণ ৪-এ স্থানান্তরিত হতে, সংস্করণ ৩ থেকে সংস্করণ ৪-এ স্থানান্তরের নির্দেশিকাটি দেখুন।

এই পৃষ্ঠাটি Cloud Translation API অনুবাদ করেছে।

জিওকোডিং অনুরোধ এবং প্রতিক্রিয়া

ইউরোপীয় অর্থনৈতিক অঞ্চল (EEA) ডেভেলপাররা

অনুরোধ

একটি জিওকোডিং এপিআই অনুরোধের রূপটি নিম্নরূপ:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

যেখানে outputFormat নিম্নলিখিত মানগুলির যেকোনো একটি হতে পারে:

json (প্রস্তাবিত) মানে হলো জাভাস্ক্রিপ্ট অবজেক্ট নোটেশন (JSON)-এ আউটপুট; অথবা
xml বলতে XML-এ আউটপুট বোঝায়।

HTTPS আবশ্যক।

কিছু প্যারামিটার আবশ্যক এবং কিছু ঐচ্ছিক। ইউআরএল-এর প্রচলিত রীতি অনুযায়ী, প্যারামিটারগুলো অ্যামপারস্যান্ড ( & ) চিহ্ন দিয়ে আলাদা করা হয়।

এই পৃষ্ঠার বাকি অংশে জিওকোডিং এবং রিভার্স জিওকোডিং আলাদাভাবে বর্ণনা করা হয়েছে, কারণ প্রতিটি ধরণের অনুরোধের জন্য ভিন্ন ভিন্ন প্যারামিটার উপলব্ধ থাকে।

জিওকোডিং (অক্ষাংশ/দ্রাঘিমাংশ অনুসন্ধান) প্যারামিটার

একটি জিওকোডিং অনুরোধে প্রয়োজনীয় প্যারামিটারসমূহ:

key — আপনার অ্যাপ্লিকেশনের API কী। এই কী কোটা ব্যবস্থাপনার উদ্দেশ্যে আপনার অ্যাপ্লিকেশনকে শনাক্ত করে। কীভাবে একটি কী পাবেন তা জানুন।

অনুরোধে আপনাকে অবশ্যই address অথবা components অথবা উভয়ই উল্লেখ করতে হবে:

address — যে রাস্তার ঠিকানা বা প্লাস কোডটি আপনি জিওকোড করতে চান। দ্রষ্টব্য: ঠিকানা জিওকোডিং অক্ষাংশ এবং দ্রাঘিমাংশের স্থানাঙ্ক, অথবা অন্যান্য অসংগঠিত স্ট্রিং যা কোনো ঠিকানা বা প্লাস কোডকে প্রতিনিধিত্ব করে না, তা সমাধান করে না। এই ধরনের স্ট্রিং ব্যবহার করে করা অনুরোধগুলি সমর্থিত নয় এবং এর ফলে ত্রুটিপূর্ণ প্রতিক্রিয়া বা অনির্দিষ্ট আচরণ দেখা দিতে পারে। অসমর্থিত কোয়েরিগুলির উদাহরণ নিচে দেওয়া হলো:

কোয়েরি টাইপ	উদাহরণ
অক্ষাংশ ও দ্রাঘিমাংশের স্থানাঙ্ক। এর পরিবর্তে বিপরীত জিওকোডিং ব্যবহার করুন।	"৩৭.৪২২১৩১,-১২২.০৮৪৮০১"
একটি কোয়েরিতে একাধিক স্থান, রাস্তা বা শহরের নামের মতো অনেক বেশি ধারণা বা সীমাবদ্ধতা।	"মার্কেট স্ট্রিট সান ফ্রান্সিসকো সান হোসে বিমানবন্দর"
গুগল ম্যাপে ডাক ঠিকানার যে উপাদানগুলো দেখানো হয় না	"জন স্মিথের তত্ত্বাবধানে, ১২৩ মেইন স্ট্রিট" পোস্ট অফিস বক্স ১৩ সান ফ্রান্সিসকো
ব্যবসা, চেইন বা ক্যাটাগরির নাম, সেইসাথে এমন স্থান যেখানে এই সত্তাগুলো উপলব্ধ নয়।	ডালাস, টেক্সাসের নিকটবর্তী টেসকো
একাধিক ব্যাখ্যা সহ দ্ব্যর্থক প্রশ্ন	চার্জার ড্রপ-অফ
ঐতিহাসিক নাম যা এখন আর ব্যবহৃত হয় না	"মিডলসেক্স যুক্তরাজ্য"
অ-ভূস্থানিক উপাদান বা উদ্দেশ্য	ভেনচুরা বন্দরে কয়টি নৌকা আছে?
অনানুষ্ঠানিক বা শখের নাম	"জেঙ্গা" "দ্য হেল্টার স্কেল্টার"

সংশ্লিষ্ট দেশের জাতীয় ডাক পরিষেবা কর্তৃক ব্যবহৃত বিন্যাস অনুসারে ঠিকানা উল্লেখ করুন। ব্যবসার নাম এবং ইউনিট, স্যুট বা ফ্লোর নম্বরের মতো অতিরিক্ত ঠিকানার উপাদান পরিহার করা উচিত। রাস্তার ঠিকানার উপাদানগুলোকে স্পেস দিয়ে আলাদা করতে হবে (এখানে যা url-escaped করে %20 হিসেবে দেখানো হয়েছে):

address=24%20Sussex%20Drive%20Ottawa%20ON

প্লাস কোডগুলো এখানে দেখানো অনুযায়ী ফরম্যাট করুন (প্লাস চিহ্নগুলোকে ইউআরএল-এস্কেপ করে %2B এবং স্পেসগুলোকে ইউআরএল-এস্কেপ করে %20 করা হয়):

গ্লোবাল কোড হলো একটি ৪ অক্ষরের এরিয়া কোড এবং ৬ বা তার বেশি অক্ষরের লোকাল কোড (যেমন: 849VCWC8+R9 হলো 849VCWC8%2BR9 )।
যৌগিক কোড হলো ৬ বা ততোধিক অক্ষরের একটি স্থানীয় কোড যার সাথে একটি সুস্পষ্ট অবস্থান উল্লেখ থাকে (যেমন: CWC8+R9 Mountain View, CA, USA হলো CWC8%2BR9%20Mountain%20View%20CA%20USA )।

components — একটি কম্পোনেন্টস ফিল্টার যার উপাদানগুলো একটি পাইপ ( | ) চিহ্ন দিয়ে আলাদা করা থাকে। যদি কোনো address প্রদান করা হয়, তবে কম্পোনেন্টস ফিল্টারটি একটি ঐচ্ছিক প্যারামিটার হিসেবেও গৃহীত হয়। কম্পোনেন্টস ফিল্টারের প্রতিটি উপাদান একটি component:value জোড়া নিয়ে গঠিত এবং এটি জিওকোডার থেকে প্রাপ্ত ফলাফলকে সম্পূর্ণরূপে সীমাবদ্ধ করে। কম্পোনেন্ট ফিল্টারিং সম্পর্কে আরও তথ্য নিচে দেখুন।

অতিরিক্ত নির্দেশনার জন্য প্রায়শই জিজ্ঞাসিত প্রশ্নাবলী (FAQ) দেখুন।

জিওকোডিং অনুরোধে ঐচ্ছিক প্যারামিটারসমূহ:

bounds — ভিউপোর্টের বাউন্ডিং বক্স, যার মধ্যে জিওকোড ফলাফলকে আরও সুস্পষ্টভাবে পক্ষপাতদুষ্ট করা হবে। এই প্যারামিটারটি জিওকোডারের ফলাফলকে শুধুমাত্র প্রভাবিত করবে, সম্পূর্ণরূপে সীমাবদ্ধ করবে না। (আরও তথ্যের জন্য নিচে ‘ভিউপোর্ট বায়াসিং’ দেখুন।)
language — যে ভাষায় ফলাফল ফেরত দেওয়া হবে।
- সমর্থিত ভাষাগুলোর তালিকা দেখুন। গুগল প্রায়শই সমর্থিত ভাষাগুলো হালনাগাদ করে, তাই এই তালিকাটি সম্পূর্ণ নাও হতে পারে।
- যদি language সরবরাহ করা না হয়, তাহলে জিওকোডার Accept-Language হেডারে নির্দিষ্ট করা পছন্দের ভাষা, অথবা যে ডোমেইন থেকে অনুরোধটি পাঠানো হয়েছে তার স্থানীয় ভাষা ব্যবহার করার চেষ্টা করে।
- জিওকোডার এমন একটি রাস্তার ঠিকানা দেওয়ার জন্য যথাসাধ্য চেষ্টা করে যা ব্যবহারকারী এবং স্থানীয় বাসিন্দা উভয়ের কাছেই পাঠযোগ্য। সেই লক্ষ্য অর্জনের জন্য, এটি পছন্দের ভাষাটি অনুসরণ করে রাস্তার ঠিকানাগুলো স্থানীয় ভাষায় ফেরত দেয় এবং প্রয়োজনে ব্যবহারকারীর পাঠযোগ্য লিপিতে তা প্রতিবর্ণীকরণ করে। অন্য সব ঠিকানা পছন্দের ভাষাতেই ফেরত দেওয়া হয়। ঠিকানার সমস্ত উপাদান একই ভাষায় ফেরত দেওয়া হয়, যা প্রথম উপাদান থেকে বেছে নেওয়া হয়।
- পছন্দের ভাষায় কোনো নাম পাওয়া না গেলে, জিওকোডার সবচেয়ে কাছাকাছি মিল থাকা নামটি ব্যবহার করে।
- এপিআই যে ফলাফলগুলো ফেরত দেবে এবং সেগুলো যে ক্রমে ফেরত আসবে, তার ওপর পছন্দের ভাষার সামান্য প্রভাব রয়েছে। জিওকোডার ভাষার ওপর নির্ভর করে সংক্ষিপ্ত রূপগুলোকে ভিন্নভাবে ব্যাখ্যা করে, যেমন রাস্তার প্রকারভেদের সংক্ষিপ্ত রূপ, অথবা এমন সমার্থক শব্দ যা একটি ভাষায় বৈধ হলেও অন্যটিতে নয়। উদাহরণস্বরূপ, হাঙ্গেরীয় ভাষায় utca এবং tér হলো যথাক্রমে রাস্তা এবং চত্বরের সমার্থক শব্দ।
region — অঞ্চলের কোড, যা একটি ccTLD ("টপ-লেভেল ডোমেইন") দুই-অক্ষরের মান হিসাবে নির্দিষ্ট করা হয়। এই প্যারামিটারটি জিওকোডারের ফলাফলকে শুধুমাত্র প্রভাবিত করবে, সম্পূর্ণরূপে সীমাবদ্ধ করবে না। (আরও তথ্যের জন্য নিচে ‘অঞ্চল পক্ষপাত’ দেখুন।) এই প্যারামিটারটি প্রযোজ্য আইনের উপর ভিত্তি করেও ফলাফলকে প্রভাবিত করতে পারে।
components — একটি কম্পোনেন্টস ফিল্টার যার উপাদানগুলো একটি পাইপ ( | ) দ্বারা পৃথক করা থাকে। অনুরোধে কোনো address অন্তর্ভুক্ত না থাকলে কম্পোনেন্টস ফিল্টারটি আবশ্যক । কম্পোনেন্টস ফিল্টারের প্রতিটি উপাদান একটি component:value জোড়া নিয়ে গঠিত এবং এটি জিওকোডার থেকে প্রাপ্ত ফলাফলকে সম্পূর্ণরূপে সীমাবদ্ধ করে। কম্পোনেন্ট ফিল্টারিং সম্পর্কে আরও তথ্য নিচে দেখুন।
extra_computations — রেসপন্সে নিম্নলিখিত অতিরিক্ত ফিচারগুলো নির্দিষ্ট করতে এই প্যারামিটারটি ব্যবহার করুন:
- ADDRESS_DESCRIPTORS — আরও বিস্তারিত তথ্যের জন্য ঠিকানার বিবরণ দেখুন।
- BUILDING_AND_ENTRANCES — আরও বিস্তারিত তথ্যের জন্য প্রবেশপথ ও ভবনের রূপরেখা দেখুন।
একই API অনুরোধের জন্য এই বৈশিষ্ট্যগুলির একাধিক সক্রিয় করতে, প্রতিটি বৈশিষ্ট্যের জন্য অনুরোধে extra_computations প্যারামিটারটি অন্তর্ভুক্ত করুন, উদাহরণস্বরূপ:
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```

প্রতিক্রিয়া

জিওকোডিং প্রতিক্রিয়াগুলি URL অনুরোধের মধ্যে output ফ্ল্যাগ দ্বারা নির্দেশিত বিন্যাসে, অথবা ডিফল্টরূপে JSON বিন্যাসে ফেরত দেওয়া হয়।

এই উদাহরণে, জিওকোডিং এপিআই "1600 Amphitheatre Parkway, Mountain View, CA" ঠিকানাটির উপর একটি কোয়েরির জন্য একটি json রেসপন্স অনুরোধ করছে।

এই অনুরোধটি JSON output ফ্ল্যাগের ব্যবহার প্রদর্শন করে:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

এই অনুরোধটি XML output ফ্ল্যাগ ব্যবহারের পদ্ধতি প্রদর্শন করে:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

নমুনা JSON এবং XML প্রতিক্রিয়াগুলো দেখতে নিচের ট্যাবগুলো নির্বাচন করুন।

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

লক্ষ্য করুন যে JSON প্রতিক্রিয়াটিতে দুটি রুট উপাদান রয়েছে:

"status" অনুরোধ সম্পর্কিত মেটাডেটা থাকে। নিচে স্ট্যাটাস কোডগুলো দেখুন।
"results" এ জিওকোডেড ঠিকানার তথ্য এবং জ্যামিতিক তথ্যের একটি অ্যারে থাকে।

সাধারণত, ঠিকানা অনুসন্ধানের ক্ষেত্রে "results" অ্যারেতে কেবল একটি এন্ট্রিই ফেরত দেওয়া হয়, যদিও ঠিকানা সংক্রান্ত জিজ্ঞাসা অস্পষ্ট হলে জিওকোডার একাধিক ফলাফলও ফেরত দিতে পারে।

এক্সএমএল

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

উল্লেখ্য যে, XML রেসপন্সটি একটিমাত্র <GeocodeResponse> এবং দুটি টপ-লেভেল এলিমেন্ট নিয়ে গঠিত:

<status> এ অনুরোধ সম্পর্কিত মেটাডেটা থাকে। নিচে স্ট্যাটাস কোডগুলো দেখুন।
শূন্য বা তার বেশি <result> এলিমেন্ট, যার প্রতিটিতে জিওকোডেড ঠিকানা এবং জ্যামিতিক তথ্যের একটি করে সেট থাকে।

XML রেসপন্সটি JSON রেসপন্সের চেয়ে যথেষ্ট দীর্ঘ হয়। এই কারণে, আমরা সুপারিশ করি যে আপনি পছন্দের আউটপুট ফ্ল্যাগ হিসেবে json ব্যবহার করুন, যদি না আপনার সার্ভিসের জন্য কোনো কারণে xml প্রয়োজন হয়। এছাড়াও, XML ট্রি প্রসেস করার ক্ষেত্রে কিছু সতর্কতা অবলম্বন করা প্রয়োজন, যাতে আপনি সঠিক নোড এবং এলিমেন্ট রেফারেন্স করেন। আউটপুট প্রসেসিংয়ের জন্য কিছু প্রস্তাবিত ডিজাইন প্যাটার্ন জানতে 'Parsing XML with XPath' দেখুন।

XML ফলাফলগুলো একটি রুট <GeocodeResponse> এলিমেন্টের মধ্যে আবদ্ধ থাকে।
JSON-এ একাধিক উপাদানযুক্ত এন্ট্রিগুলিকে বহুবচন অ্যারে ( types ) দ্বারা চিহ্নিত করা হয়, অন্যদিকে XML-এ এগুলিকে একাধিক একবচন উপাদান ( <type> ) ব্যবহার করে চিহ্নিত করা হয়।
JSON-এ খালি অ্যারের মাধ্যমে ফাঁকা এলিমেন্ট নির্দেশ করা হয়, কিন্তু XML-এ এই ধরনের কোনো এলিমেন্টের অনুপস্থিতির মাধ্যমে তা বোঝানো হয়। উদাহরণস্বরূপ, যে রেসপন্স কোনো ফলাফল তৈরি করে না, সেটি JSON-এ একটি খালি results অ্যারে রিটার্ন করবে, কিন্তু XML-এ কোনো <result> এলিমেন্ট থাকবে না।

স্ট্যাটাস কোড

জিওকোডিং রেসপন্স অবজেক্টের অন্তর্গত "status" ফিল্ডটিতে অনুরোধের অবস্থা থাকে এবং জিওকোডিং কেন কাজ করছে না তা খুঁজে বের করতে সাহায্য করার জন্য এতে ডিবাগিং তথ্যও থাকতে পারে। "status" ফিল্ডটিতে নিম্নলিখিত মানগুলি থাকতে পারে:

"OK" নির্দেশ করে যে কোনো ত্রুটি ঘটেনি; ঠিকানাটি সফলভাবে পার্স করা হয়েছে এবং অন্তত একটি জিওকোড ফেরত এসেছে।
"ZERO_RESULTS" নির্দেশ করে যে জিওকোডিং সফল হয়েছে কিন্তু কোনো ফলাফল পাওয়া যায়নি। জিওকোডারকে যদি অস্তিত্বহীন কোনো address দেওয়া হয়, তবে এমনটা ঘটতে পারে।
OVER_DAILY_LIMIT নিম্নলিখিত যেকোনো একটিকে নির্দেশ করে:
- এপিআই কী অনুপস্থিত অথবা অবৈধ।
- আপনার অ্যাকাউন্টে বিলিং চালু করা হয়নি।
- স্বেচ্ছায় নির্ধারিত ব্যবহারের সীমা অতিক্রম করা হয়েছে।
- প্রদত্ত অর্থপ্রদানের পদ্ধতিটি আর বৈধ নয় (উদাহরণস্বরূপ, ক্রেডিট কার্ডের মেয়াদ শেষ হয়ে গেছে)।
এটি কীভাবে ঠিক করতে হয় তা জানতে ম্যাপস FAQ দেখুন।
"OVER_QUERY_LIMIT" নির্দেশ করে যে আপনি আপনার কোটা অতিক্রম করেছেন।
"REQUEST_DENIED" নির্দেশ করে যে আপনার অনুরোধটি প্রত্যাখ্যান করা হয়েছে।
"INVALID_REQUEST" সাধারণত বোঝায় যে কোয়েরিটি ( address , components বা latlng ) অনুপস্থিত।
"UNKNOWN_ERROR" নির্দেশ করে যে সার্ভার ত্রুটির কারণে অনুরোধটি প্রক্রিয়া করা যায়নি। আপনি পুনরায় চেষ্টা করলে অনুরোধটি সফল হতে পারে।

ত্রুটির বার্তা

যখন জিওকোডার OK ছাড়া অন্য কোনো স্ট্যাটাস কোড ফেরত দেয়, তখন Geocoding response অবজেক্টের মধ্যে একটি অতিরিক্ত error_message ফিল্ড থাকতে পারে। এই ফিল্ডটিতে প্রদত্ত স্ট্যাটাস কোডটির পেছনের কারণ সম্পর্কে আরও বিস্তারিত তথ্য থাকে।

ফলাফল

যখন জিওকোডার ফলাফল ফেরত দেয়, তখন সেগুলোকে একটি (JSON) results অ্যারের মধ্যে রাখে। এমনকি যদি জিওকোডার কোনো ফলাফল ফেরত না দেয় (যেমন ঠিকানাটির অস্তিত্ব না থাকলে), তবুও এটি একটি খালি results অ্যারে ফেরত দেয়। (XML রেসপন্সে শূন্য বা তার বেশি <result> এলিমেন্ট থাকে।)

একটি সাধারণ ফলাফলে নিম্নলিখিত ক্ষেত্রগুলি থাকে:

` types[] ` অ্যারেটি ফেরত আসা ফলাফলের ধরন নির্দেশ করে। এই অ্যারেটিতে শূন্য বা তার বেশি সংখ্যক ট্যাগের একটি সেট থাকে, যা ফলাফলে ফেরত আসা ফিচারের ধরন শনাক্ত করে। উদাহরণস্বরূপ, "শিকাগো" এর একটি জিওকোড "লোকালিটি" ফেরত দেয়, যা নির্দেশ করে যে "শিকাগো" একটি শহর, এবং "পলিটিক্যাল" ফেরত দেয়, যা নির্দেশ করে যে এটি একটি রাজনৈতিক সত্তা। আরও তথ্যের জন্য, 'অ্যাড্রেস টাইপস' এবং 'অ্যাড্রেস কম্পোনেন্ট টাইপস' দেখুন।
formatted_address হলো একটি স্ট্রিং, যাতে এই অবস্থানের পাঠযোগ্য ঠিকানাটি থাকে।
অনেক ক্ষেত্রে এই ঠিকানাটি ডাক ঠিকানার সমতুল্য হয়। উল্লেখ্য যে, যুক্তরাজ্যসহ কিছু দেশ লাইসেন্স সংক্রান্ত বিধিনিষেধের কারণে প্রকৃত ডাক ঠিকানা বিতরণের অনুমতি দেয় না।
বিন্যাসকৃত ঠিকানাটি যৌক্তিকভাবে এক বা একাধিক ঠিকানার উপাদান দ্বারা গঠিত। উদাহরণস্বরূপ, "111 8th Avenue, New York, NY" ঠিকানাটি নিম্নলিখিত উপাদানগুলি নিয়ে গঠিত: "111" (রাস্তার নম্বর), "8th Avenue" (পথ), "New York" (শহর) এবং "NY" (মার্কিন যুক্তরাষ্ট্রের রাজ্য)।
প্রোগ্রাম্যাটিকভাবে ফরম্যাট করা ঠিকানা পার্স করবেন না। এর পরিবর্তে, আপনার ঠিকানার স্বতন্ত্র উপাদানগুলো ব্যবহার করা উচিত, যা এপিআই রেসপন্সে ফরম্যাট করা ঠিকানা ফিল্ডের পাশাপাশি অন্তর্ভুক্ত থাকে।
address_components[] হলো একটি অ্যারে, যেখানে এই ঠিকানার জন্য প্রযোজ্য পৃথক উপাদানগুলো থাকে।
ঠিকানার প্রতিটি অংশে সাধারণত নিম্নলিখিত ক্ষেত্রগুলি থাকে:
- types[] হলো একটি অ্যারে যা অ্যাড্রেস কম্পোনেন্টের ধরন নির্দেশ করে। যখন কোনো অ্যাড্রেস কম্পোনেন্টের জন্য কোনো পরিচিত ধরন থাকে না, তখন সেই কম্পোনেন্টের types অ্যারেটি খালি থাকতে পারে। প্রয়োজন অনুযায়ী API নতুন ধরনের মান যোগ করতে পারে। আরও তথ্যের জন্য, Address types এবং address component types দেখুন।
- long_name হলো জিওকোডার দ্বারা ফেরত প্রাপ্ত ঠিকানার উপাদানের পূর্ণাঙ্গ পাঠ্য বিবরণ বা নাম।
- short_name হলো ঠিকানার অংশের একটি সংক্ষিপ্ত লিখিত নাম, যদি তা উপলব্ধ থাকে। উদাহরণস্বরূপ, আলাস্কা রাজ্যের ঠিকানার অংশের long_name হতে পারে "Alaska" এবং দুই অক্ষরের ডাক বিভাগের সংক্ষিপ্ত রূপ ব্যবহার করে short_name "AK"।
address_components[] অ্যারে সম্পর্কে নিম্নলিখিত তথ্যগুলো লক্ষ্য করুন:
- ঠিকানার উপাদানগুলোর অ্যারেতে formatted_address চেয়ে বেশি উপাদান থাকতে পারে।
- অ্যারেটিতে formatted_address এ অন্তর্ভুক্ত রাজনৈতিক সত্তাগুলো ছাড়া, ঠিকানা আছে এমন সব রাজনৈতিক সত্তা আবশ্যিকভাবেই অন্তর্ভুক্ত থাকে না। একটি নির্দিষ্ট ঠিকানা আছে এমন সমস্ত রাজনৈতিক সত্তা পুনরুদ্ধার করতে, আপনার রিভার্স জিওকোডিং ব্যবহার করা উচিত এবং অনুরোধের প্যারামিটার হিসাবে ঠিকানাটির অক্ষাংশ/দ্রাঘিমাংশ প্রেরণ করা উচিত।
- অনুরোধগুলোর মধ্যে প্রতিক্রিয়ার বিন্যাস একই থাকবে এমন কোনো নিশ্চয়তা নেই। বিশেষ করে, অনুরোধ করা ঠিকানার উপর ভিত্তি করে address_components এর সংখ্যা পরিবর্তিত হয় এবং একই ঠিকানার জন্য সময়ের সাথে সাথে তা পরিবর্তিত হতে পারে। একটি কম্পোনেন্ট অ্যারের মধ্যে তার অবস্থান পরিবর্তন করতে পারে। কম্পোনেন্টটির ধরন পরিবর্তিত হতে পারে। পরবর্তী কোনো প্রতিক্রিয়ায় একটি নির্দিষ্ট কম্পোনেন্ট অনুপস্থিত থাকতে পারে।
কম্পোনেন্টগুলোর অ্যারে পরিচালনা করার জন্য, আপনার রেসপন্সটি পার্স করা এবং এক্সপ্রেশনের মাধ্যমে উপযুক্ত মান নির্বাচন করা উচিত। রেসপন্স পার্স করার নির্দেশিকাটি দেখুন।
postcode_localities[] হলো একটি অ্যারে যা একটি পোস্টাল কোডের অন্তর্ভুক্ত সর্বোচ্চ ১০০টি এলাকাকে নির্দেশ করে। এটি শুধুমাত্র তখনই উপস্থিত থাকে যখন ফলাফলটি এমন একটি পোস্টাল কোড হয় যাতে একাধিক এলাকা থাকে।
geometry নিম্নলিখিত তথ্য রয়েছে:
- location জিওকোডেড অক্ষাংশ ও দ্রাঘিমাংশের মান থাকে। সাধারণ ঠিকানা খোঁজার ক্ষেত্রে এই ফিল্ডটি সাধারণত সবচেয়ে গুরুত্বপূর্ণ।
- location_type নির্দিষ্ট অবস্থান সম্পর্কে অতিরিক্ত তথ্য সংরক্ষণ করে। বর্তমানে নিম্নলিখিত মানগুলি সমর্থিত:
  - "ROOFTOP" নির্দেশ করে যে প্রত্যাবর্তিত ফলাফলটি একটি সুনির্দিষ্ট জিওকোড, যার জন্য আমাদের কাছে রাস্তার ঠিকানা পর্যন্ত নির্ভুল অবস্থানের তথ্য রয়েছে।
  - "RANGE_INTERPOLATED" নির্দেশ করে যে প্রত্যাবর্তিত ফলাফলটি দুটি সুনির্দিষ্ট বিন্দুর (যেমন সংযোগস্থল) মধ্যে ইন্টারপোলেট করা একটি আনুমানিক চিত্র (সাধারণত রাস্তার ক্ষেত্রে)। যখন কোনো রাস্তার ঠিকানার জন্য রুফটপ জিওকোড পাওয়া যায় না, তখন সাধারণত ইন্টারপোলেটেড ফলাফল ফেরত দেওয়া হয়।
  - "GEOMETRIC_CENTER" নির্দেশ করে যে প্রত্যাবর্তিত ফলাফলটি একটি পলিলাইন (উদাহরণস্বরূপ, একটি রাস্তা) বা বহুভুজ (অঞ্চল)-এর জ্যামিতিক কেন্দ্র।
  - "APPROXIMATE" নির্দেশ করে যে প্রত্যাবর্তিত ফলাফলটি আনুমানিক।
- viewport ফেরত আসা ফলাফল প্রদর্শনের জন্য প্রস্তাবিত ভিউপোর্টটি থাকে, যা দুটি অক্ষাংশ ও দ্রাঘিমাংশের মান হিসাবে নির্দিষ্ট করা হয় এবং যা ভিউপোর্ট বাউন্ডিং বক্সের southwest ও northeast কোণকে সংজ্ঞায়িত করে। সাধারণত, কোনো ব্যবহারকারীকে ফলাফল দেখানোর সময় সেটিকে ফ্রেম করার জন্য ভিউপোর্ট ব্যবহার করা হয়।
- bounds (ঐচ্ছিকভাবে ফেরত দেওয়া হয়) সেই বাউন্ডিং বক্সটি সংরক্ষণ করে যা ফেরত আসা ফলাফলকে সম্পূর্ণরূপে ধারণ করতে পারে। উল্লেখ্য যে, এই সীমানাগুলো প্রস্তাবিত ভিউপোর্টের সাথে নাও মিলতে পারে। (উদাহরণস্বরূপ, সান ফ্রান্সিসকোর মধ্যে ফারালন দ্বীপপুঞ্জ অন্তর্ভুক্ত, যা প্রযুক্তিগতভাবে শহরের অংশ, কিন্তু সম্ভবত ভিউপোর্টে ফেরত দেওয়া উচিত নয়।)
plus_code ( ওপেন লোকেশন কোড এবং প্লাস কোডসমূহ দেখুন) হলো অক্ষাংশ এবং দ্রাঘিমাংশের স্থানাঙ্ক থেকে প্রাপ্ত একটি এনকোডেড অবস্থান নির্দেশক, যা ১/৮০০০ ডিগ্রি বাই ১/৮০০০ ডিগ্রি (নিরক্ষীয় অঞ্চলে প্রায় ১৪মি x ১৪মি) বা তার চেয়ে ছোট একটি এলাকাকে প্রতিনিধিত্ব করে। যেসব জায়গায় ঠিকানা নেই (যেমন যেখানে ভবনগুলোর নম্বর দেওয়া নেই বা রাস্তাগুলোর নাম নেই), সেখানে রাস্তার ঠিকানার বিকল্প হিসেবে প্লাস কোড ব্যবহার করা যেতে পারে। এপিআই সবসময় প্লাস কোড ফেরত দেয় না।
যখন পরিষেবাটি একটি প্লাস কোড ফেরত দেয়, তখন সেটি একটি গ্লোবাল কোড এবং একটি কম্পাউন্ড কোড হিসাবে বিন্যস্ত করা হয়:
- global_code হলো ৪ অক্ষরের একটি এলাকা কোড এবং ৬ বা তার বেশি অক্ষরের স্থানীয় কোড (849VCWC8+R9)।
- compound_code হলো ৬ অক্ষর বা তার বেশি দৈর্ঘ্যের একটি স্থানীয় কোড, যার সাথে একটি সুস্পষ্ট অবস্থান (CWC8+R9, Mountain View, CA, USA) উল্লেখ থাকে। প্রোগ্রামগতভাবে এই বিষয়বস্তু পার্স করবেন না।
উপলব্ধ থাকলে, এপিআই গ্লোবাল কোড এবং কম্পাউন্ড কোড উভয়ই ফেরত দেয়। তবে, ফলাফলটি যদি কোনো দূরবর্তী স্থানে (যেমন, মহাসাগর বা মরুভূমি) হয়, তাহলে শুধুমাত্র গ্লোবাল কোডটি ফেরত দেওয়া হতে পারে।
partial_match নির্দেশ করে যে জিওকোডার মূল অনুরোধের জন্য একটি সঠিক মিল খুঁজে পায়নি, যদিও এটি অনুরোধ করা ঠিকানার একটি অংশের সাথে মিল খুঁজে পেয়েছে। আপনি মূল অনুরোধটিতে কোনো বানান ভুল এবং/অথবা অসম্পূর্ণ ঠিকানা আছে কিনা তা খতিয়ে দেখতে পারেন।
আপনার অনুরোধে দেওয়া এলাকার মধ্যে যে রাস্তার ঠিকানাগুলো নেই, সেগুলোর ক্ষেত্রে প্রায়শই আংশিক মিল পাওয়া যায়। একই এলাকার মধ্যে দুই বা ততোধিক ঠিকানা মিলে গেলেও আংশিক মিল পাওয়া যেতে পারে। উদাহরণস্বরূপ, "Hillpar St, Bristol, UK" অনুরোধটি Henry Street এবং Henrietta Street উভয়ের জন্যই আংশিক মিল দেখাবে। মনে রাখবেন, যদি কোনো অনুরোধে ঠিকানার কোনো অংশে বানান ভুল থাকে, তাহলে জিওকোডিং পরিষেবাটি একটি বিকল্প ঠিকানার পরামর্শ দিতে পারে। এইভাবে দেওয়া পরামর্শগুলোকেও আংশিক মিল হিসেবে চিহ্নিত করা হবে।
place_id হলো একটি অনন্য শনাক্তকারী যা অন্যান্য গুগল এপিআই-এর সাথে ব্যবহার করা যায়। উদাহরণস্বরূপ, আপনি কোনো স্থানীয় ব্যবসার বিবরণ, যেমন ফোন নম্বর, খোলার সময়, ব্যবহারকারীর পর্যালোচনা এবং আরও অনেক কিছু পেতে Places API অনুরোধে place_id ব্যবহার করতে পারেন। প্লেস আইডি ওভারভিউ দেখুন।

ঠিকানার প্রকারভেদ এবং ঠিকানার উপাদানের প্রকারভেদ

রেসপন্সের ` types অ্যারেটি ঠিকানার ধরন নির্দেশ করে। ঠিকানার ধরনের উদাহরণ হলো রাস্তার ঠিকানা, দেশ বা রাজনৈতিক সত্তা। address_component ফিল্ডের ` types অ্যারেটি ঠিকানার প্রতিটি অংশের ধরন নির্দেশ করে। এর উদাহরণ হলো রাস্তার নম্বর বা দেশ।

ঠিকানার একাধিক প্রকার থাকতে পারে। এই প্রকারগুলোকে 'ট্যাগ' হিসেবে বিবেচনা করা যেতে পারে। উদাহরণস্বরূপ, অনেক শহরকে political এবং locality প্রকার দিয়ে ট্যাগ করা হয়।

অ্যাড্রেস টাইপ এবং অ্যাড্রেস কম্পোনেন্ট টাইপ উভয় অ্যারেতেই নিম্নলিখিত টাইপগুলো সমর্থিত এবং ফেরত দেওয়া হয়:

ঠিকানার ধরণ	বর্ণনা
`street_address`	একটি সঠিক রাস্তার ঠিকানা।
`route`	একটি নামযুক্ত রুট (যেমন "ইউএস ১০১")।
`intersection`	একটি প্রধান সংযোগস্থল, যা সাধারণত দুটি প্রধান সড়কের হয়ে থাকে।
`political`	একটি রাজনৈতিক সত্তা। সাধারণত, এই প্রকারটি কোনো বেসামরিক প্রশাসনের একটি সমষ্টিকে বোঝায়।
`country`	জাতীয় রাজনৈতিক সত্তা, এবং এটি সাধারণত জিওকোডার দ্বারা প্রত্যাবর্তিত সর্বোচ্চ ক্রমের প্রকার।
`administrative_area_level_1`	দেশ স্তরের নিচের একটি প্রথম-স্তরের বেসামরিক সত্তা। মার্কিন যুক্তরাষ্ট্রের মধ্যে, এই প্রশাসনিক স্তরগুলো হলো রাজ্য। সব দেশে এই প্রশাসনিক স্তরগুলো দেখা যায় না। বেশিরভাগ ক্ষেত্রে, `administrative_area_level_1` সংক্ষিপ্ত নামগুলো ISO 3166-2 উপবিভাগ এবং অন্যান্য বহুল প্রচলিত তালিকার সাথে ঘনিষ্ঠভাবে মিলে যাবে; তবে এটি নিশ্চিত নয়, কারণ আমাদের জিওকোডিং ফলাফল বিভিন্ন ধরনের সংকেত এবং অবস্থান তথ্যের উপর ভিত্তি করে তৈরি হয়।
`administrative_area_level_2`	দেশ পর্যায়ের নিচের একটি দ্বিতীয়-স্তরের বেসামরিক সত্তা। মার্কিন যুক্তরাষ্ট্রের মধ্যে, এই প্রশাসনিক স্তরগুলো হলো কাউন্টি। সব দেশে এই প্রশাসনিক স্তরগুলো দেখা যায় না।
`administrative_area_level_3`	দেশ পর্যায়ের নিম্নতর একটি তৃতীয়-স্তরের বেসামরিক সত্তা। এই প্রকারটি একটি ক্ষুদ্র বেসামরিক বিভাগকে নির্দেশ করে। সকল রাষ্ট্রে এই প্রশাসনিক স্তরগুলো দেখা যায় না।
`administrative_area_level_4`	দেশ পর্যায়ের নিচে চতুর্থ-স্তরের একটি বেসামরিক সত্তা। এই প্রকারটি একটি ক্ষুদ্র বেসামরিক বিভাগকে নির্দেশ করে। সব দেশে এই প্রশাসনিক স্তরগুলো দেখা যায় না।
`administrative_area_level_5`	দেশ পর্যায়ের নিচে পঞ্চম স্তরের একটি বেসামরিক সত্তা। এই প্রকারটি একটি ক্ষুদ্র বেসামরিক বিভাগকে নির্দেশ করে। সব দেশে এই প্রশাসনিক স্তরগুলো দেখা যায় না।
`administrative_area_level_6`	দেশ পর্যায়ের নিচে ষষ্ঠ-স্তরের একটি বেসামরিক সত্তা। এই প্রকারটি একটি ক্ষুদ্র বেসামরিক বিভাগকে নির্দেশ করে। সব দেশে এই প্রশাসনিক স্তরগুলো দেখা যায় না।
`administrative_area_level_7`	দেশ পর্যায়ের নিচে সপ্তম-স্তরের একটি বেসামরিক সত্তা। এই প্রকারটি একটি ক্ষুদ্র বেসামরিক বিভাগকে নির্দেশ করে। সব দেশে এই প্রশাসনিক স্তরগুলো দেখা যায় না।
`colloquial_area`	সত্তাটির একটি বহুল ব্যবহৃত বিকল্প নাম।
`locality`	একটি নিগমিত শহর বা নগর রাজনৈতিক সত্তা।
`sublocality`	এলাকার নিম্নস্তরের একটি প্রথম-স্তরের বেসামরিক সত্তা। কিছু অবস্থানের জন্য এটি অতিরিক্ত প্রকারগুলোর মধ্যে একটি পেতে পারে: `sublocality_level_1` থেকে `sublocality_level_5` । প্রতিটি উপ-এলাকা স্তর একটি বেসামরিক সত্তা। বৃহত্তর সংখ্যা একটি ছোট ভৌগোলিক এলাকা নির্দেশ করে।
`neighborhood`	একটি নামযুক্ত এলাকা।
`premise`	একটি নামযুক্ত স্থান, যা সাধারণত একটি সাধারণ নামে পরিচিত কোনো ভবন বা একাধিক ভবন নিয়ে গঠিত।
`subpremise`	প্রাঙ্গণ স্তরের নিচে অবস্থিত একটি ঠিকানাযোগ্য সত্তা, যেমন অ্যাপার্টমেন্ট, ইউনিট বা স্যুইট।
`plus_code`	অক্ষাংশ ও দ্রাঘিমাংশ থেকে প্রাপ্ত একটি এনকোডেড অবস্থান নির্দেশক। যেসব স্থানে রাস্তার ঠিকানা নেই (যেমন যেখানে ভবনগুলোর নম্বর দেওয়া নেই বা রাস্তাগুলোর নাম নেই), সেখানে রাস্তার ঠিকানার বিকল্প হিসেবে প্লাস কোড ব্যবহার করা যেতে পারে। বিস্তারিত জানতে https://plus.codes দেখুন।
`postal_code`	দেশের অভ্যন্তরে ডাকযোগে চিঠি পাঠানোর ঠিকানা হিসেবে পোস্টাল কোড ব্যবহার করা হয়।
`natural_feature`	একটি উল্লেখযোগ্য প্রাকৃতিক বৈশিষ্ট্য।
`airport`	একটি বিমানবন্দর।
`park`	একটি নামযুক্ত পার্ক।
`point_of_interest`	একটি নামযুক্ত দর্শনীয় স্থান। সাধারণত, এই "পিওআই" (POI) গুলো হলো স্থানীয় গুরুত্বপূর্ণ স্থান, যেগুলোকে সহজে অন্য কোনো শ্রেণিতে ফেলা যায় না, যেমন "এম্পায়ার স্টেট বিল্ডিং" বা "আইফেল টাওয়ার"।

প্রকারের একটি খালি তালিকা নির্দেশ করে যে নির্দিষ্ট ঠিকানা উপাদানটির (উদাহরণস্বরূপ, ফ্রান্সে Lieu-dit) জন্য কোনো পরিচিত প্রকার নেই।

উপরোক্ত বিষয়গুলো ছাড়াও, অ্যাড্রেস কম্পোনেন্টগুলোর মধ্যে নিচে তালিকাভুক্ত প্রকারগুলো অন্তর্ভুক্ত থাকতে পারে।

ঠিকানা উপাদানের ধরণ	বর্ণনা
`floor`	একটি ভবনের ঠিকানার তলা।
`establishment`	সাধারণত এমন একটি স্থান যাকে এখনও শ্রেণীবদ্ধ করা হয়নি।
`landmark`	নিকটবর্তী কোনো স্থান, যা দিক নির্ণয়ে সহায়তার জন্য নির্দেশক হিসেবে ব্যবহৃত হয়।
`point_of_interest`	একটি নামযুক্ত দর্শনীয় স্থান।
`parking`	পার্কিং লট বা পার্কিং কাঠামো।
`post_box`	একটি নির্দিষ্ট ডাকবাক্স।
`postal_town`	কিছু দেশে ডাক ঠিকানার জন্য ব্যবহৃত ভৌগোলিক এলাকার সমষ্টি, যেমন `locality` ও `sublocality` ।
`room`	ভবনের একটি কক্ষের ঠিকানা।
`street_number`	সঠিক রাস্তার নম্বর।
`bus_station` , `train_station` এবং `transit_station`	বাস, ট্রেন বা গণপরিবহন স্টপের অবস্থান।

দ্রষ্টব্য: জিওকোডিং এপিআই আমাদের ডেটা সেটের মধ্যে থাকা কোনো ঠিকানার জন্য কোনো নির্দিষ্ট উপাদান ফেরত দেবে, এমন কোনো নিশ্চয়তা নেই। ব্রুকলিনের মতো যেটিকে শহর বলে মনে করা হতে পারে, সেটি এলাকা হিসেবে না দেখিয়ে বরং অন্য কোনো উপাদান হিসেবে দেখানো হতে পারে – এক্ষেত্রে, সাবলোকালিটি_লেভেল_১। কোন নির্দিষ্ট উপাদানগুলো ফেরত দেওয়া হবে তা কোনো পূর্ব বিজ্ঞপ্তি ছাড়াই পরিবর্তিত হতে পারে। আপনি যদি রেসপন্স থেকে ঠিকানার উপাদানগুলো বের করার চেষ্টা করেন, তবে আপনার কোডটিকে নমনীয়ভাবে ডিজাইন করুন।

ভিউপোর্ট বায়াসিং

একটি জিওকোডিং অনুরোধে, আপনি জিওকোডিং পরিষেবাটিকে একটি নির্দিষ্ট ভিউপোর্টের (বাউন্ডিং বক্স হিসাবে প্রকাশিত) মধ্যে থাকা ফলাফলগুলিকে অগ্রাধিকার দিতে নির্দেশ দিতে পারেন। অনুরোধ URL-এর মধ্যে bounds প্যারামিটারটি সেট করার মাধ্যমে আপনি এটি করতে পারেন।

bounds প্যারামিটারটি এই বাউন্ডিং বক্সের দক্ষিণ-পশ্চিম এবং উত্তর-পূর্ব কোণার অক্ষাংশ/দ্রাঘিমাংশ স্থানাঙ্ক নির্ধারণ করে, যেখানে স্থানাঙ্ক দুটিকে একটি পাইপ ( | ) চিহ্ন দিয়ে আলাদা করা হয়।

দ্রষ্টব্য: এটি শুধুমাত্র ভিউপোর্টের মধ্যে থাকা ফলাফলগুলোর প্রতি একটি পক্ষপাতিত্ব তৈরি করে, এবং এটি কোনো নিশ্চয়তা দেয় না যে সমস্ত বা যেকোনো ফলাফল এর মধ্যে অন্তর্ভুক্ত থাকবে। প্লেসেস এপিআই (Places API)-এর অটোকমপ্লিট (Autocomplete) পদ্ধতিটি সাধারণত দ্ব্যর্থক কোয়েরিগুলোর জন্য বেশি উপযুক্ত, এবং এটি ফলাফলকে একটি নির্দিষ্ট এলাকায় সীমাবদ্ধ করতে পারে। জিওকোডিং সেরা অনুশীলন (Geocoding best practices) নিবন্ধটিতে কোন এপিআই পদ্ধতি কোন ব্যবহারের ক্ষেত্রে সবচেয়ে উপযুক্ত, সে সম্পর্কে কিছু নির্দেশনা দেওয়া আছে।

উদাহরণস্বরূপ, 'ওয়াশিংটন'-এর জন্য একটি জিওকোড সাধারণত মার্কিন যুক্তরাষ্ট্রের ওয়াশিংটন অঙ্গরাজ্যকে ফেরত দেয়:

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

তবে, মার্কিন যুক্তরাষ্ট্রের উত্তর-পূর্ব অংশের চারপাশে একটি বাউন্ডিং বক্স নির্ধারণ করে একটি bounds আর্গুমেন্ট যোগ করলে, এই জিওকোডটি ওয়াশিংটন, ডিসি শহরটিকে ফেরত দেয়:

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

অঞ্চল পক্ষপাত

একটি জিওকোডিং অনুরোধে, আপনি ' region প্যারামিটারটি ব্যবহার করে জিওকোডিং পরিষেবাটিকে একটি নির্দিষ্ট অঞ্চলের প্রতি পক্ষপাতদুষ্ট ফলাফল ফেরত দিতে নির্দেশ দিতে পারেন। এই প্যারামিটারটি একটি ccTLD (কান্ট্রি কোড টপ-লেভেল ডোমেইন) আর্গুমেন্ট গ্রহণ করে, যা অঞ্চলের পক্ষপাতিত্ব নির্দিষ্ট করে। কিছু উল্লেখযোগ্য ব্যতিক্রম ছাড়া, বেশিরভাগ ccTLD কোড ISO 3166-1 কোডের অনুরূপ। উদাহরণস্বরূপ, যুক্তরাজ্যের ccTLD হলো "uk" ( .co.uk ), যেখানে এর ISO 3166-1 কোড হলো "gb" (যা প্রযুক্তিগতভাবে "The United Kingdom of Great Britain and Northern Ireland" সত্তাটির জন্য ব্যবহৃত হয়)।

যেসব ডোমেইনে মূল গুগল ম্যাপস অ্যাপ্লিকেশনটি আনুষ্ঠানিকভাবে চালু করা হয়েছে, সেগুলোর প্রতিটির জন্য জিওকোডিং ফলাফল পক্ষপাতদুষ্ট হতে পারে। উল্লেখ্য যে, এই পক্ষপাত শুধুমাত্র একটি নির্দিষ্ট ডোমেইনের ফলাফলকেই প্রাধান্য দেয় ; যদি এই ডোমেইনের বাইরে আরও প্রাসঙ্গিক ফলাফল থাকে, তবে সেগুলোও অন্তর্ভুক্ত করা হতে পারে।

উদাহরণস্বরূপ, "টলেডো"-এর জন্য একটি জিওকোড এই ফলাফলটি ফেরত দেয়, কারণ জিওকোডিং এপিআই-এর ডিফল্ট ডোমেইন মার্কিন যুক্তরাষ্ট্রে সেট করা আছে। অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

region=es (স্পেন) সহ "Toledo"-এর জন্য একটি জিওকোডিং অনুরোধ স্প্যানিশ শহরটি ফেরত দেবে।

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

উপাদান ফিল্টারিং

একটি জিওকোডিং রেসপন্সে, জিওকোডিং এপিআই একটি নির্দিষ্ট এলাকার মধ্যে সীমাবদ্ধ ঠিকানার ফলাফল ফেরত দিতে পারে। আপনি components ফিল্টার ব্যবহার করে এই সীমাবদ্ধতা নির্দিষ্ট করতে পারেন। একটি ফিল্টার হলো component:value জোড়ের একটি তালিকা, যা একটি পাইপ ( | ) চিহ্ন দ্বারা পৃথক করা থাকে। ফিল্টার ভ্যালুগুলো অন্যান্য জিওকোডিং অনুরোধের মতোই বানান সংশোধন এবং আংশিক মিলের পদ্ধতি সমর্থন করে। যদি জিওকোডার কোনো কম্পোনেন্ট ফিল্টারের জন্য একটি আংশিক মিল খুঁজে পায়, তাহলে রেসপন্সে একটি partial_match ফিল্ড থাকবে।

যে components ফিল্টার করা যায় সেগুলো হলো:

postal_code postal_code এবং postal_code_prefix সাথে মেলে।
country একটি দেশের নাম অথবা দুই অক্ষরের ISO 3166-1 কান্ট্রি কোডের সাথে মেলে। এপিআইটি দেশ নির্ধারণের জন্য ISO স্ট্যান্ডার্ড অনুসরণ করে, এবং সংশ্লিষ্ট দেশের ISO কোড ব্যবহার করলে ফিল্টারিং সবচেয়ে ভালোভাবে কাজ করে।
দ্রষ্টব্য: যদি কোনো কান্ট্রি কোড দিয়ে অপ্রত্যাশিত ফলাফল পান, তবে যাচাই করে নিন যে আপনি এমন একটি কোড ব্যবহার করছেন যাতে আপনার কাঙ্ক্ষিত দেশ, অধীনস্থ অঞ্চল এবং ভৌগোলিকভাবে গুরুত্বপূর্ণ বিশেষ এলাকাগুলো অন্তর্ভুক্ত রয়েছে। আপনি উইকিপিডিয়ার 'List of ISO 3166 country codes' অথবা ISO অনলাইন ব্রাউজিং প্ল্যাটফর্মে কোড সম্পর্কিত তথ্য খুঁজে পেতে পারেন।

ফলাফলকে প্রভাবিত করার জন্য নিম্নলিখিত components ব্যবহার করা যেতে পারে, কিন্তু সেগুলি বলবৎ করা হবে না:

route একটি রুটের দীর্ঘ বা সংক্ষিপ্ত নামের সাথে মেলে।
locality locality এবং sublocality প্রকারভেদের সাথে মেলে।
administrative_area সকল administrative_area লেভেলের সাথে মেলে।

কম্পোনেন্ট ফিল্টারিং সম্পর্কে নোট:

অনুরোধে এই উপাদান ফিল্টারগুলির পুনরাবৃত্তি করবেন না, অন্যথায় API Invalid_request ফেরত দেবে: country , postal_code , route
অনুরোধে যদি পুনরাবৃত্ত উপাদান ফিল্টার থাকে, তাহলে API সেই ফিল্টারগুলিকে AND হিসেবে মূল্যায়ন করে, OR হিসেবে নয়।
ফলাফলগুলো গুগল ম্যাপসের সাথে সামঞ্জস্যপূর্ণ, যা মাঝে মাঝে অপ্রত্যাশিতভাবে শূন্য ফলাফল ZERO_RESULTS দেখায়। কিছু ক্ষেত্রে প্লেস অটোকমপ্লিট (Place Autocomplete) ব্যবহার করলে আরও ভালো ফলাফল পাওয়া যেতে পারে। এ বিষয়ে আরও জানতে, এই প্রায়শই জিজ্ঞাসিত প্রশ্নাবলী (FAQ) দেখুন।
প্রতিটি অ্যাড্রেস কম্পোনেন্টের জন্য, হয় address প্যারামিটারে অথবা components ফিল্টারে এটি উল্লেখ করুন, কিন্তু উভয় স্থানে নয়। উভয় স্থানে একই মান উল্লেখ করলে ফলাফল শূন্য ZERO_RESULTS হতে পারে।

` components=country:GB সহ `High St, Hastings`-এর জন্য একটি জিওকোড মার্কিন যুক্তরাষ্ট্রের হেস্টিংস-অন-হাডসনের পরিবর্তে ইংল্যান্ডের হেস্টিংস-এ একটি ফলাফল প্রদান করে।

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

components=country:ES সহ `Santa Cruz` এলাকার জন্য একটি জিওকোড অনুরোধ করলে `Santa Cruz de Tenerife in Canary Islands, Spain` ফলাফল হিসেবে পাওয়া যায়।

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

কম্পোনেন্ট ফিল্টারিং শুধুমাত্র তখনই ZERO_RESULTS প্রতিক্রিয়া প্রদান করে, যখন আপনি এমন ফিল্টার সরবরাহ করেন যা একে অপরকে বাদ দেয়।

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

আপনি components ফিল্টার ব্যবহার করে অ্যাড্রেস প্যারামিটার ছাড়াই বৈধ কোয়েরি করতে পারেন। (সম্পূর্ণ ঠিকানা জিওকোড করার সময়, অনুরোধটিতে ভবনের নাম ও নম্বর থাকলে address প্যারামিটারটি আবশ্যক।)

অনুরোধ:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

প্রতিক্রিয়া:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}