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

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":

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

On a server-side failure, status is UNKNOWN_ERROR:

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

Example:

{
  "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": []
}