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. When the user starts typing a search keyword, your app generates a sessiontoken (UUID v4) and includes it in every Autocomplete API call.
  2. The user can make multiple Autocomplete queries with the same sessiontoken.
  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. Only this session is charged as a single unit.

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