## Nearby Search

Searches for places within a specific area. You can refine results by providing a keyword or specifying a place type.

### Request

#### Endpoint

```
https://dplace-api.themap.world/maps/api/place/nearbysearch/json
```

#### Query params

| Param | Required | Description |
|  --- | --- | --- |
| `location` | Required | Center coordinate, format `{lat},{lng}` (latitude first), for example: `10.7952219,106.7217912` |
| `radius` | Required | Search radius around `location`, in **meters**, max `50000`, for example: `5000` (= 5km) |
| `type` | Optional | One or more place types to filter results, separated by `|`, for example: `hospital|pharmacy` |
| `keyword` | Optional | Keyword to filter nearby results, for example: `"tạp hóa"` |
| `size` | Optional | Number of results returned |
| `has_deprecated_admin` | Optional | `true` if you want to return old_formatted_address, old_address_components |


#### `type` values

| Category | types |
|  --- | --- |
| `food_and_drink` | `food_and_drink`, `restaurant`, `vietnamese_restaurant`, `asian_restaurant`, `japanese_restaurant`, `korean_restaurant`, `chinese_restaurant`, `thai_restaurant`, `western_restaurant`, `italian_restaurant`, `american_restaurant`, `vegetarian_restaurant`, `fast_food`, `food_court`, `street_food`, `buffet_restaurant`, `diner`, `bakery`, `cafe`, `tea_house`, `bubble_tea_shop`, `juice_shop`, `smoothie_shop`, `ice_cream_shop`, `dessert_shop`, `beer_garden`, `wine_bar`, `cocktail_bar` |
| `shopping` | `shopping`, `book_store`, `vehicle_store`, `computer_store`, `convenience_store`, `electronics_store`, `appliance_store`, `cell_phone_store`, `florist`, `grocery_store`, `market`, `furniture_store`, `shopping_mall`, `supermarket`, `fashion_store`, `jewelry_store`, `shoe_store`, `pet_store`, `hardware_store`, `liquor_store`, `gift_shop`, `sporting_goods_store`, `toy_store`, `cosmetics_store`, `optician` |
| `services` | `service`, `hair_salon`, `nail_salon`, `barber_shop`, `spa`, `car_repair`, `car_wash`, `motorcycle_repair`, `mobile_phone_repair`, `electronics_repair`, `gas_station`, `laundry_service`, `parking_lot`, `photography_studio`, `tailor`, `funeral_home`, `travel_agency`, `real_estate_agency`, `notary`, `printing_shop`, `veterinary_care`, `internet_cafe`, `pet_care` |
| `finance` | `finance`,`bank`, `atm`, `insurance_agency`, `money_exchange`, `pawn_shop`, `accounting` |
| `hotels_and_lodging` | `hotels_and_lodging`,`hotel`, `motel`, `villa`, `homestay`, `lodging`, `guest_house`, `resort`, `hostel`, `serviced_apartment` |
| `entertainment_and_recreation` | `entertainment_and_recreation`, `dance_club`, `hiking_area`, `historical_landmark`, `museum`, `park`, `playground`, `tourist_attraction`, `casino`, `garden`, `karaoke`, `live_music_venue`, `wedding_venue`, `event_venue`, `movie_theater`, `night_club`, `plaza`, `zoo` |
| `sports` | `sports`, `arena`, `golf_course`, `gym`, `yoga`, `sport_club`, `stadium`, `swimming_pool`, `tennis_court`, `badminton_court`, `basketball_court`, `fishing_pond` |
| `transportation` | `transportation`, `airport`, `international_airport`, `bridge`, `bus_station`, `bus_stop`, `subway_station`, `train_station`, `transportation_service`, `taxi_stand`, `parking_garage`, `ferry_terminal`, `port` |
| `health_and_wellness` | `health_and_wellness`,`hospital`, `clinic`, `dental_clinic`, `skin_care_clinic`, `pharmacy`, `medical_center`, `optometrist`, `physiotherapy`, `traditional_medicine`, `massage` |
| `religion` | `religion`, `church`, `pagoda`, `place_of_worship`, `buddhist_temple`, `hindu_temple` |
| `office_and_industrial` | `office_and_industrial`, `business_office`, `corporate_office`, `farm`, `ranch`, `manufacturer`, `industrial_park`, `factory` |
| `residential` | `residential` |
| `government` | `government`, `government_office`, `city_hall`, `fire_station`, `police`, `post_office`, `embassy`, `cemetery`, `courthouse`, `local_government_office`, `customs` |
| `education` | `education`, `university`, `college`, `high_school`, `secondary_school`, `primary_school`, `kindergarten`, `preschool`, `driving_school`, `education_center`, `research_institute`, `language_school`, `music_school`, `library`, `vocational_school`, `school` |
| `automotive` | `automotive`, `car_dealer`, `car_rental`, `car_repair`, `car_wash`, `ebike_charging_station`, `electric_vehicle_charging_station`, `gas_station`, `parking`, `parking_garage`, `parking_lot`, `rental_car_agency`, `rest_stop`, `tire_shop`, `truck_dealer`, `motorcycle_repair`, `motorcycle_wash` |
| `natural_features` | `natural_features`, `body_of_water`, `beach`, `island`, `lake`, `mountain`, `mountain_peak`, `river`, `woods`, `forest` |
| `point_of_interest` | `point_of_interest` |


