# How to use SearchNearby Use SearchNearby This section contains a variety of how to guides and examples for how to use SearchNearby. **Topics** + [ # How to search nearby from a position ](how-to-search-nearby.md) + [ # How to search nearby places based on category ](how-to-search-nearby-category.md) + [ # How to search nearby places based on food type ](how-to-search-nearby-food.md) + [ # How to search nearby based on business chain ](how-to-search-nearby-business.md) + [ # How to search nearby within a country ](how-to-search-nearby-country.md) + [ # How to search nearby using geospatial context ](how-to-search-nearby-geospatial.md) # How to search nearby from a position Search nearby from a position The SearchNearby API enables querying for all nearby places and points of interest (POI) without entering any specific text. Users can explore neighborhoods, discover POIs, and more using this API. It requires a `QueryPosition`, which can represent a device's location, IP-based position, or the map viewport center. Alternatively, users can specify a city or place to bias results based on the geocoordinates of that location. ## Potential use cases + **Explore nearby POIs:** View all points of interest near the current position. + **Explore nearby places:** View all locations or places near a given position. ## Examples ### Search nearby from a position In this example, the search is conducted from a position in Dubai with latitude 25.26951 and longitude 55.30884. ------ #### [ Sample request ] ``` { "QueryPosition": [ 55.30884, 25.26951 ] } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "هما", "Address": { "Label": "هما, شارع مستشفى آل مكتوم, نايف دبي, الإمارات العربية المتحدة", "Country": { "Code2": "AE", "Code3": "ARE", "Name": "الإمارات العربية المتحدة" }, "SubRegion": { "Name": "دبي" }, "Locality": "دبي", "District": "نايف", "Street": "شارع مستشفى آل مكتوم", "StreetComponents": [ { "BaseName": "مستشفى آل مكتوم", "Type": "شارع", "TypePlacement": "BeforeBaseName", "TypeSeparator": " ", "Language": "ar" } ] }, "Position": [ 55.30884, 25.26951 ], "Distance": 0, "Categories": [ { "Id": "department_store", "Name": "Department Store", "LocalizedName": "مول تجاري", "Primary": true } ], "BusinessChains": [ { "Name": "HEMA", "Id": "HEMA" } ] }, { "PlaceId": "", "PlaceType": "Locality", "Title": "دبي, الإمارات العربية المتحدة", "Address": { "Label": "دبي, الإمارات العربية المتحدة", "Country": { "Code2": "AE", "Code3": "ARE", "Name": "الإمارات العربية المتحدة" }, "SubRegion": { "Name": "دبي" }, "Locality": "دبي" }, "Position": [ 55.30884, 25.26951 ], "Distance": 0, "MapView": [ 54.64906, 24.62308, 55.7371, 25.36995 ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [ 55.30884, 25.26951 ], "MaxResults": 2 }' ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position 55.30884 25.26951 \ --max-results 2 ``` ------ # How to search nearby places based on category Search nearby places based on category The SearchNearby API enables querying for points of interest (POI) with the inclusion or exclusion of specified categories. This can help users explore neighborhoods, discover local POIs, and more. The API requires a `QueryPosition`, which can be based on a device's location, IP position, or the center of the map viewport. Alternatively, users can specify a city or place, and the application will bias results based on that location’s coordinates. To learn more about supported categories, see [Categories filters](places-filtering.md#place-categories). ## Potential use cases + **Explore local facilities:** Find available facilities within a neighborhood. + **Discover tourist attractions:** Identify tourist spots within a city. + **Plan travel in a city:** Organize travel around different POIs within a chosen city. ## Examples ### Include category ------ #### [ Sample request ] ``` { "QueryPosition": [ 4.35609, 50.84439 ], "Filter": { "IncludeCategories": ["airport"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Brussels Airport", "Address": { "Label": "Brussels Airport, A201, 1930 Zaventem, België", "Country": { "Code2": "BE", "Code3": "BEL", "Name": "België" }, "Region": { "Code": "VLG", "Name": "Vlaanderen" }, "SubRegion": { "Name": "Vlaams Brabant" }, "Locality": "Zaventem", "PostalCode": "1930", "Street": "A201", "StreetComponents": [ { "BaseName": "A201", "Language": "nl" } ] }, "Position": [ 4.47767, 50.89452 ], "Distance": 10191, "Categories": [ { "Id": "airport", "Name": "Airport", "LocalizedName": "Luchthaven", "Primary": true } ] }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Internationale Luchthaven Antwerpen", "Address": { "Label": "Internationale Luchthaven Antwerpen, Luchthavenlei 1, 2100 Antwerpen, België", "Country": { "Code2": "BE", "Code3": "BEL", "Name": "België" }, "Region": { "Code": "VLG", "Name": "Vlaanderen" }, "SubRegion": { "Name": "Antwerpen" }, "Locality": "Antwerpen", "District": "Deurne", "PostalCode": "2100", "Street": "Luchthavenlei", "StreetComponents": [ { "BaseName": "Luchthaven", "Type": "lei", "TypePlacement": "AfterBaseName", "TypeSeparator": "", "Language": "nl" } ], "AddressNumber": "1" }, "Position": [ 4.45083, 51.18867 ], "Distance": 38852, "Categories": [ { "Id": "airport", "Name": "Airport", "LocalizedName": "Luchthaven", "Primary": true } ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [ 4.35609, 50.84439 ], "Filter": { "IncludeCategories": ["airport"] }, "MaxResults": 2 } ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position 4.35609 50.84439 \ --filter '{"IncludeCategories": ["airport"]}' \ --max-results 2 ``` ------ ### Exclude category ------ #### [ Sample request ] ``` { "QueryPosition": [ 4.35609, 50.84439 ], "Filter": { "ExcludeCategories": ["airport"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Socialbrands Module 2", "Address": { "Label": "Socialbrands Module 2, Albertinaplein, 1000 Brussel, België", "Country": { "Code2": "BE", "Code3": "BEL", "Name": "België" }, "Region": { "Code": "BRU", "Name": "Brussel" }, "SubRegion": { "Name": "Brussel" }, "Locality": "Brussel", "District": "Koningswijk", "PostalCode": "1000", "Street": "Albertinaplein", "StreetComponents": [ { "BaseName": "Albertina", "Type": "plein", "TypePlacement": "AfterBaseName", "TypeSeparator": "", "Language": "nl" } ] }, "Position": [ 4.35609, 50.84439 ], "Distance": 0, "Categories": [ { "Id": "commercial_services", "Name": "Commercial Services", "LocalizedName": "Commerciële diensten", "Primary": true } ], "Contacts": { "Websites": [ { "Value": "https://oneread.net" } ] }, "AccessPoints": [ { "Position": [ 4.35609, 50.84439 ] } ] }, { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Barman Privé", "Address": { "Label": "Barman Privé, Albertinaplein, 1000 Brussel, België", "Country": { "Code2": "BE", "Code3": "BEL", "Name": "België" }, "Region": { "Code": "BRU", "Name": "Brussel" }, "SubRegion": { "Name": "Brussel" }, "Locality": "Brussel", "District": "Koningswijk", "PostalCode": "1000", "Street": "Albertinaplein", "StreetComponents": [ { "BaseName": "Albertina", "Type": "plein", "TypePlacement": "AfterBaseName", "TypeSeparator": "", "Language": "nl" } ] }, "Position": [ 4.35609, 50.84439 ], "Distance": 0, "Categories": [ { "Id": "catering_and_other_food_services", "Name": "Catering and Other Food Services", "LocalizedName": "Catering- en horecadiensten", "Primary": true } ], "Contacts": { "Phones": [ { "Value": "+32476891634" } ] }, "OpeningHours": [ { "Display": [ "ma-zo: 00:00 - 24:00" ], "OpenNow": true, "Components": [ { "OpenTime": "T000000", "OpenDuration": "PT24H00M", "Recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA,SU" } ] } ], "AccessPoints": [ { "Position": [ 4.35609, 50.84439 ] } ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [ 4.35609, 50.84439 ], "Filter": { "ExcludeCategories": ["airport"] } } ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position 4.35609 50.84439 \ --filter '{"ExcludeCategories": ["airport"]}' \ --max-results 2 ``` ------ # How to search nearby places based on food type Search nearby places based on food type The `SearchNearby` API enables you query nearby restaurants that serve a specific type of food. You can also exclude food types from your results. You can use the SearchNearby API to let end users explore neighborhoods and discover places of interest. The API requires QueryPosition, which can be a device position, IP position, or a map‘s view port center. Another way is to let end users provide the city name or place name and the application can bias results based on the geo-coordinates. For more information on food types, see [Food Type filters](places-filtering.md#food-type). ## Potential use cases + Explore types of food available in the vicinity. + Exclude restaurant options that serve food types to which you're allergic. ## Example ### Search nearby places by food type The following example demonstrates how to search for nearby places based on food type. ------ #### [ Sample request ] This request searches for restaurants that serve Chinese food near the specified coordinates. ``` { "QueryPosition": [ 12.49563, 41.90325 ], "Filter": { "IncludeFoodTypes": ["chinese"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Bufala e Pachino", "Address": { "Label": "Bufala e Pachino, Via Firenze, 53, 00184 Roma RM, Italia", "Country": { "Code2": "IT", "Code3": "ITA", "Name": "Italia" } }, "Position": [ 12.49409, 41.90237 ], "Distance": 161, "Categories": [ { "Id": "restaurant", "Name": "Restaurant", "LocalizedName": "Ristorante", "Primary": true } ], "FoodTypes": [ { "LocalizedName": "Pizza", "Id": "pizza", "Primary": true }, { "LocalizedName": "Cinese", "Id": "chinese", "Primary": false } ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [12.49563, 41.90325], "Filter": { "IncludeFoodTypes": ["chinese"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position 12.49563 41.90325 \ --filter '{"IncludeFoodTypes": ["chinese"]}' ``` ------ ### Developer Tips + You can use `ExludeFoodTypes` to exclude certain business chains from your results. + You can exclude or include multiple food types. # How to search nearby based on business chain Search nearby places based on business chain The SearchNearby API enables you to query nearby business chains. You can include or exclude specific business chains in your search. This feature allows end users to explore neighborhoods, discover points of interest, and more. To use the SearchNearby API, you need to provide a QueryPosition, which can be: + A device position + An IP-based position + A map's viewport center Alternatively, users can provide a city name or place, and the application can bias results based on the geo-coordinates of that location. For more information about supported business chains, see [Business Chains filter](places-filtering.md#business-chains). ## Potential use cases + Explore businesses in the vicinity + Expand your business by finding nearby B2B customers ## Examples ### Search nearby places by business chain The following example demonstrates how to search for nearby Starbucks locations. ------ #### [ Sample request ] This request searches for Starbucks locations near the specified coordinates. ``` { "QueryPosition": [ 12.49563, 41.90325 ], "Filter" : { "IncludeBusinessChains": ["Starbucks"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Starbucks", "Address": { "Label": "Starbucks, Via Giovanni Giolitti, 2, 00185 Roma RM, Italia", "Country": { "Code2": "IT", "Code3": "ITA", "Name": "Italia" }, "Region": { "Name": "Lazio" }, "SubRegion": { "Code": "RM", "Name": "Roma" }, "Locality": "Roma", "District": "Esquilino", "PostalCode": "00185", "Street": "Via Giovanni Giolitti", "StreetComponents": [ { "BaseName": "Giovanni Giolitti", "Type": "Via", "TypePlacement": "BeforeBaseName", "TypeSeparator": " ", "Language": "it" } ], "AddressNumber": "2" }, "Position": [ 12.50102, 41.90093 ], "Distance": 515, "Categories": [ { "Id": "coffee_shop", "Name": "Coffee Shop", "LocalizedName": "Bar", "Primary": true } ], "BusinessChains": [ { "Name": "Starbucks", "Id": "Starbucks" } ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [ 12.49563, 41.90325 ], "Filter" : { "IncludeBusinessChains": ["Starbucks"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position 12.49563 41.90325 \ --filter '{"IncludeBusinessChains": ["Starbucks"]}' ``` ------ ## Developer Tips + You can use `ExcludeBusinessChains` to exclude certain business chains from your results. + You can exclude or include multiple business chains. # How to search nearby within a country Search nearby places within a country The SearchNearby API enables you to search for nearby places within a specific country. To use the API, you need to provide a QueryPosition, which can be: + A device position + An IP-based position + A map's viewport center Alternatively, users can provide a city name or place, and the application can bias results based on the geocoordinates of that location. ## Potential use cases + Explore businesses within a country + Find nearby B2B customers within a country + Explore tourist places within a country ## Examples ### Search for golf courses in Canada The following example demonstrates how to search for golf courses within Canada near specified coordinates. ------ #### [ Sample request ] This request searches for golf courses in Canada near the specified location. ``` { "QueryPosition": [ -122.741803, 49.002478 ], "Filter" : { "IncludeCategories": ["golf_course"], "IncludeCountries": ["CAN"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Peace Portal Golf Course", "Address": { "Label": "Peace Portal Golf Course, 16900 * Ave, Surrey, BC V*Z *P*, Canada", "Country": { "Code2": "CA", "Code3": "CAN", "Name": "Canada" }, "Region": { "Code": "BC", "Name": "British Columbia" }, "SubRegion": { "Name": "Metro Vancouver" }, "Locality": "Surrey", "District": "South Surrey", "PostalCode": "V*Z *P*", "Street": "* Ave", "StreetComponents": [ { "BaseName": "4", "Type": "Ave", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "16900" }, "Position": [ -122.75086, 49.00921 ], "Distance": 998, "Categories": [ { "Id": "golf_course", "Name": "Golf Course", "LocalizedName": "Golf Course", "Primary": true } ], "Contacts": { "Phones": [ { "Value": "+16045384818" } ], "Websites": [ { "Value": "http://www.peaceportalgolf.com" } ] }, "AccessPoints": [ { "Position": [ -122.75087, 49.00935 ] } ] } ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [ -122.741803, 49.002478 ], "Filter" : { "IncludeCategories": ["golf_course"], "IncludeCountries": ["CAN"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position -122.741803 49.002478 \ --filter '{"IncludeCategories": ["golf_course"], "IncludeCountries": ["CAN"]}' ``` ------ # How to search nearby using geospatial context Search nearby with geospatial context The SearchNearby API enables you to explore nearby, while restricting results within geospatial context (such as a circle or bounding box). The SearchNearby API lets you filter results using geospatial contexts such as circles and bounding boxes. By defining these geographic boundaries, you can limit search results to specific areas. ## Potential use cases + Limit search results to a specific geographic area + Search within custom-defined boundaries + Focus results on targeted neighborhoods or districts ## Examples ### Search using query radius The following example demonstrates how to search for schools within a 1000-meter radius of the specified coordinates. ------ #### [ Sample request ] This request searches for schools within a 1000-meter (1-kilometer) radius. ``` { "QueryPosition": [ -122.741803, 49.002478 ], "QueryRadius":1000, "Filter" : { "IncludeCategories": ["school"] } } ``` ------ #### [ Sample response ] ``` { "ResultItems": [ { "PlaceId": "", "PlaceType": "PointOfInterest", "Title": "Grace Lutheran Church", "Address": { "Label": "Grace Lutheran Church, 702 G St, Blaine, WA 98230-5125, United States", "Country": { "Code2": "US", "Code3": "USA", "Name": "United States" }, "Region": { "Code": "WA", "Name": "Washington" }, "SubRegion": { "Name": "Whatcom" }, "Locality": "Blaine", "PostalCode": "98230-5125", "Street": "G St", "StreetComponents": [ { "BaseName": "G", "Type": "St", "TypePlacement": "AfterBaseName", "TypeSeparator": " ", "Language": "en" } ], "AddressNumber": "702" }, "Position": [ -122.74157, 48.99533 ], "Distance": 795, "Categories": [ { "Id": "church", "Name": "Church", "LocalizedName": "Church", "Primary": true }, { "Id": "kindergarten_and_childcare", "Name": "Kindergarten and Childcare", "LocalizedName": "Kindergarten & Childcare", "Primary": false }, { "Id": "school", "Name": "School", "LocalizedName": "School", "Primary": false } ] } ... ] } ``` ------ #### [ cURL ] ``` curl --request POST \ --url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \ --header 'Content-Type: application/json' \ --data '{ "QueryPosition": [ -122.741803, 49.002478 ], "QueryRadius": 1000, "Filter": { "IncludeCategories": ["school"] } }' ``` ------ #### [ AWS CLI ] ``` aws geo-places search-nearby --key ${YourKey} \ --query-position -122.741803 49.002478 \ --query-radius 1000 \ --filter '{"IncludeCategories": ["school"]}' ``` ------ ## Developer Tips + Alternatively, you can use a bounding box filter.