Autocomplete API

Suggest places as the user types. Returns a list of matching locations with coordinates and identifiers.

Comparison with Search API:

Autocomplete: 3-4 lightweight suggestions, ideal for input fields
Search: 20 detailed results

I. Endpoint

GET https://api.pisomap.tech/api/maps/autocomplete

II. Headers

Name	Value	Required
`x-api-key`	Your API key	Yes

III. Query Parameters

Name	Type	Required	Default	Description
`q`	string	Yes	—	Place name or address to search for
`lat`	number	Yes	—	Your current latitude
`lng`	number	Yes	—	Your current longitude

IV. Example

Your current location: Saigon Opera House (10.77682358167437, 106.70313930948461)

Search: "starbucks"

curl "https://api.pisomap.tech/api/maps/autocomplete?q=starbucks&lat=10.77682358167437&lng=106.70313930948461" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "suggestions": [
    {
      "data_id": "0x31752fd5abbc268f:0x209a24f81b1461d4",
      "value": "Starbucks Waterbus Thủ Thiêm, Thủ Thiêm, An Khánh, Hồ Chí Minh",
      "subtext": "Thủ Thiêm, An Khánh, Hồ Chí Minh",
      "latitude": 10.776872,
      "longitude": 106.7103264,
      "link_search_value": "https://api.pisomap.tech/api/maps/search?q=Starbucks%20Waterbus%20Th%E1%BB%A7%20Thi%C3%AAm%2C%20Th%E1%BB%A7%20Thi%C3%AAm%2C%20An%20Kh%C3%A1nh%2C%20H%E1%BB%93%20Ch%C3%AD%20Minh&lat=10,776872&lng=106,7103264",
      "link_place_detail": "https://api.pisomap.tech/api/maps/place?data_id=0x31752fd5abbc268f%3A0x209a24f81b1461d4",
      "link_google_maps": "https://www.google.com/maps/place/?cid=0x31752fd5abbc268f%3A0x209a24f81b1461d4",
      "link_docs": "https://docs.pisomap.tech/en/api-docs/autocomplete"
    },
    {
      "data_id": "0x31752f8e69fb1817:0x99b4de4074cd2e5a",
      "value": "Starbucks Nguyễn Thị Minh Khai, Đường Nguyễn Thị Minh Khai, Xuân Hòa, Hồ Chí Minh",
      "subtext": "Đường Nguyễn Thị Minh Khai, Xuân Hòa, Hồ Chí Minh",
      "latitude": 10.7820814,
      "longitude": 106.6971085,
      "link_search_value": "https://api.pisomap.tech/api/maps/search?q=Starbucks%20Nguy%E1%BB%85n%20Th%E1%BB%8B%20Minh%20Khai%2C%20%C4%90%C6%B0%E1%BB%9Dng%20Nguy%E1%BB%85n%20Th%E1%BB%8B%20Minh%20Khai%2C%20Xu%C3%A2n%20H%C3%B2a%2C%20H%E1%BB%93%20Ch%C3%AD%20Minh&lat=10,7820814&lng=106,6971085",
      "link_place_detail": "https://api.pisomap.tech/api/maps/place?data_id=0x31752f8e69fb1817%3A0x99b4de4074cd2e5a",
      "link_google_maps": "https://www.google.com/maps/place/?cid=0x31752f8e69fb1817%3A0x99b4de4074cd2e5a",
      "link_docs": "https://docs.pisomap.tech/en/api-docs/autocomplete"
    },
    {
      "data_id": "0x31752f46c63d2867:0x8ce11d6317e10879",
      "value": "Starbucks Nguyễn Huệ, Nguyễn Huệ, Sài Gòn, Hồ Chí Minh",
      "subtext": "Nguyễn Huệ, Sài Gòn, Hồ Chí Minh",
      "latitude": 10.7734074,
      "longitude": 106.7038845,
      "link_search_value": "https://api.pisomap.tech/api/maps/search?q=Starbucks%20Nguy%E1%BB%85n%20Hu%E1%BB%87%2C%20Nguy%C3%AA%CC%83n%20Hu%C3%AA%CC%A3%2C%20S%C3%A0i%20G%C3%B2n%2C%20H%E1%BB%93%20Ch%C3%AD%20Minh&lat=10,7734074&lng=106,7038845",
      "link_place_detail": "https://api.pisomap.tech/api/maps/place?data_id=0x31752f46c63d2867%3A0x8ce11d6317e10879",
      "link_google_maps": "https://www.google.com/maps/place/?cid=0x31752f46c63d2867%3A0x8ce11d6317e10879",
      "link_docs": "https://docs.pisomap.tech/en/api-docs/autocomplete"
    },
    {
      "data_id": "0x31752f0a2323cb43:0xe43cbaeb2de16988",
      "value": "Starbucks Waterbus Bach Dang, Đường Tôn Đức Thắng, Sài Gòn, Hồ Chí Minh",
      "subtext": "Đường Tôn Đức Thắng, Sài Gòn, Hồ Chí Minh",
      "latitude": 10.775133,
      "longitude": 106.7070959,
      "link_search_value": "https://api.pisomap.tech/api/maps/search?q=Starbucks%20Waterbus%20Bach%20Dang%2C%20%C4%90%C6%B0%E1%BB%9Dng%20T%C3%B4n%20%C4%90%E1%BB%A9c%20Th%E1%BA%AFng%2C%20S%C3%A0i%20G%C3%B2n%2C%20H%E1%BB%93%20Ch%C3%AD%20Minh&lat=10,775133&lng=106,7070959",
      "link_place_detail": "https://api.pisomap.tech/api/maps/place?data_id=0x31752f0a2323cb43%3A0xe43cbaeb2de16988",
      "link_google_maps": "https://www.google.com/maps/place/?cid=0x31752f0a2323cb43%3A0xe43cbaeb2de16988",
      "link_docs": "https://docs.pisomap.tech/en/api-docs/autocomplete"
    }
  ]
}

V. Response Fields

Field	Type	Description
`suggestions`	array	List of place suggestions
`data_id`	string	Internal ID used for Place Detail
`value`	string	Display name of the place
`subtext`	string	Address or area description
`latitude`	number	Latitude
`longitude`	number	Longitude
`link_search_value`	string	Link to Search API for this place
`link_place_detail`	string	Link to Place Detail API
`link_google_maps`	string	Link to Google Maps page
`link_docs`	string	Link to API documentation

VI. Errors

Status	Meaning
401	Missing or invalid API key
422	Invalid or missing query parameter
429	Rate limit exceeded
500	Internal server error