#### Example

```bash
curl --location 'https://dplace-api.themap.world/maps/api/place/nearbysearch/json?location=10.792981,106.639812&radius=5000&keyword=cửa hàng&has_deprecated_admin=true&key=YOUR_API_KEY'
```

### Response

`nearbysearch/json` wraps the response in the following top-level fields:

| Field | When present | Content |
|  --- | --- | --- |
| `status` | always | `OK`, `ZERO_RESULTS`, `INVALID_REQUEST`, or `UNKNOWN_ERROR` |
| `results` | always | array of place objects (empty array on `ZERO_RESULTS` / errors) |
| `error_message` | on `INVALID_REQUEST` / `UNKNOWN_ERROR` | error description |
| `html_attributions` | always | `[]` — no third-party attribution data |


#### `status`

| Value | Meaning |
|  --- | --- |
| `OK` | success, results found |
| `ZERO_RESULTS` | success but no results matched |
| `INVALID_REQUEST` | missing or invalid parameter (HTTP 400) |
| `UNKNOWN_ERROR` | server-side error: timeout, backend unreachable (HTTP 502/500) |


#### `results`

Each item in `results` is a place object with the fields shown in the example response body above:

| Field | When present | Content |
|  --- | --- | --- |
| `place_id` | always | unique identifier for the place |
| `distance` | always | distance from `location`, in km |
| `name` | always | place name |
| `formatted_address` | always | standardized full address |
| `old_formatted_address` | always | address before an administrative merge, or `""` if none |
| `geometry` | always | `location` (lat/lng) and `viewport` (northeast/southwest bounds) |
| `types` | always | array of place type classifications |


#### `error_message`

When the request has an invalid parameter, `nearbysearch/json` still returns HTTP 200 with `status: "INVALID_REQUEST"`:

```json
{
  "status": "INVALID_REQUEST",
  "error_message": "radius must be between 1 and 50000",
  "results": [],
  "html_attributions": []
}
```

On a server-side failure, `status` is `UNKNOWN_ERROR`:

```json
{
  "status": "UNKNOWN_ERROR",
  "error_message": "backend unreachable",
  "results": [],
  "html_attributions": []
}
```

#### Example:

```json
{
  "status": "OK",
  "results": [
    {
      "place_id": "4:venue:fece07bb108e4cccbfde40678984c3c4",
      "distance": 0.12,
      "name": "Tạp Hóa Tuyên Huyền",
      "formatted_address": "Đường Âu Cơ, Phường Tân Phú, Thành phố Hồ Chí Minh, Việt Nam",
      "old_formatted_address": "Đường Âu Cơ, Phường Tân Thành, Quận Tân Phú, Thành phố Hồ Chí Minh, Việt Nam",
      "geometry": {
        "location": {
          "lat": 10.793547630310059,
          "lng": 106.63887786865234
        },
        "viewport": {
          "northeast": {
            "lat": 10.794447630310058,
            "lng": 106.64007786865234
          },
          "southwest": {
            "lat": 10.792647630310059,
            "lng": 106.63767786865235
          }
        }
      },
      "types": [
        "shopping"
      ]
    },
    {
      "place_id": "4:venue:779e3879dc4f47c9beac52899e110b3d",
      "distance": 0.319,
      "name": "Tạp Hóa Thu Trang",
      "formatted_address": "Đường Vạn Hạnh, Phường Tân Sơn Nhì, Thành phố Hồ Chí Minh, Việt Nam",
      "old_formatted_address": "Đường Vạn Hạnh, Phường Tân Thành, Quận Tân Phú, Thành phố Hồ Chí Minh, Việt Nam",
      "geometry": {
        "location": {
          "lat": 10.794112205505371,
          "lng": 106.63713073730469
        },
        "viewport": {
          "northeast": {
            "lat": 10.79501220550537,
            "lng": 106.63833073730468
          },
          "southwest": {
            "lat": 10.793212205505371,
            "lng": 106.63593073730469
          }
        }
      },
      "types": [
        "shopping"
      ]
    }
  ],
  "html_attributions": []
}
```