@arcgis/core/rest/places.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Find [places](https://developers.arcgis.com/documentation/mapping-apis-and-services/places/) within a search distance of a geographic point or within an extent,
 * or find more information about specific places.
 * Places, also known as points of interest (POIs), are businesses and geographic locations that one can discover around the world.
 * Places also contain attributes such as name, category, street address, contact information, and more.
 *
 * With the [places service](https://developers.arcgis.com/rest/places/) one can build powerful applications to help people discover, locate, and learn more about places
 * around them. The places service can search for businesses, points of interest (POI), and popular geographic features near a
 * location or within a bounding box. This service is currently only available if you have an
 * [ArcGIS Location Platform account](https://location.arcgis.com/).
 *
 * To start, one should identify one or more place categories
 * for the types of places of interest. Categories are used to help filter search results so only the places of interest
 * are returned. All categories have a name and a unique ID. To help find the appropriate category and ID, one can use the [places category finder](https://developers.arcgis.com/documentation/mapping-apis-and-services/places/places-category-finder/) tool.
 *
 * Once categories have been chosen, use the [queryPlacesNearPoint()](https://developers.arcgis.com/javascript/latest/references/core/rest/places/#queryPlacesNearPoint) or
 * [queryPlacesWithinExtent()](https://developers.arcgis.com/javascript/latest/references/core/rest/places/#queryPlacesWithinExtent) method. To filter and return the best results, provide a list of categories
 * and/or keywords when you search. When places are returned, they contain attributes such as name, placeId, location, and categories.
 *
 * @since 4.27
 * @see [Sample -  Find nearby places and details](https://developers.arcgis.com/javascript/latest/sample-code/places/)
 * @see [Introduction to places](https://developers.arcgis.com/documentation/mapping-apis-and-services/places/)
 * @see [Places category finder](https://developers.arcgis.com/documentation/mapping-apis-and-services/places/places-category-finder/)
 * @see [Places service](https://developers.arcgis.com/rest/places/)
 * @see [FetchPlaceParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FetchPlaceParameters/)
 * @see [PlacesParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesParameters/)
 * @see [PlacesQueryParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesQueryParameters/)
 * @see [PlaceResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlaceResult/)
 * @see [PlacesQueryResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesQueryResult/)
 */
import type FetchPlaceParameters from "./support/FetchPlaceParameters.js";
import type PlacesQueryParameters from "./support/PlacesQueryParameters.js";
import type PlacesQueryResult from "./support/PlacesQueryResult.js";
import type { RequestOptions } from "../request/types.js";

/**
 * Get place details, including name, address, description, and other attributes.
 *
 * @param params - Defines the parameters of the place details request.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns Returns a promise that resolves to an object with the results.
 * @see [FetchPlaceParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FetchPlaceParameters/)
 * @example
 * const [places, FetchPlaceParameters] = await $arcgis.import(
 *  "@arcgis/core/rest/places.js",
 *  "@arcgis/core/rest/support/FetchPlaceParameters.js"
 * ]);
 * const swedishFetchPlaceParameters = new FetchPlaceParameters({
 *   apiKey: "YOUR_API_KEY",
 *   placeId: "571624acd79b8a99897357a25b744a20",  // really good plumber
 *   requestedFields: ["address", "socialMedia"]
 * });
 *
 * function fetchPlaceDetails() {
 *   places.fetchPlace(swedishFetchPlaceParameters).then(showPlaceDetails);
 * }
 *
 * function showPlaceDetails(fetchResult) {
 *   console.log("Fetch place result: ", fetchResult);
 * }
 *
 * fetchPlaceDetails();
 */
export function fetchPlace(params: FetchPlaceParameters, requestOptions?: RequestOptions): Promise<object>;

/**
 * A nearby search that finds places within a given radius of a location.
 * The location typically represents a point on a map or the geolocation of a device.
 *
 * @param params - Defines the parameters of the query request.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns Resolves to an object containing the `PlacesQueryResult` as a promise.
 * @see [PlacesQueryParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesQueryParameters/)
 * @see [PlacesQueryResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesQueryResult/)
 * @example
 * const [places, PlacesQueryParameters] = await $arcgis.import(
 *   "@arcgis/core/rest/places.js",
 *   "@arcgis/core/rest/support/PlacesQueryParameters.js"
 * ]);
 * const point = {
 *   type: "point", // autocasts as new Point()
 *   longitude: 17.81840,
 *   latitude: 59.42145
 * };
 *
 * const swedishPlacesQueryParameters = new PlacesQueryParameters({
 *   apiKey: "YOUR_API_KEY",
 *   categoryIds: ["63be6904847c3692a84b9b4c"], // Bathroom Contractor
 *   radius: 10000,  // set radius to 10,000 meters
 *   point
 * });
 *
 * function findPlaces() {
 *   places.queryPlacesNearPoint(swedishPlacesQueryParameters).then(showPlaces);
 * }
 *
 * function showPlaces(placesSolveResult) {
 *   // results from the queryPlacesNearPoint() method
 *   console.log("PlacesQueryResult: ", placesSolveResult);
 *   // first PlaceResult object from PlacesQueryResult.results
 *   console.log("PlaceResult: ", placesSolveResult.results[0]);
 * }
 *
 * findPlaces();
 */
export function queryPlacesNearPoint(params: PlacesQueryParameters, requestOptions?: RequestOptions): Promise<PlacesQueryResult>;

/**
 * A search that finds places within a given extent.
 * An extent typically represents the visible area of a map.
 *
 * @param params - Defines the parameters of the query request.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns Resolves to an object containing the `PlacesQueryResult` as a promise.
 * @see [PlacesQueryParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesQueryParameters/)
 * @see [PlacesQueryResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PlacesQueryResult/)
 * @example
 * const [places, PlacesQueryParameters, Extent, SpatialReference] = await $arcgis.import(
 *   "@arcgis/core/rest/places.js",
 *   "@arcgis/core/rest/support/PlacesQueryParameters.js",
 *   "@arcgis/core/geometry/Extent.js",
 *   "@arcgis/core/geometry/SpatialReference.js"
 * ]);
 * const extent = new Extent({
 *   xmin: 17.75,
 *   ymin: 59.55,
 *   xmax: 18,
 *   ymax: 59.7,
 *   spatialReference: SpatialReference.WGS84
 * });
 *
 * const swedishPlacesQueryParameters = new PlacesQueryParameters({
 *   apiKey: "YOUR_API_KEY",
 *   categoryIds: ["4d4b7105d754a06377d81259"], // Landmarks and Outdoors
 *   extent
 * });
 *
 * function findPlaces() {
 *   places.queryPlacesWithinExtent(swedishPlacesQueryParameters).then(showPlaces);
 * }
 *
 * function showPlaces(placesSolveResult) {
 *   // results from the queryPlacesWithinExtent() method
 *   console.log("PlacesQueryResult: ", placesSolveResult);
 *   // first PlaceResult object from PlacesQueryResult.results
 *   console.log("PlaceResult: ", placesSolveResult.results[0]);
 * }
 *
 * findPlaces();
 */
export function queryPlacesWithinExtent(params: PlacesQueryParameters, requestOptions?: RequestOptions): Promise<PlacesQueryResult>;