Find places in a bounding box

Learn how to perform a text-based search to find places within a bounding box.

Find places in a bounding box API key authentication

A bounding box search finds places within an extent using the places service. An extent typically represents the visible area of a map. To perform a bounding box search, you use the places package from ArcGIS REST JS. With the results of the search, you can make another request to the service and return place attributes such as street address and telephone number.

In this tutorial, you use ArcGIS REST JS to perform a bounding box search based on the visible extent on the map and return details about each place. You also use Calcite components to create a basic search interface.

Prerequisites

An ArcGIS Location Platform account.

Steps

Get the starter app

Select a type of authentication below and follow the steps to create a new application.

You can choose one of the following to create a new CodePen:

Option 1: Complete the Display a map tutorial; or,
Option 2: Start from the Display a map tutorial .

Set up authentication

Create developer credentials in your portal for the type of authentication you selected.

Create a new API key credential with privileges to access the resources used in this tutorial.

Go to the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
  - Location services > Basemaps
  - Location services > Places
When prompted, copy and paste the API key to a safe location. It will be used in the next step.

Set developer credentials

Use the API key or OAuth developer credentials so your application can access location services.

Update the accessToken variable to use your API key.

Use dark colors for code blocks
  <script>

    /* Use for API key authentication */
    const accessToken = "YOUR_ACCESS_TOKEN";

    const map = L.map("map", {
      minZoom: 2
    })

    map.setView([34.02, -118.805], 13);

    const basemapEnum = "arcgis/streets";

    L.esri.Vector.vectorBasemapLayer(basemapEnum, {
      token: accessToken
    }).addTo(map);

  </script>

In both the index.html and callback.html files, replace YOUR_CLIENT_ID and YOUR_REDIRECT_URL with the client ID and redirect URL of your OAuth credentials.

index.html
Use dark colors for code blocks
    /* Use for user authentication */
    const clientId = "YOUR_CLIENT_ID"; // Your client ID from OAuth credentials
    const redirectUri = "YOUR_REDIRECT_URI"; // The redirect URL registered in your OAuth credentials
    const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
      clientId,
      redirectUri,
      portal: "https://www.arcgis.com/sharing/rest" // Your portal URL
    })

    const accessToken = session.token;

callback.html
Use dark colors for code blocks
    arcgisRest.ArcGISIdentityManager.completeOAuth2({
      clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
      redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
      portal: "https://www.arcgis.com/sharing/rest" // Your portal URL
    })

Run the app and ensure you can sign in successfully.

If you are unable to sign in, make sure you have the correct redirect URL and port. This URL varies based on your application and typically takes the format of https://<server>[:port]/callback.html or http://my-arcgis-app:/auth. For example, if you are running an application on http://127.0.0.1:5500/, set http://127.0.0.1:5500/callback.html as your redirect URL in the index.html and callback.html file and your developer credential. They all have to match!

Add script references

Reference the ArcGIS REST JS request and places packages to perform a bounding box search operation. You also reference the Calcite library to create the user interface.

Reference the routing and request packages from ArcGIS REST JS.

Use dark colors for code blocks
    <!-- Load Leaflet from CDN -->
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" crossorigin="" />
    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js" crossorigin=""></script>
    <!-- Load Esri Leaflet from CDN -->
    <script src="https://unpkg.com/esri-leaflet@3.0.16/dist/esri-leaflet.js"></script>
    <script src="https://unpkg.com/esri-leaflet-vector@4.2.8/dist/esri-leaflet-vector.js"></script>

    <!-- ArcGIS REST JS: request and places -->
    <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-places@1/dist/bundled/places.umd.js"></script>

Reference the Calcite Design System library.

Use dark colors for code blocks
    <!-- Load Leaflet from CDN -->
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" crossorigin="" />
    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js" crossorigin=""></script>
    <!-- Load Esri Leaflet from CDN -->
    <script src="https://unpkg.com/esri-leaflet@3.0.16/dist/esri-leaflet.js"></script>
    <script src="https://unpkg.com/esri-leaflet-vector@4.2.8/dist/esri-leaflet-vector.js"></script>

    <!-- Calcite components -->
    <script type="module" src="https://js.arcgis.com/calcite-components/2.12.1/calcite.esm.js"></script>
    <link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/2.12.1/calcite.css" />

    <!-- ArcGIS REST JS: request and places -->
    <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-places@1/dist/bundled/places.umd.js"></script>

Create a REST JS ApiKeyManager using your access token.

