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 using 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 the correct 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
Copy the API key access token to your clipboard when prompted.

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.

Expand
Use dark colors for code blocks
    /* Use for API key authentication */
    const accessToken = "YOUR_ACCESS_TOKEN"
Expand

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 MapLibre from CDN -->
    <script src=https://unpkg.com/maplibre-gl@5.4.0/dist/maplibre-gl.js></script>
    <link href=https://unpkg.com/maplibre-gl@5.4.0/dist/maplibre-gl.css rel="stylesheet" />

    <!-- 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 MapLibre from CDN -->
    <script src=https://unpkg.com/maplibre-gl@5.4.0/dist/maplibre-gl.js></script>
    <link href=https://unpkg.com/maplibre-gl@5.4.0/dist/maplibre-gl.css rel="stylesheet" />

    <!-- 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 [-122.32116, 47.62737] with a zoom of 13 to focus on Seattle, Washington.

Use dark colors for code blocks
        const basemapEnum = "arcgis/streets";
        const map = new maplibregl.Map({
            container: "map", // the id of the div element
            style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,

            zoom: 13, // starting zoom
            center: [-122.32116, 47.62737] // starting location [longitude, latitude]

        });

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

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>

Update styling to the map div element and body. Add styling for the new elements.

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;
        }

Create a set of dynamic buttons for place categories (e.g., Restaurants, Hotels, Museums) using calcite-button elements.

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 = document.createElement("calcite-button");
            categoryButton.setAttribute("class", "category-button");
            categoryButton.setAttribute("round", true);
            categoryButton.setAttribute("scale", "s");
            categoryButton.setAttribute("kind", "inverse")
            categoryButton.innerHTML = category;
            categoryButton.id = category;
            control.appendChild(categoryButton);

        })
        document.getElementById(placeKeywords[0]).dispatchEvent(new Event('click'));
Expand

Add event listeners

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 = document.createElement("calcite-button");
            categoryButton.setAttribute("class", "category-button");
            categoryButton.setAttribute("round", true);
            categoryButton.setAttribute("scale", "s");
            categoryButton.setAttribute("kind", "inverse")
            categoryButton.innerHTML = category;
            categoryButton.id = category;
            control.appendChild(categoryButton);

        })
        document.getElementById(placeKeywords[0]).dispatchEvent(new Event('click'));
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 = document.createElement("calcite-button");
            categoryButton.setAttribute("class", "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)
            })

        })
        document.getElementById(placeKeywords[0]).dispatchEvent(new Event('click'));
Expand

Find places in the map bounds

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

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

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

        };
Expand

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

Expand
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
            })

        };
Expand

Display results

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

Create a new list to store service results. When a new places request is made, clear the list.

Expand
Use dark colors for code blocks
        const currentPlaces = [];

        function showPlaces(text) {

            for (let place of currentPlaces) {
                place.remove();
            }

            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
            })

        };
Expand

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

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

            for (let place of currentPlaces) {
                place.remove();
            }

            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 = new maplibregl.Marker()
                            .setLngLat([result.location.x, result.location.y])
                            .addTo(map);
                        currentPlaces.push(marker);

                    });
                });

        };
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 setPopup to bind a popup to each result marker.

Expand
Use dark colors for code blocks
                .then((response) => {
                    response.results.forEach((result) => {
                        const marker = new maplibregl.Marker()
                            .setLngLat([result.location.x, result.location.y])
                            .addTo(map);
                        currentPlaces.push(marker);

                        const popup = new maplibregl.Popup();

                        marker.setPopup(popup)

                    });
                });

        };

        function getDetails(popup, id) {

        };
Expand

Add an event listener to each marker that calls a new function getDetails. Pass the current popup as well as the unique place ID from the service response.

Expand
Use dark colors for code blocks
                .then((response) => {
                    response.results.forEach((result) => {
                        const marker = new maplibregl.Marker()
                            .setLngLat([result.location.x, result.location.y])
                            .addTo(map);
                        currentPlaces.push(marker);

                        const popup = new maplibregl.Popup();

                        popup.on('open', e => {
                            getDetails(e.target, result.placeId)
                        });

                        marker.setPopup(popup)

                    });
                });

        };

        function getDetails(popup, id) {

        };
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(popup, id) {

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

        };
Expand

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

Expand
Use dark colors for code blocks
        function getDetails(popup, id) {

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

                .then((result) => {
                    console.log(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.setHTML(popupContents);
                });

        };
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.