# Place - v4

Source: https://maps.vietmap.vn/docs/map-api/place-v4/

## Place version for merged location search

Place v4 returns the address components and `lat`/`lng` for a `ref_id` obtained from [Autocomplete v4](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/) or [Geocode v4](https://maps.vietmap.vn/docs/map-api/geocode-version/geocode-v4/). Each call counts as one transaction.

### Playground
!!! tip "Try it on the Playground"
    Place v4 runs after a suggestion is picked: type an address into Autocomplete, pick a result, and the Playground calls Place v4 with its `ref_id` to get the coordinates. **[Open the Playground](https://tools.vietmap.vn/playground/autocomplete)**

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration: **<a href="/docs/assets/agents/search-geocoding.txt" download="search-geocoding.txt">Search & Geocoding Agent Doc</a>** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**

Or try it with [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

### URL

``` 
https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid={refid}
```

### Method
GET

### Parameter
|Parameter|Type|Required|Description|Example|
|--- |--- |--- |--- |--- |
|apikey|string|yes|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)||
|refid|string|yes|The `ref_id` value from an Autocomplete v4 or Geocode v4 result, passed verbatim including its `auto:` / `geocode:` prefix|auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU|

### Example 

[:material-play-circle: Try the Autocomplete → Place flow on the Playground](https://tools.vietmap.vn/playground/autocomplete){ .md-button .md-button--primary }


**Input:**
``` 
 https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid=auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU
```

**Response body:**

**Note:** The response uses the same administrative format as the search result the `refid` came from. A `refid` from a new-format (2-level) result returns `district_id: 0` and `district: ""`; a `refid` from an old-format (3-level) result returns all three levels.
```json
{
    "display": "197 Đường Trần Phú,Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "name": "",
    "hs_num": "197",
    "street": "Đường Trần Phú",
    "address": "197 Đường Trần Phú",
    "city_id": 12,
    "city": "Thành Phố Hồ Chí Minh",
    "district_id": 0,
    "district": "",
    "ward_id": 18700,
    "ward": "Phường Chợ Quán",
    "lat": 10.759222947000069,
    "lng": 106.67590269100003
}
```


### Response description
| Parameter  | Type   | Description                                                   |
| ---------- | ------ | ------------------------------------------------------------- |
| display    | string | Display name containing detailed information of the address   |
| name       | string | POI name. Empty string when the result is a plain street address. |
| hs_num     | string | House number or building number                                |
| street     | string | Street name, with its prefix (e.g. `Đường Trần Phú`)          |
| address    | string | House number and street (`hs_num` + `street`)                  |
| city_id    | int    | Unique identifier for the city                                 |
| city       | string | Name of the city                                               |
| district_id| int    | Unique identifier for the district. Currently, it is always `0` for the new display format. For the old display format, it will be the district ID. |
| district   | string | Name of the district. Currently, it is always an empty string for the new display format. For the old display format, it will be the district name. |
| ward_id    | int    | Unique identifier for the ward                                 |
| ward       | string | Name of the ward                                               |
| lat        | number | Latitude coordinate of the address                             |
| lng        | number | Longitude coordinate of the address                            |

### Error codes

| HTTP | Meaning | Response body |
| --- | --- | --- |
| `200` | Success | JSON as in the example above |
| `401` | Wrong or unknown API key | Empty |
| `423` | Quota used up, or this API is not enabled for the key | Plain text, e.g. `Your request is limited` |

On `423`, check the remaining quota in [Monitor API key usage](https://maps.vietmap.vn/docs/map-api/console/monitor-api-key-usage/) and whether the API is enabled for the key in [Manage API keys](https://maps.vietmap.vn/docs/map-api/console/manage-api-key/).

!!! tip "Try it with your own data"
    Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open Place v4 on the Playground](https://tools.vietmap.vn/playground/autocomplete)**