Expand
Use dark colors for code blocks
    const authentication = arcgisRest.ApiKeyManager.fromKey(accessToken);
Expand

Update interface

Change the map's viewpoint to [47.62737, -122.32116] with a zoom of 14 to focus on Seattle, Washington.

Use dark colors for code blocks
    const map = L.map("map", {
        minZoom: 13

    }).setView([47.62737, -122.32116], 14); //Latitude, longitude

Inside <body>, copy and paste the following HTML to create a basic search interface.

Expand
Use dark colors for code blocks
    <div id="place-control">
        <div class="search">
            <calcite-input type="text" id="search-input" placeholder="Type in a place name or category">
                <calcite-button kind="inverse" icon-start="search" id="search-button" type="submit" slot="action"></calcite-button>
            </calcite-input>
        </div>
    </div>

    <div id="map"></div>
Expand

Add styling for the new elements and add a z-index of 1 to the map <div> element.

Expand
Use dark colors for code blocks
        body {
            margin: 0;
            padding: 0;
        }
        #map {
            position: absolute;
            top: 0;
            bottom: 0;
            right: 0;
            left: 0;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;

            z-index:1;
        }
        #place-control {
            position:absolute;
            top:15px;
            left:15px;
            display:flex;
            flex-direction: row;
            z-index: 2;
        }
        .search {
            margin-right:15px;
        }
        #search-input {
            width:270px;
        }
        .category-button {
            margin:auto 5px;

        }
Expand

Create a set of dynamic buttons for place categories (e.g., Restaurants, Hotels, Museums) using calcite-button elements. Then, adjust the map's zoom control position to bottom right.

Expand
Use dark colors for code blocks
    const control = document.getElementById("place-control");
    const input = document.getElementById("search-input")

    const placeKeywords = ["Restaurants", "Hotels", "Museums", "ATMs", "Breweries"];

    placeKeywords.forEach(category => {
        const categoryButton = L.DomUtil.create("calcite-button","category-button");
        categoryButton.setAttribute("round",true);
        categoryButton.setAttribute("scale","s");
        categoryButton.setAttribute("kind","inverse")
        categoryButton.innerHTML = category;
        categoryButton.id = category;
        control.appendChild(categoryButton);

    })
    map.zoomControl.setPosition("bottomright");
Expand

Add event listeners

The provided for this tutorial includes a basic user interface with a text input and category buttons. Add event listeners to this interface to make requests to the places service on when they are clicked.

Create a showPlaces function to make requests to the places service.

Expand
Use dark colors for code blocks
    function showPlaces(text) {

    };
Expand

Add an event listener to the search button that calls showPlaces on click.

Expand
Use dark colors for code blocks
    const control = document.getElementById("place-control");
    const input = document.getElementById("search-input")

    const placeKeywords = ["Restaurants", "Hotels", "Museums", "ATMs", "Breweries"];

    document.getElementById("search-button").addEventListener("click", e => {
        showPlaces(input.value)
    })

    placeKeywords.forEach(category => {
        const categoryButton = L.DomUtil.create("calcite-button","category-button");
        categoryButton.setAttribute("round",true);
        categoryButton.setAttribute("scale","s");
        categoryButton.setAttribute("kind","inverse")
        categoryButton.innerHTML = category;
        categoryButton.id = category;
        control.appendChild(categoryButton);

    })
    map.zoomControl.setPosition("bottomright");
Expand

Add an event listener to each category button that calls showPlaces on click.

Expand
Use dark colors for code blocks
    placeKeywords.forEach(category => {
        const categoryButton = L.DomUtil.create("calcite-button","category-button");
        categoryButton.setAttribute("round",true);
        categoryButton.setAttribute("scale","s");
        categoryButton.setAttribute("kind","inverse")
        categoryButton.innerHTML = category;
        categoryButton.id = category;
        control.appendChild(categoryButton);

        categoryButton.addEventListener("click", e => {
            input.value = category;
            showPlaces(category)
        })

    })
    map.zoomControl.setPosition("bottomright");
Expand

Find places in the map bounds

Calculate the current visible extent of the Leaflet map with map.getBounds(). Access the top right and bottom left corners.

Use dark colors for code blocks
    function showPlaces(text) {

        const bounds = map.getBounds()
        const topRight = bounds.getNorthEast();
        const bottomLeft = bounds.getSouthWest();

    };

Use the ArcGIS REST JS findPlacesWithinExtent operation to make a request to the places service. Set the searchText parameter to the input text and pass the current map bounding box to the xmin,xmax,ymin, and ymax parameters.

