openapi: 3.0.3 info: title: ArcGIS places service description: | # ArcGIS places service The places service can search for businesses, points of interest (POI), and popular geographic features near a location or within a bounding box. You can use the service to: * Find and display places on a map. * Search for places by text and/or categories such as restaurants, gas stations, or schools. * Find places near a location and display information such as place name, description, address and contact information. * Find places within a bounding box (extent). * Search for over 1,000 categories using the API or the [category browser](https://developers.arcgis.com/documentation/mapping-apis-and-services/places/places-category-finder/). **Additional documentation**: To access the service with different client APIs, go to [Places](https://developers.arcgis.com/documentation/mapping-apis-and-services/places/) in the _Mapping APIs and location services_ guide. To access the service, you must use an ArcGIS Location Platform account to create a token that includes the `premium:user:places` privilege. ## Supported Operations ### /categories The `places/categories` endpoint returns the full list of categories supported by the service. There are over 1000 categories organized into a hierarchy. For example, a place that is in the category of "French Restaurant", can also be found through the parent category "Restaurant", which is also included in "Dining and Drinking". If you want to view a specific subset of categories, you can supply a filter parameter to return a reduced list of categories which match your filter. ### /categories/{categoryId} The `/categories/{categoryId}` endpoint looks up details of a specific category using its ID and returns all the categories to which it belongs and the parent category ID. ### places/near-point The `places/near-point` endpoint returns places that are within a search distance of a geographic point. You can also supply additional search criteria, including: - Search text, such as the place name, or partial name. - The categories of places (for example, coffee shops or museums). ### places/within-extent The `places/within-extent` endpoint returns candidate places that are within an extent (or bounding box). You can also supply additional search criteria, including: - Search text, such as the place name, or partial name. - The categories of places (for example, coffee shops or museums). ### places/{placeId} The `places/{placeId}` endpoint returns detailed information about a given place, including: - Contact information. - Address. ## Workflows ### Local search In a local search application, follow these steps: 1. Make a `places/categories` request to get information about all available categories. 2. Let users select the categories they want. You will need the category Ids when searching for places. For example, if the target category is "Bicycle Store", the category Id is `4bf58dd8d48988d115951735`. Note that if you already know the category Id you are interested in, you can skip steps 1 and 2. 3. Pass the user's search location and a search distance, along with optional search criteria such as category, to `places/near-point` endpoint. 4. Present the user with the filtered places and let them choose those they want to see in more detail. You will need the `placeId` to fetch additional details. 5. Pass the `placeId` to `places/{placeId}` endpoint to get details for a specific place. ## Units - Geographic coordinates are in WGS84 decimal degrees, x is a longitude and y is a latitude. - Distances are in meters. version: 1.3.0 termsOfService: https://developers.arcgis.com/documentation/mapping-and-location-services/terms-of-use/ servers: - url: https://places-api.arcgis.com/arcgis/rest/services/places-service/{basePath} description: Production service endpoint. variables: basePath: description: Version 1 of the places service. default: v1 tags: - name: categories description: Operations to find information about categories or types of places. - name: places description: Operations to find information about places, or points of interest (POIs). security: - ArcGISTokenParameter: [] - ArcGISAuthorizationHeader: [] - ArcGISXEsriAuthorizationHeader: [] paths: /categories: get: tags: - categories operationId: categoriesGet x-arcgis-frontmatter: keywords: - place - poi - category - categories - search - filter summary: Return the name and category ID of all categories, or categories which satisfy a filter. description: | A category describes a type of place, such as "movie theater" or "zoo". The places service has over 1,000 categories (or types) of place. The categories fall into ten general groups: Arts and Entertainment, Business and Professional Services, Community and Government, Dining and Drinking, Events, Health and Medicine, Landmarks and Outdoors, Retail, Sports and Recreation, and Travel and Transportation. The categories are organized into a hierarchical system where a general category contains many more detailed variations on the parent category. For example: "Travel and Transportation" (Level 1), "Transport Hub" (Level 2), "Airport" (Level 3) and "Airport Terminal" (Level 4). The hierarchy has up to 5 levels of categories. The table below shows the top-level of categories, along with a selection of level two categories. The `/categories` endpoint fetches the latest set of place categories. The request returns all categories including their label and `categoryId`. You should use this endpoint to fetch the latest set of categories when your app starts up. Each category contains an unique ID that you can use to perform a `near-point` or `within-extent` search. You can also reduce the list to a subset of categories using the `filter` parameter. For example, searching for "coffee" would return categories including: - "Coffee Shop" - "Coffee Roaster" - "Turkish Coffeehouse" |Category Label | Category ID | Level 2| |--- | --- | ---| |Arts and Entertainment | 4d4b7104d754a06370d81259 | Amusement Park, Art Gallery, Casino, Exhibit, Movie Theater, Museum, Stadium, Water Park, Zoo, ...| |Business and Professional Services | 4d4b7105d754a06375d81259 | Construction, Convention Center, Food and Beverage Service, Health and Beauty Service, Industrial Estate, Office, ...| |Community and Government | 63be6904847c3692a84b9b9a | Education, Organization, Government Building, Community Center, Library, Utility Company, ...| |Dining and Drinking | 63be6904847c3692a84b9bb5 | Bakery, Bar, Cafe, Coffee, and Tea House, Restaurant, ...| |Event | 4d4b7105d754a06373d81259 | Conference, Convention, Entertainment Event, Marketplace, ...| |Health and Medicine | 63be6904847c3692a84b9bb9 | Dentist, Emergency Service, Hospital, Medical Center, Optometrist, Physician, Veterinarian, ...| |Landmarks and Outdoors | 4d4b7105d754a06377d81259 | Beach, Structure, Campground, Harbor or Marina, Historic and Protected Site, Monument, Nature Preserve, Park, ...| |Retail | 4d4b7105d754a06378d81259 | Arts and Crafts Store, Bookstore, Convenience Store, Department Store, ...| |Sports and Recreation | 4f4528bc4b90abdf24c9de85 | Athletic Field, Baseball, Basketball, Football, Golf, Gym and Studio, ...| |Travel and Transportation | 4d4b7105d754a06379d81259 | Bike Rental, Cruise, Electric Vehicle Charging Station, Fuel Station, Lodging, Transport Hub, ...| **Note**: Category details are subject to change as new types of places are introduced. **Note**: Query parameters are case-sensitive. Categories use Foursquare's Open Source Places system: Copyright 2024 Foursquare Labs, Inc. All rights reserved. Licensed under the Apache License. Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [the Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0). Unless required by applicable law or agreed in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License." parameters: - $ref: '#/components/parameters/CategoriesFilterParam' - $ref: '#/components/parameters/IconParam' - $ref: '#/components/parameters/LanguageParam' - $ref: '#/components/parameters/FormatParam' - $ref: '#/components/parameters/TokenParam' responses: '200': $ref: '#/components/responses/CategoriesDetailsResponse' '400': $ref: '#/components/responses/InvalidQueryErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/PermissionMissingErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /categories/{categoryId}: get: tags: - categories summary: Get the category details for a category ID. description: | The `/categories/{categoryId}` request returns all the groups to which the category belongs. You must supply a `category ID` to use this request. **Note**: Query parameters are case-sensitive. Categories use Foursquare's Open Source Places system: Copyright 2024 Foursquare Labs, Inc. All rights reserved. Licensed under the Apache License. Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [the Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0). Unless required by applicable law or agreed in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License." operationId: categoriesCategoryIdGet x-arcgis-frontmatter: keywords: - place - poi - category - categoryId parameters: - $ref: '#/components/parameters/CategoryIdParam' - $ref: '#/components/parameters/IconParam' - $ref: '#/components/parameters/LanguageParam' - $ref: '#/components/parameters/FormatParam' - $ref: '#/components/parameters/TokenParam' responses: '200': $ref: '#/components/responses/CategoryDetailsResponse' '400': $ref: '#/components/responses/InvalidQueryErrorResponse' '404': $ref: '#/components/responses/IdNotFoundErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/PermissionMissingErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /places/near-point: get: tags: - places operationId: nearPointGet x-arcgis-frontmatter: keywords: - place - poi - point - location - search summary: Search for places near a point or location by radius. description: | The `/places/near-point` request finds places that are within a given radius of a specified location. The returned places contain basic data such as name, category and location. To perform the request, you must supply the `x` and `y` coordinates of the point from which to search. Optionally, you can also specify the: - Search radius (1 to 10,000 meters) - Category IDs - Search text If the `pagination.nextUrl` property in the response is populated, then you can page through the results to return more places. The maximum number of places that can be paged to is 200. **Note**: You cannot permanently store places. Please see the [Terms of use](https://developers.arcgis.com/documentation/mapping-apis-and-services/deployment/terms-of-use/). **Note**: Query parameters are case-sensitive. parameters: - in: query name: x description: The x coordinate, or longitude, to search from, in WGS84 decimal degrees. schema: $ref: '#/components/schemas/XCoord' required: true examples: xCoordRedlands: value: -117.205 summary: X (longitude) of Redlands, CA, USA xCoordEdinburgh: value: -3.18 summary: X (longitude) of Edinburgh, Scotland xCoordSydney: value: 151.209 summary: X (longitude) of Sydney, Australia xCoordWembleyStadium: value: -0.279 summary: X (longitude) of Wembley Stadium, London - in: query name: y description: The y coordinate, or latitude, to search from, in WGS84 decimal degrees. required: true schema: $ref: '#/components/schemas/YCoord' examples: yCoordRedlands: value: 34.056 summary: Y (latitude) of Redlands, CA, USA yCoordEdinburgh: value: 55.953 summary: Y (latitude) of Edinburgh, Scotland yCoordSydney: value: -33.869 summary: Y (latitude) of Sydney, Australia yCoordWembleyStadium: value: 51.556057 summary: Y (latitude) of Wembley Stadium, London - $ref: '#/components/parameters/RadiusParam' - $ref: '#/components/parameters/CategoryIdsParam' - $ref: '#/components/parameters/SearchTextParam' - $ref: '#/components/parameters/PageSizeParam' - $ref: '#/components/parameters/IconParam' - $ref: '#/components/parameters/OffsetParam' - $ref: '#/components/parameters/FormatParam' - $ref: '#/components/parameters/TokenParam' responses: '200': $ref: '#/components/responses/NearPointResponse' '400': $ref: '#/components/responses/InvalidQueryErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/PermissionMissingErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /places/within-extent: get: tags: - places operationId: withinExtentGet x-arcgis-frontmatter: keywords: - place - poi - extent - bounding box - search summary: Search for places within an extent (bounding box). description: | The `/places/within-extent` request searches for places within an extent (bounding box). You must supply the `xmin`, `ymin`, `xmax` and `ymax` coordinates to define the extent. The maximum width and height of an extent that can be used in a search is 20,000 meters. The width and height of an extent must be greater than 0 meters. You can also provide multiple categories or search text to find specific types of places within the extent. The default number of places returned (`pageSize`) is 10. The maximum `pageSize` value is 20. If the `pagination.nextUrl` property in the response is populated, then you can page through the results to return more places. The maximum number of places that can be paged to is 200. **Note**: You cannot permanently store places. Please see the [Terms of use](https://developers.arcgis.com/documentation/mapping-apis-and-services/deployment/terms-of-use/). **Note**: Query parameters are case-sensitive. parameters: - $ref: '#/components/parameters/XMinParam' - $ref: '#/components/parameters/YMinParam' - $ref: '#/components/parameters/XMaxParam' - $ref: '#/components/parameters/YMaxParam' - $ref: '#/components/parameters/CategoryIdsParam' - $ref: '#/components/parameters/SearchTextParam' - $ref: '#/components/parameters/IconParam' - $ref: '#/components/parameters/PageSizeParam' - $ref: '#/components/parameters/OffsetParam' - $ref: '#/components/parameters/FormatParam' - $ref: '#/components/parameters/TokenParam' responses: '200': $ref: '#/components/responses/WithinExtentResponse' '400': $ref: '#/components/responses/InvalidQueryErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/PermissionMissingErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /places/{placeId}: get: tags: - places operationId: placeIdGet x-arcgis-frontmatter: keywords: - place - poi - details - placeId summary: Get place details including name, address, description, and other attributes. description: | The `/places/{placeId}` request returns details for a place. To request details, you use the `requestedFields` parameter to specify the fields and the attributes you want from the **Place**, **Address**, **Details** and/or **Location** price groups. It is always recommended to specify the fields you want, however, you can also use `requestedFields=all` to return all of the attributes available. By default, The `placeId` attribute is always returned in addition to the other attributes you requested. The attributes available for places may vary. For example, opening hours may not be available (or applicable) for geographic places or landmarks. You will only be charged for attributes that contain valid values for the requested fields. If no data is available for the requested field, `null` or an empty collection is returned and you are not charged. You are only charged once if one or more attributes with valid values are returned from a price group. To learn more, go to [Pricing](https://developers.arcgis.com/pricing/). Field | Price group --- | --- additionalLocations:dropOff | Location additionalLocations:frontDoor | Location additionalLocations:road | Location additionalLocations:roof | Location address:adminRegion | Address address:censusBlockId | Address address:country | Address address:designatedMarketArea | Address address:extended | Address address:locality | Address address:neighborhood | Address address:poBox | Address address:postcode | Address address:postTown | Address address:region | Address address:streetAddress | Address categories | Place chains | Details contactInfo:email | Details contactInfo:fax | Details contactInfo:telephone | Details contactInfo:website | Details description | Details hours:opening | Details hours:openingText | Details hours:popular | Details location | Location name | Place rating:price | Details rating:user | Details socialMedia:facebookId | Details socialMedia:instagram | Details socialMedia:twitter | Details **Note**: Due to limitations with the underlying data source, the following fields will currently return `null`: Field | Price group --- | --- address:censusBlockId | Address address:designatedMarketArea | Address address:extended | Address address:neighborhood | Address additionalLocations:* | Location chains | Details contactInfo:fax | Details description | Details hours:* | Details rating:* | Details **Note**: You cannot permanently store places. Please see the [Terms of use](https://developers.arcgis.com/documentation/mapping-apis-and-services/deployment/terms-of-use/). **Note**: Query parameters are case-sensitive. **Note**: Can be used in conjunction with the [Basemap Styles service](https://developers.arcgis.com/rest/basemap-styles) to request additional attributes for places retrieved using the [Places for basemaps](https://developers.arcgis.com/documentation/mapping-apis-and-services/maps/places-for-basemaps) workflow. parameters: - name: placeId in: path description: The Id of the place for which you want to fetch additional details. required: true schema: $ref: '#/components/schemas/PlaceId' examples: esriIncPlaceId: summary: Place Id for Esri International, Redlands. value: 2880ba4b89db36eb3470e4c557f81a5c - $ref: '#/components/parameters/RequestedFieldsParam' - $ref: '#/components/parameters/IconParam' - $ref: '#/components/parameters/FormatParam' - $ref: '#/components/parameters/TokenParam' responses: '200': $ref: '#/components/responses/PlaceDetailsResponse' '400': $ref: '#/components/responses/InvalidQueryErrorResponse' '404': $ref: '#/components/responses/IdNotFoundErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/PermissionMissingErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' components: schemas: PlaceId: type: string description: | An ID that uniquely identifies a place. A place ID is a 32 character string. minLength: 32 maxLength: 32 example: 2da082218b6f7538e52250999c8f8ef1 NearPointResult: type: object description: | A result of searching for places using a `places/near-point` request. The result object includes a single place that satisfied the search and the distance from the search point, in meters. required: - placeId - location - name - categories - distance additionalProperties: false properties: placeId: description: | The unique Id of this place. This place Id can be passed to the `places/{placeId}` endpoint to retrieve additional details. allOf: - $ref: '#/components/schemas/PlaceId' example: 2da082218b6f7538e52250999c8f8ef1 location: description: | The location of this place as a WGS84 point. $ref: '#/components/schemas/Point' example: x: -117.194769 y: 34.057289 categories: type: array description: | A list of category objects for a place. Categories are uniquely identified by a `categoryId`. For example, `4bf58dd8d48988d115951735` identifies a "Bicycle Store" and `4bf58dd8d48988d184941735` identifies a "Stadium". Note that a single place can belong to multiple categories (for example, a petrol station could also have a super-market). items: $ref: '#/components/schemas/Category' example: - categoryId: 63be6904847c3692a84b9b90 label: Technology Business name: description: | The name of the place, or point of interest. You can search for places by name using the `searchText` property in a `places/near-point` or `places/within-extent` request. type: string minLength: 1 example: Esri International distance: description: | The distance, in meters, from the place to the search point of a 'places/near-point` query. type: number minimum: 0 example: 50.0 icon: description: | Details of an icon, suitable for depicting this place. To fetch icon details use the `icon` query parameter. allOf: - $ref: '#/components/schemas/IconDetails' WithinExtentResult: type: object description: | A result of searching for places using a `places/within-extent` request. The result object includes a single place that satisfied the search. required: - placeId - location - name - categories additionalProperties: false properties: placeId: description: | The unique Id of this place. This place Id can be passed to the `places/{placeId}` endpoint to retrieve additional details. allOf: - $ref: '#/components/schemas/PlaceId' example: 2da082218b6f7538e52250999c8f8ef1 location: description: | The location of this place as a WGS84 point. $ref: '#/components/schemas/Point' example: x: -117.194769 y: 34.057289 categories: type: array description: | A list of category objects for a place. Categories are uniquely identified by a `categoryId`. For example, `4bf58dd8d48988d115951735` identifies a "Bicycle Store" and `4bf58dd8d48988d184941735` identifies a "Stadium". Note that a single place can belong to multiple categories (for example, a petrol station could also have a super-market). items: $ref: '#/components/schemas/Category' example: - categoryId: 63be6904847c3692a84b9b90 label: Technology Business name: description: | The name of the place, or point of interest. You can search for places by name using the `searchText` property in a `places/near-point` or `places/within-extent` request. type: string minLength: 1 example: Esri International icon: description: | Details of an icon, suitable for depicting this place. To fetch icon details use the `icon` query parameter. allOf: - $ref: '#/components/schemas/IconDetails' PlaceDetails: type: object required: - placeId description: | The additional details for a `Place`, including address, contact details, opening hours, and rating. You can request additional details for a place by using the `placeId` in a `places/{placeId}` request. Use the `requestedFields` query parameter to choose the fields or attributes that are included in the response. additionalProperties: false properties: placeId: description: | The unique Id of this place. allOf: - $ref: '#/components/schemas/PlaceId' example: 2da082218b6f7538e52250999c8f8ef1 categories: type: array description: | A list of category objects for a place. Categories are uniquely identified by a `categoryId`. For example, `4bf58dd8d48988d115951735` identifies a "Bicycle Store" and `4bf58dd8d48988d184941735` identifies a "Stadium". Note that a single place can belong to multiple categories (for example, a petrol station could also have a super-market). This property is part of the "Place" attribute group. items: $ref: '#/components/schemas/Category' example: - categoryId: 63be6904847c3692a84b9b90 label: Technology Business name: description: | The name of the place, or point of interest. This property is part of the "Place" attribute group. type: string minLength: 1 example: Esri International location: description: | The location of this place as a WGS84 point. This property is part of the "Location" attribute group. $ref: '#/components/schemas/Point' example: x: -117.194769 y: 34.057289 description: type: string nullable: true description: | A text description of the place. This property is part of the "Details" attribute group. example: | Esri is the global market leader in geographic information system (GIS) technology, location intelligence, mapping software, and spatial analytics. Esri software is deployed in more than 350,000 organizations and 75 percent of Fortune 500 companies. minLength: 1 address: description: | The address of the place or point of interest (POI). This object and child properties are part of the "Address" attribute group. $ref: '#/components/schemas/Address' additionalLocations: description: | A set of additional locations that represent the place as WGS84 points, for example the location of the front door, or of a drop off point. This object and child properties are part of the "Location" attribute group. $ref: '#/components/schemas/AdditionalLocations' contactInfo: description: | Contact information for the place, such as the telephone number or email address. This object and child properties are part of the "Details" attribute group. $ref: '#/components/schemas/ContactInfo' socialMedia: description: | Social media information associated with the place. This object and child properties are part of the "Details" attribute group. $ref: '#/components/schemas/SocialMedia' hours: description: | The operating hours for the place, including hours of opening and popular times. This object and child properties are part of the "Details" attribute group. $ref: '#/components/schemas/Hours' rating: description: | Rating information supplied by users of the place. This object and child properties are part of the "Details" attribute group. $ref: '#/components/schemas/Rating' chains: description: | Information about all the chains the place belongs to. This object and child properties are part of the "Details" attribute group. example: - name: Starbucks type: array items: $ref: '#/components/schemas/ChainInfo' minItems: 0 icon: description: | Details of an icon, suitable for depicting this place. To fetch icon details use the `icon` query parameter. allOf: - $ref: '#/components/schemas/IconDetails' CategoryId: type: string minLength: 5 maxLength: 24 example: 4bf58dd8d48988d115951735 Category: type: object required: - categoryId - label description: | Represents the category of a place. You can get more information on categories from the `places/categories` endpoint. additionalProperties: false properties: categoryId: description: | The category Id uniquely identifies this category or type of place. The name of the category can be looked up using the `places/categories` endpoint. For example, "4bf58dd8d48988d115951735" is the id for a "Bicycle Store". allOf: - $ref: '#/components/schemas/CategoryId' example: 4bf58dd8d48988d115951735 label: description: | The label that describes the category. type: string example: Bicycle Store minLength: 1 CategoryDetails: type: object required: - categoryId - fullLabel description: | Provides details about a category or type of place. Categories are hierarchical so that you can filter places based on specific categories such as "Provençal Restaurant", or with more generic types such as "Restaurant". A category such as "Provençal Restaurant" includes the details of its more generic parent, such as "French Restaurant". additionalProperties: false properties: categoryId: description: | A unique identifying string for a category. This matches the `categoryId` of a place's `category` property. allOf: - $ref: '#/components/schemas/CategoryId' example: 4bf58dd8d48988d115951735 fullLabel: description: | The full list of labels that describe the category, including its more generic parent categories. type: array items: type: string example: - Retail - Sporting Goods Retail - Bicycle Store minItems: 1 parents: description: | The list of parent category Ids for this category. type: array items: type: string example: - 4bf58dd8d48988d1f2941735 minItems: 0 icon: description: | Details of an icon, suitable for depicting this place. To fetch icon details use the `icon` query parameter. allOf: - $ref: '#/components/schemas/IconDetails' XCoord: type: number format: double description: An x-coordinate, or longitude, in WGS84 decimal degrees. minimum: -180.0 maximum: 180.0 example: -117.194769 YCoord: type: number format: double description: A y-coordinate, or latitude, in WGS84 decimal degrees. minimum: -90.0 maximum: 90.0 example: 34.057289 SearchDistance: type: number format: float description: | A search distance in meters. minimum: 1 maximum: 10000 default: 1000 example: 50 Point: type: object description: | A point defined in WGS84 decimal degrees. required: - x - y example: x: -117.194769 y: 34.057289 additionalProperties: false properties: x: $ref: '#/components/schemas/XCoord' description: The x, or longitude, of this location in WGS84 decimal degrees. y: $ref: '#/components/schemas/YCoord' description: The y, or latitude, of this location in WGS84 decimal degrees. NullablePoint: type: object nullable: true description: | A point defined in WGS84 decimal degrees. required: - x - y example: x: -117.194769 y: 34.057289 additionalProperties: false properties: x: $ref: '#/components/schemas/XCoord' description: The x, or longitude, of this location in WGS84 decimal degrees. y: $ref: '#/components/schemas/YCoord' description: The y, or latitude, of this location in WGS84 decimal degrees. TimeRange: type: object description: | A pair of times defining the start and end of a time period. For example, this could define opening hours or popular hours. Hours are shown in 24-hour time in the local timezone of the place or POI. Where a time range is 24-hours (for example a venue that is open 24-hours), the `from` property will be 00:00 and the `to` property will be 23:59. required: - from - to additionalProperties: false example: from: 10:00 to: 13:00 properties: from: description: The start of a time range in the format "HH:MM". type: string pattern: ^\d{2}:\d{2}$ example: 09:00 to: description: The end of a time range in the format "HH:MM". type: string pattern: ^\d{2}:\d{2}$ example: 15:30 HoursByDay: type: object nullable: true description: | The opening or popular hours for a place. Opening hours are shown by day of the week. Each day can have several pairs of from and to times. For example, if a coffee shop is open from 9:00 until 12:00 and then again from 13:00 until 17:00, it would contain two pairs of opening/closing times: 9:00 paired with 12:00 and 13:00 with 17:00. Hours are shown in 24-hour time in the local timezone of the place or POI. additionalProperties: false properties: monday: example: - from: 09:00 to: 17:00 type: array items: $ref: '#/components/schemas/TimeRange' tuesday: example: - from: 09:00 to: 17:00 type: array items: $ref: '#/components/schemas/TimeRange' wednesday: example: - from: 09:00 to: 12:00 - from: 13:00 to: 17:00 type: array items: $ref: '#/components/schemas/TimeRange' thursday: example: - from: 09:00 to: 17:00 type: array items: $ref: '#/components/schemas/TimeRange' friday: example: - from: 09:00 to: 17:00 type: array items: $ref: '#/components/schemas/TimeRange' saturday: example: - from: 10:00 to: 17:00 type: array items: $ref: '#/components/schemas/TimeRange' sunday: example: - from: 11:00 to: 12:00 type: array items: $ref: '#/components/schemas/TimeRange' Hours: type: object description: | Lists the opening hours of this place or POI along with the popular or busy hours. A string is also provided that can be used for display. additionalProperties: false properties: opening: description: | The opening hours for a place. Opening hours are shown by day of the week. Each day can have several pairs of from and to times. For example, if a coffee shop is open from 9:00 until 12:00 and then again from 13:00 until 17:00, it would contain two pairs of from/to times: 09:00 paired with 12:00 and 13:00 with 17:00. Opening hours are shown in 24-hour time in the local timezone of the place or POI. $ref: '#/components/schemas/HoursByDay' example: monday: - from: 09:00 to: 17:00 tuesday: - from: 09:00 to: 17:00 wednesday: - from: 09:00 to: 12:00 - from: 13:00 to: 17:00 thursday: - from: 09:00 to: 17:00 friday: - from: 09:00 to: 17:30 saturday: - from: 10:00 to: 17:00 sunday: - from: 11:00 to: 12:00 popular: description: | The popular or busy hours for a place. Popular hours are shown by day of the week. Each day can have several pairs of from and to times. For example, if a coffee shop is popular from 9:00 until 10:00 and then again from 14:00 until 15:00, it would contain two pairs of from/to times: 09:00 paired with 10:00 and 14:00 with 15:00. Popular hours are shown in 24-hour time in the local timezone of the place or POI. $ref: '#/components/schemas/HoursByDay' example: monday: - from: 10:00 to: 12:00 - from: 14:00 to: 15:00 tuesday: - from: 14:00 to: 15:00 wednesday: - from: 10:00 to: 12:00 - from: 14:00 to: 15:00 thursday: - from: 14:00 to: 15:00 friday: - from: 15:00 to: 17:00 saturday: - from: 10:00 to: 12:00 sunday: - from: 11:00 to: 12:00 openingText: description: | The opening hours for this place, formatted for display. type: string nullable: true minLength: 1 example: Mon-Thu 12:00 PM-11:00 PM; Fri-Sat 12:00 PM-11:30 PM; Sun 12:00 PM-10:30 PM Rating: type: object description: | Rating information about the price and user rating of the place. additionalProperties: false properties: price: type: string nullable: true description: | An indication of the overall price of a place based on user reviews. enum: - cheap - moderate - expensive - veryExpensive example: cheap user: description: | A rating for the place based on user-reviews from 0 to 5, where 5 is the best rating. type: number nullable: true format: float example: 4.5 minimum: 0 maximum: 5 AdditionalLocations: type: object description: | A set of additional locations for the place, as WGS84 points. This list provides alternative locations for accessing a place such as `frontDoor` or `road`. additionalProperties: false properties: dropOff: description: | A location for drop-off/pick-up for a place. $ref: '#/components/schemas/NullablePoint' example: x: -0.279541 y: 51.556057 frontDoor: description: | A location for the front door for a place. $ref: '#/components/schemas/NullablePoint' example: x: -0.279541 y: 51.556057 road: description: | A road-side location for a place. $ref: '#/components/schemas/NullablePoint' example: x: -0.279541 y: 51.556057 roof: description: | A location in the roof centroid for a place. $ref: '#/components/schemas/NullablePoint' example: x: -0.279541 y: 51.556057 Address: type: object description: | The address of a place, or point of interest (POI). additionalProperties: false properties: streetAddress: type: string nullable: true minLength: 1 example: 380 New York St description: | The street address for a place, for example the street name and number. extended: type: string nullable: true minLength: 1 example: Unit 32 description: | Additional address information, including suite or apartment numbers. locality: type: string nullable: true minLength: 1 example: Redlands description: The city, town, or equivalent. designatedMarketArea: type: string nullable: true minLength: 1 example: Los Angeles description: | As defined by Nielsen, signifies a region where the population can receive similar TV and radio offerings (US only). region: type: string nullable: true minLength: 1 example: CA description: | The state, province, territory or equivalent. postcode: type: string nullable: true minLength: 1 example: '92373' description: | Postal code or equivalent (zip code in the US). Format will be localized based on country. poBox: type: string nullable: true minLength: 1 description: Post-office box. country: type: string nullable: true example: US description: Two letter ISO country code minLength: 2 maxLength: 2 adminRegion: type: string nullable: true minLength: 1 example: Scotland description: | Additional sub-division. Usually, but not always, a country sub-division (e.g., Scotland). postTown: type: string nullable: true minLength: 1 example: Edinburgh description: | Town/place employed in postal addressing. neighborhood: type: array items: type: string minItems: 0 description: | The neighborhoods of the place. example: - Downtown censusBlockId: type: string nullable: true minLength: 1 maxLength: 15 description: | The census block Id of the place (US only). example: '060710081003002' SocialMedia: type: object description: | The social media details for a place. additionalProperties: false properties: facebookId: description: The facebook Id of the place. type: string nullable: true minLength: 1 example: 183768242996 twitter: description: The twitter handle of the place. type: string nullable: true minLength: 1 example: esri instagram: description: The instagram ID of the place. type: string nullable: true minLength: 1 example: esrigram ContactInfo: type: object description: | The contact information for a place. additionalProperties: false properties: telephone: description: The telephone number of the place. type: string nullable: true minLength: 1 example: (909) 793-2853 website: description: The website address of the place. type: string nullable: true format: url example: https://www.esri.com fax: description: Fax number. type: string nullable: true minLength: 1 example: 0800 169 2008 email: description: Email address. type: string nullable: true minLength: 1 example: support@esri.com ChainInfo: type: object description: | Information about a chain that a place belongs to. additionalProperties: false properties: name: description: | The name of the chain. type: string nullable: true minLength: 1 example: Starbucks Pagination: type: object description: | Provides pagination links for accessing more results for the current request. properties: previousUrl: type: string format: url minLength: 1 description: | A url for fetching the previous page of results. Use this property to request the previous page of results if available. If this property is omitted then there are no previous pages of results. You must also supply authentication details, such as a `token`, to make a previous page request. example: https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?x=-117.194769&y=34.057289&radius=50.0&offset=0&pageSize=10 nextUrl: type: string format: url minLength: 1 description: | A url for fetching the next page of results. Use this property to request the next page of results if available. If this property is omitted then there are no more pages of results available. You must also supply authentication details, such as a `token`, to make a next page request. example: https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?x=-117.194769&y=34.057289&radius=50.0&offset=20&pageSize=10 additionalProperties: false Error: type: object properties: error: description: Error information type: object properties: code: description: | A code identifying the type of error. This can be an HTTP status code, `498` (invalid or expired token), or `499` (missing token). type: integer example: 400 enum: - 400 - 401 - 403 - 404 - 498 - 499 - 500 message: description: A message describing the error. type: string minLength: 1 example: Parameter invalid. details: description: List of details about the error. type: array items: type: string minItems: 0 restInfoUrl: description: | A link to general information about the service, such as the owning system and token service URL. This property is only present for errors relating to tokens. type: string format: url example: https://places-api.arcgis.com/arcgis/rest/info required: - code - message required: - error IconDetails: description: | Information about an icon for depicting a place or category. type: object additionalProperties: false properties: url: description: | Url for an icon for this place or category in either `svg`, `cim` or `png` format. type: string format: url example: https://static.arcgis.com/icons/places/Default_Shop_or_Service_15.svg securitySchemes: ArcGISTokenParameter: type: apiKey in: query name: token description: | The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:places` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the Places service. The `token` parameter can be either an API Key or short-lived token. See [ArcGIS security documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/) for more information on authenticating with a token or API key. ArcGISAuthorizationHeader: type: http scheme: bearer bearerFormat: 'Authorization: Bearer ' description: | The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:places` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the Places service. The authorization parameter can be either an API Key or short-lived token. See [ArcGIS security documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/) for more information on authenticating with a token or API key. Supply the token in the request header using the "Bearer" scheme: `Authorization: Bearer ` ArcGISXEsriAuthorizationHeader: type: http scheme: bearer bearerFormat: 'X-Esri-Authorization: Bearer ' description: | The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:places` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the Places service. The authorization parameter can be either an API Key or short-lived token. See [ArcGIS security documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/) for more information on authenticating with a token or API key. Supply the token in the request header using the "Bearer" scheme: `X-Esri-Authorization: Bearer ` responses: UnauthorizedErrorResponse: description: Authentication Error. The API key or token is missing, invalid or expired. content: application/json: schema: $ref: '#/components/schemas/Error' ServerErrorResponse: description: An error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/Error' InvalidQueryErrorResponse: description: Invalid query parameters. content: application/json: schema: $ref: '#/components/schemas/Error' IdNotFoundErrorResponse: description: A resource with the supplied Id was not found. content: application/json: schema: $ref: '#/components/schemas/Error' PermissionMissingErrorResponse: description: | The required parameter 'token' is valid but does not have permission to access the service. content: application/json: schema: $ref: '#/components/schemas/Error' CategoryDetailsResponse: description: A successful request to return details for a single category. content: application/json: schema: $ref: '#/components/schemas/CategoryDetails' CategoriesDetailsResponse: description: Details of categories that a `Place` can belong to. content: application/json: schema: required: - categories type: object properties: categories: type: array items: $ref: '#/components/schemas/CategoryDetails' links: GetPlacesFilter: operationId: nearPointGet description: | The `categoryId` values can be used in the `categoryIds` parameter in `GET /near-point`. NearPointResponse: description: A successful response for a `places/near-point` request. content: application/json: schema: required: - results type: object properties: results: type: array items: $ref: '#/components/schemas/NearPointResult' minItems: 0 pagination: $ref: '#/components/schemas/Pagination' links: GetPlaceById: operationId: placeIdGet description: | The `placeId` value returned for places in the response can be used as the `placeId` parameter in `GET /{placeId}`. GetCategoryById: operationId: categoriesCategoryIdGet description: | The `categoryId` value returned for places in the response can be used as the `categoryId` parameter in `GET /categories/{categoryId}`. GetNextPlaces: operationId: nearPointGet description: | The `nextUrl` can be used to fetch the next page of results. GetPreviousPlaces: operationId: nearPointGet description: | The `previousUrl` can be used to fetch the previous page of results, if available. WithinExtentResponse: description: A successful response for a `places/within-extent` request. content: application/json: schema: required: - results type: object properties: results: type: array items: $ref: '#/components/schemas/WithinExtentResult' minItems: 0 pagination: $ref: '#/components/schemas/Pagination' links: GetPlaceById: operationId: placeIdGet description: | The `placeId` value returned for places in the response can be used as the `placeId` parameter in `GET /places/{placeId}`. GetCategoryById: operationId: categoriesCategoryIdGet description: | The `categoryId` value returned for places in the response can be used as the `categoryId` parameter in `GET /categories/{categoryId}`. GetNextPlaces: operationId: nearPointGet description: | The `nextUrl` can be used to fetch the next page of results. GetPreviousPlaces: operationId: nearPointGet description: | The `previousUrl` can be used to fetch the previous page of results, if available. PlaceDetailsResponse: description: A successful response for a `places/{placeId}` request. content: application/json: schema: required: - placeDetails type: object properties: placeDetails: $ref: '#/components/schemas/PlaceDetails' examples: esriInc: $ref: '#/components/examples/placeDetailsExample' parameters: RadiusParam: name: radius in: query description: | The radius in meters to search for places - measured from the supplied `x` and `y` coordinate. A radius of 100 meters will result in a circular search area that is 200 meters in diameter. If omitted, the default search radius will be 1,000 meters. schema: $ref: '#/components/schemas/SearchDistance' examples: searchDist50: value: 50 summary: Search radius of 50 meters searchDist2km: value: 2000 summary: Search radius of 2 kilometers searchDist1Mile: value: 1609 summary: Search radius of 1 mile (1,609 meters) XMinParam: name: xmin in: query description: | The minimum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees. This is the furthest _west_ that will be searched. schema: $ref: '#/components/schemas/XCoord' required: true examples: centralParkMinX: summary: West of central park, NYC. value: -73.982 YMinParam: in: query name: ymin description: | The minimum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees. This is the furthest _south_ that will be searched. examples: centralParkMinY: summary: South of central park, NYC. value: 40.764 required: true schema: $ref: '#/components/schemas/YCoord' XMaxParam: in: query name: xmax description: | The maximum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees. This is the furthest _east_ that will be searched. schema: $ref: '#/components/schemas/XCoord' required: true examples: centralParkMaxX: summary: East of central park, NYC. value: -73.949 YMaxParam: in: query name: ymax description: | The maximum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees. This is the furthest _north_ that will be searched. required: true schema: $ref: '#/components/schemas/YCoord' examples: centralParkMaxY: summary: North of central park, NYC. value: 40.801 CategoryIdsParam: name: categoryIds in: query description: | Filters places to those that match the category Ids. Places will be returned if they match _any_ of the category Ids. If this property is not set, places will be returned regardless of their category. You can obtain information on category Ids from the `places/categories` endpoint. For example, to filter for places where the category is "Bicycle Store", include the categoryId `4bf58dd8d48988d115951735` in this property. You can search up to a maximum of `10` category Ids. required: false explode: false schema: type: array items: $ref: '#/components/schemas/CategoryId' minLength: 1 maxLength: 10 uniqueItems: true examples: coffeeShopOrBakery: value: - 4bf58dd8d48988d1e0931735 - 4bf58dd8d48988d16a941735 summary: Coffee Shop or Bakery bicycleStore: value: - 4bf58dd8d48988d115951735 summary: Bicycle Store SearchTextParam: name: searchText in: query description: | Free search text for places against names, categories etc. required: false schema: type: string minLength: 3 maxLength: 255 examples: coffeeSearch: summary: Search for places with a name or category containing "Coff" value: Coff PageSizeParam: name: pageSize in: query required: false description: | The number of places that should be sent in the response for a single request. You can set this to any value up to `20` when you need to control the size of responses that your app downloads. If the query results in more than this page size, then the response object will contain a `pagination.nextUrl`. This can be used to request the next page of results. Regardless of paging, the maximum number of places that can be returned in total is `200`. The default `pageSize` is 10. schema: type: integer minimum: 1 maximum: 20 default: 10 examples: pageSize10: summary: Page size of 10 value: 10 OffsetParam: name: offset in: query required: false description: | Request results starting from the given offset. This parameter works with the `pageSize` parameter to fetch results from subsequent pages. For example, with a page size of 2, setting the `offset` to `2` would return the 3rd and 4th results. Regardless of paging, the maximum number of places that can be returned in total is `200`. schema: type: integer minimum: 0 maximum: 199 default: 0 examples: offset10: summary: Fetch results starting from the 10th value: 10 FormatParam: name: f in: query description: | The requested response format - either `json` or `pjson` (pretty json). schema: type: string default: json enum: - json - pjson CategoryIdParam: name: categoryId in: path description: | The ID of the category that you want to fetch details for. For example, using a category ID of `4bf58dd8d48988d1e0931735` would fetch details about the "Coffee Shop" category. required: true schema: $ref: '#/components/schemas/CategoryId' examples: bicycleStore: value: 4bf58dd8d48988d115951735 summary: Category Id for Bicycle Store coffeeShop: value: 4bf58dd8d48988d1e0931735 summary: Category Id for Coffee Shop CategoriesFilterParam: name: filter in: query description: | A text filter that will be used for searching categories. The text must be at least three characters and will be applied as a partial match. For example, using the filter "off" would return categories using the word "Office" as well as those using the word "Coffee". required: false schema: type: string minLength: 3 maxLength: 255 examples: coffeeSearch: summary: Search for "Coffee" value: Coffee RequestedFieldsParam: name: requestedFields required: true in: query description: | The array of fields that define the attributes to return for a place. Use this parameter to define the attributes you would like returned, for example `requestedFields=name,address:streetAddress`. However, you can also set this value to `requestedFields=all` to return all of the attributes available for a place. The `placeId` attribute is always returned in addition to the other attributes you requested. If a valid attribute value is not available, `null`, or an empty collection, is returned and you are not charged for it. To see the fields and pricing groups they belong to, go to the table above. explode: false schema: type: array minItems: 1 items: type: string enum: - all - additionalLocations - additionalLocations:dropOff - additionalLocations:frontDoor - additionalLocations:road - additionalLocations:roof - address - address:adminRegion - address:censusBlockId - address:country - address:designatedMarketArea - address:extended - address:locality - address:neighborhood - address:poBox - address:postcode - address:postTown - address:region - address:streetAddress - categories - contactInfo - contactInfo:email - contactInfo:fax - contactInfo:telephone - contactInfo:website - chains - description - hours - hours:opening - hours:openingText - hours:popular - location - name - rating - rating:price - rating:user - socialMedia - socialMedia:facebookId - socialMedia:instagram - socialMedia:twitter examples: addressGroupAttributes: value: - address detailsGroupAttributes: value: - contactInfo - chains - description - hours - rating - socialMedia allRequested: value: - all summary: Return all details for this place. TokenParam: name: token in: query description: | The authentication token, created from an ArcGIS Location Platform account, with the `premium:user:places` [privilege](https://developers.arcgis.com/rest/users-groups-and-items/privileges.htm), used to access the Places service. The `token` parameter can be either an API Key or short-lived token. See [ArcGIS security documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/) for more information on authenticating with a token or API key. Alternatively, you can supply a token in the request header with one of the following keys using the "Bearer" scheme: - `Authorization: Bearer ` - `X-Esri-Authorization: Bearer ` schema: type: string IconParam: name: icon in: query description: | Determines whether icons are returned and the type of icon to use with a place or category. ![example icon](https://static.arcgis.com/icons/places/Zoo_48.png) Use this parameter to define the type of icon URL for a given place or category. Place icons are available in the following formats: - `svg` - `cim` ([Cartographic Information Model](https://developers.arcgis.com/documentation/glossary/cim-symbol/)) - `png` 48 x 48 pixels The SVG and CIM symbols default to 15 x 15 pixels but can be scaled smoothly for display in larger UI elements or to emphasize these features on a map. The PNG icons are provided as 48 x 48 pixels but for map display the recommended size is 16 x 16 pixels. The default is `none` (no icon URL will be returned). explode: false schema: type: string default: none enum: - none - svg - png - cim examples: svg: value: - svg summary: Return the `.svg` icon URL for a given place. cim: value: - cim summary: Return the CIM icon URL for a given place. LanguageParam: name: language in: query description: | Optional case-sensitive parameter to specify the preferred language to use for category names. This query parameter uses language codes to specify the preferred language. If not set, or if no translation is available, the default behavior is to return category names in English. The language codes use the [CLDR](https://cldr.unicode.org/) (Common Locale Data Repository) format string that uses a two letter language code (e.g. "fr" for French) optionally followed by a two letter country code (e.g. "fr-CA" for French in Canada). If an unsupported language code is used, then the service will attempt to fall-back to the closest available language. This is done by stripping regional and extension subtags to find a known language code. For example, French Canadian (`fr-CA`) is unsupported so this falls back to French `fr`. Should the fallback fail, then the service will return category names in the default language `en` for English. Language codes: - English, default US - `en` - French - `fr` - German - `de` - Japanese - `ja` - Portuguese, default Brazil - `pt` - Spanish - `es` schema: type: string enum: - en - es - de - fr - ja - pt example: fr default: en examples: placeDetailsExample: value: placeDetails: placeId: 2880ba4b89db36eb3470e4c557f81a5c categories: - categoryId: 4bf58dd8d48988d124941735 label: Office name: Esri Building N location: x: -117.194769 y: 34.057289 description: null address: streetAddress: 380 New York St extended: null locality: Redlands designatedMarketArea: Los Angeles region: CA postcode: 92373 poBox: null country: US adminRegion: null postTown: null neighborhood: [] censusBlockId: null additionalLocations: dropOff: null frontDoor: null road: null roof: null contactInfo: telephone: null website: null fax: null email: null socialMedia: facebookId: null twitter: null instagram: null hours: opening: null popular: null openingText: null rating: price: null user: null chains: []