Skip to main content

Autocomplete with Place Detail per Session

Reduce operational costs and improve user experience by providing real-time place suggestions and detailed place information in the same API session.

This guide helps you integrate the autocomplete feature and simultaneously display place details in a single API session. After completing the integration, your users can quickly find their desired place and receive detailed information about it seamlessly.

🛡️ About session token in Autocomplete + Place Detail​

When using the Autocomplete feature, you should provide a sessiontoken (UUID v4) for each user search session. This helps the system recognize related queries in the same session, resulting in:

  • Cost optimization: Place Detail queries made after a user selects a suggestion from Autocomplete will not be charged separately, only the initial Autocomplete session is charged.
  • Smooth experience: Users can search, select a place, and view details without being charged again for the same result.

How it works​

  1. Step 1: When the user starts typing a search keyword, your app generates a sessiontoken (UUID v4) and includes it in every Autocomplete API call.
  2. Step 2: The user can make multiple Autocomplete queries with the same sessiontoken.
  3. Step 3: When the user finally selects a place and you call Place Detail with the same sessiontoken, all previous Autocomplete queries and this final Place Detail call are considered as one session.
  4. Step 4: Only this session is charged as a single unit, regardless of the number of Autocomplete queries made before the final Place Detail call.

Note:

  • sessiontoken is a UUID v4 string generated by the client (your application) and must be included in every request.
  • Each sessiontoken is only valid for 5 minutes from creation. After 5 minutes, you must generate a new sessiontoken for the next search session.
  • If you call Place Detail without the correct sessiontoken used for Autocomplete, the system will charge it as a separate query.

Example​

# 1. Call Autocomplete with sessiontoken
GET /autocomplete?input=Lotte Mall Tay Ho&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

# 2. Call Place Detail for a place in the autocomplete result, using the same sessiontoken
GET /place?ids=aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

Result:

  • Only the Autocomplete query is charged.
  • The Place Detail query is not charged extra if the correct sessiontoken is used.

Summary​

  • Always generate a new sessiontoken for each search session.
  • Reuse the same sessiontoken for all Place Detail queries related to the Autocomplete results.
  • Only Autocomplete is charged, Place Detail is not charged if using the same sessiontoken.

Base URL​

The base URL for all API requests is:
https://mapapis.openmap.vn/v1

Endpoint​

GET /autocomplete

Example​

Generate a UUID v4 session token: 576e6543-fbc8-422c-9aad-9884c97df128, keep it in your application's session.

You can generate a UUID v4 session token using UUID v4 Generator

Request:

GET /autocomplete?input=Lotte Mall Tây Hồ&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128

Response:

{
  "predictions": [
    {
      "description": "Lotte Mall Tây Hồ, 272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
      "distance_meters": null,
      "matched_substrings": [
        
      ],
      "place_id": "aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc",
      "structured_formatting": {
        "main_text": "Lotte Mall Tây Hồ",
        "main_text_matched_substrings": [
          
        ],
        "secondary_text": "272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
        "secondary_text_matched_substrings": [
          
        ]
      },
      "terms": [
        {
          "offset": 0,
          "value": "Lotte Mall Tây Hồ"
        },
        {
          "offset": 21,
          "value": "272 Đường Võ Chí Công"
        },
        {
          "offset": 51,
          "value": "phường Phú Thượng"
        },
        {
          "offset": 77,
          "value": "quận Tây Hồ"
        },
        {
          "offset": 95,
          "value": "thành phố Hà Nội"
        }
      ],
      "types": [
        "business_center"
      ]
    }
  ],
  "status": "OK"
}

Then, you can use the id field along with the sessiontoken parameter to get more details about the place (phone, website, opening hours..),

Request:

GET /place?ids=aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc&sessiontoken=576e6543-fbc8-422c-9aad-9884c97df128&format=google

Response

{
  "result": {
    "address_components": [
      {
        "long_name": "Lotte Mall Tây Hồ",
        "short_name": "Lotte Mall Tây Hồ"
      },
      {
        "long_name": "272 Đường Võ Chí Công",
        "short_name": "272 Đường Võ Chí Công"
      },
      {
        "long_name": "phường Phú Thượng",
        "short_name": "Phú Thượng"
      },
      {
        "long_name": "quận Tây Hồ",
        "short_name": "Tây Hồ"
      },
      {
        "long_name": "thành phố Hà Nội",
        "short_name": "Hà Nội"
      }
    ],
    "formatted_address": "Lotte Mall Tây Hồ, 272 Đường Võ Chí Công, phường Phú Thượng, quận Tây Hồ, thành phố Hà Nội",
    "geometry": {
      "location": {
        "lat": 21.075951,
        "lng": 105.812662
      },
      "viewport": null
    },
    "name": "Lotte Mall Tây Hồ",
    "place_id": "aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc",
    "types": [
      "business_center"
    ],
    "url": "https://openmap.vn/place/aQA0KHmLGXVtbpFgpMqFfA0OjpRAAVFgTGaOYDTSgKXVbpiV-A6xZXkuPZgc"
  },
  "status": "OK"
}