Use dark colors for code blocks
    function showPlaces(text) {

        const bounds = map.getBounds()
        const topRight = bounds.getNorthEast();
        const bottomLeft = bounds.getSouthWest();

        arcgisRest.findPlacesWithinExtent({
            xmin: bottomLeft.lng,
            ymin: bottomLeft.lat,
            xmax: topRight.lng,
            ymax: topRight.lat,
            searchText: text,
            authentication
        })

    };

Display results

The response from the places service will contain a list of place results. Each result will include the x/y coordinates, name, category, and unique ID associated with a place.

Add a new LayerGroup to your map to display service results. When a new places request is made, clear the LayerGroup.

Expand
Use dark colors for code blocks
    const layerGroup = L.layerGroup().addTo(map);

    function showPlaces(text) {

        layerGroup.clearLayers();
Expand

Access the service results. For each result, add a Leaflet Marker to your map.

Expand
Use dark colors for code blocks
    function showPlaces(text) {

        layerGroup.clearLayers();

        const bounds = map.getBounds()
        const topRight = bounds.getNorthEast();
        const bottomLeft = bounds.getSouthWest();

        arcgisRest.findPlacesWithinExtent({
            xmin: bottomLeft.lng,
            ymin: bottomLeft.lat,
            xmax: topRight.lng,
            ymax: topRight.lat,
            searchText: text,
            authentication
        })

        .then((response)=>{
            response.results.forEach((result)=>{
                const marker = L.marker([result.location.y, result.location.x])
                .addTo(layerGroup);

            });
        });

    };
Expand

Run the app. When you click a category button or search for a phrase, the map should display a set of points representing place results.

To view more information about each place result, bind a popup to each marker that displays more information about the place.

Use bindPopup to bind a popup to each result marker. Create the popup contents dynamically using a new function. The current Leaflet marker is automatically passed as the first function parameter.

Expand
Use dark colors for code blocks
        .then((response)=>{
            response.results.forEach((result)=>{
                const marker = L.marker([result.location.y, result.location.x])
                .addTo(layerGroup);

                marker.bindPopup(getDetails, {
                    minWidth:200
                });

            });
        });

    };

    function getDetails(place){

        const popup = document.createElement('div');

        return popup
    };
Expand

Set the id of each marker to the unique placeId associated with the POI.

Expand
Use dark colors for code blocks
        .then((response)=>{
            response.results.forEach((result)=>{
                const marker = L.marker([result.location.y, result.location.x])
                .addTo(layerGroup);

                marker.id = result.placeId;

                marker.bindPopup(getDetails, {
                    minWidth:200
                });

            });
        });
Expand

Get place address and phone number

You can access more information about a place using the unique placeId associated with it. Perform a subsequent request to the places service to get the street address and phone number of a clicked POI.

Use the ArcGIS REST JS getPlaceDetails function to get detailed information about a specific place. Pass the placeId associated with the current marker, and set the requestedFields parameter to return the streetAddress and telephone properties.

Expand
Use dark colors for code blocks
    function getDetails(place){

        const popup = document.createElement('div');

        arcgisRest.getPlaceDetails(({
            placeId: place.id,
            authentication,
            requestedFields: ["name","address:streetAddress", "contactInfo:telephone"]
        }))

        return popup
    };
Expand

Access the service response. Display the results in your popup if they are available.

Expand
Use dark colors for code blocks
    function getDetails(place){

        const popup = document.createElement('div');

        arcgisRest.getPlaceDetails(({
            placeId: place.id,
            authentication,
            requestedFields: ["name","address:streetAddress", "contactInfo:telephone"]
        }))

        .then((result)=>{

            let popupContents = `<b>${result.placeDetails.name}</b><br>`;
            if (result.placeDetails.address.streetAddress) popupContents += `${result.placeDetails.address.streetAddress}<br>`;
            if (result.placeDetails.contactInfo.telephone) popupContents += `${result.placeDetails.contactInfo.telephone}`;

            popup.innerHTML = popupContents;
        });

        return popup
    };
Expand

Run the app

Run the app.

The app should display a map with a search control. Upon clicking a button or entering a phrase, place results should appear on the map. Clicking a result will submit another service request to get the place address and phone number.

What's next?

Learn how to use additional ArcGIS location services in these tutorials:

Find nearby places and details

Find points of interest near a location and get detailed information about them

Find place addresses

Search for coffee shops, gas stations, restaurants and other nearby places with the Geocoding service.

Find a route and directions

Find a route and directions with the route service.