Suggestions

Request

The Suggestions API is used to show possible matches for an address or Points of Interest (POI).

GET https://apis.location.studio/geo/v2/suggestions/json

Required Parameters

api_key

String

Your Location Studio API Key

search_center

String

The latitude and longitude for the center of search. The country will be determined by the search_center for geocoding. The latitude must be in the range of -90.0 to 90.0 and longitude must be in the range of -180.0 to 180.0 otherwise HTTP Error Code 400 for Bad Request will result.

query

String

Search term entered by the user.

Optional Parameters

user_position

String

The latitude and longitude for the user’s position. This is used only for calculating distance in meters for each result.

The latitude must be in the range of -90.0 to 90.0 and longitude must be in the range of -180.0 to 180.0 otherwise HTTP Error Code 400 for Bad Request will result.

iterator_length

Integer

Number of results to return. The default value is 10.

Response

Description

When the service returns results from a suggestions request, it places them within a suggest array. The XML response consists of zero or more <lws:suggest> elements that have the following properties:

  • brand - array indicating the brands associated with the place.

    • id - brand id

    • name - brand name

  • categories - is an array indicating the categories of the place. For example, "Grocery Stores".

    • code - category code

    • name - category name

    • parent_category

      • code - category code

      • name - category name

  • distance - distance from the search_center in meters. Alternatively, the distance will be calculated from the user_position if it is provided.

  • line1 - First line of text to be displayed for the suggestion. For POI results, this will be the name of the place. For address results this will be the house number and street name. For category/brand results, this will be the name of the category/brand. For city/state/zip/country results this will contain city/state/zip/country formatted for the country of result.

  • line2 - Second line of text to be displayed for the suggestion, For POI results this will be the house number and street name of the POI. For addresses this will be the city, state, postal and country. Not used for category/brand and city/state/zip/country results.

  • line3 - Third line of text to be displayed for this suggestion. For POI results this will contain city, state, postal & country. Not used for Address, category/brand and city/state/zip/country.

  • search_filter - is an opaque value that can be used in a subsequent Search API request for this match.

Toggle JSON Response

{
  "iterator_status" : "MTA=",
  "exhausted" : "y",
  "suggests" : [ {
    "search_filter" : "UUc3dVVwWnF0NWdWcytCMHBGVEVQSnBiV216SVgvRzVGWFRUME9KaVlac2hJQjJ6dnNJY0gyTFdDdzBHOExiMEtLMkxQaU1razZjdVB0K2pSbzNHUmptU0FqcjhOZ1FDMFNIZkM2ODlaUU9lbzJDUlk5VERPMU9Hc0l5NTdIV0NleFk4eVhUa2JleWJaL0FPQnpFV2hETWhQbmlwemh2ZlhJcmNnZHpzb0xVPQ==",
    "line1" : "Grocery Stores"
  }, {
    "search_filter" : "a05ici81dnczV2lFaVBOWHZTUUZPY09JeUlXRGhNUEUxbWJTa2orZWtiaktiMVFvR25DNFBIbEZoVmtwV1ZjZEQ1WXFkVFlSMjhObjFwbmYyRjJwMWZhemRsdW9LYUQ5MGJhaGR2TlpmeWdoSGtEQkdvbGZYczhQRDNkUUppUDk0bnlxemFPWERXbnVTRCtaWDJTeXMxcG5melFhMEliSU80S213aGV0a2pvPQ==",
    "line1" : "Grocery Outlet"
  }, {
    "line3" : "Laguna Niguel, CA 92677",
    "search_filter" : "cDlhRTcyY1JDQUJnS1d3SnE4L1RvNmdpeGllMWJoWnlsbnJjaTBJN0NMVXd4TVhSekcyKzVLNElWNGUrSk54Y2xoTjRFRDZmczlqbDlNSzBtTGJ5bnJxVldvVXMvSGs5OS9aM2NaU2JKZ3lyRElLRE5EeEt6R1JmRXVFMjN5L2w3dWFic0FkMmdKL0I3WEpEdkhxVE54cW1PSjJPcTlxbk1kcitkcUoyTER0VkI4REtITnRNRjB4aW41MjlieGk2VzNOekxTb2RlUW4vMlJzMjlYUVcrT3h2QVp6VHhIWWNMY0Q0OTZFRUkvRHBIeU4rR0lIaVVuZUg5K2sxR3ppczFiT0pZak15MU1NPQ==",
    "line1" : "Ralphs Grocery Co Store 738",
    "line2" : "28231 Crown Valley Pkwy",
    "distance" : 3929.448,
    "categories" : [ {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    } ]
  }, {
    "line3" : "Laguna Hills, CA 92653",
    "search_filter" : "SFIyc0NXUEZrSExWbW1jQTIxVWdGbnhWbnd5TzdyQW9CMkZtRGF6YVBRZmcwTWUvcS91ajNoUnpqcFJsZjZaQlp2ME9TOHlWcmJwdVd6czV2SHgxKy8zRTNBYVkzdkRMQVRzSHVnN29jVWhjZDBSMUNYTFFqUzkrekJpa0U2ODNGeUQ5Z2Uwbm5LS0IvTEpMOU1KcFpHRUpldlpVdDNIVk13K3lHS2NWaEdkNlgyM2dieUd5Z1V1cHdCQi9QNGpnSnA2cnJyVUFrV0xJeHpjRnNtT2xKOXRybTNvbHcvSUpRelY0RTVjWmNEUUx6cTNtbFRVbFQ3enF1eW9MZUJXaW1PZk5wNUR4S2NmQ0JLZU5GZElPc0E9PQ==",
    "line1" : "Ralphs Grocery Co Store 223",
    "line2" : "25539 Paseo de Valencia",
    "distance" : 4563.9653,
    "categories" : [ {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Florists",
      "code" : "AKL",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    } ]
  }, {
    "line3" : "Laguna Hills, CA 92653",
    "search_filter" : "YkJsSi9qL3Y0VlVSTTh0UnFQRUlwMjQwSG9USDRIR01BT1BHUEN1cHRXWEN6L1dXMGxKbVcrSmx2SlpBWkhqbkpVMVMycWtWa0dWa0x0c1hjOTZhNWRiM29wYVRJZTgzbXF0anFDSy8wMmRYVnFDMit3NUNyYjBXcjEyT0srZnIyMHNFNFl2VkZrOHJNeWt5WDIvUTcySjFLNlZPbXhLME5xaUpvNHF5Z2x0ZkhJNjZxdDBMQmpaYTk2c3liM0ZOaG1IOExvSTI4dFI3dEtrM1RjMVQxekFUNmpDTXZtUjNaL3dVdzZNM2FDM1dJSk9MaHVycVd3PT0=",
    "line1" : "Mediterranean Grocery",
    "line2" : "25381 Alicia Pkwy",
    "distance" : 4809.9995,
    "categories" : [ {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    } ]
  }, {
    "line3" : "Laguna Beach, CA 92651",
    "search_filter" : "c3ZOMEM3WSsySnk5Z045Z3VHbGxsQUtFWmNWdllvcFRreGszZUkyRkgwcFlFMlBLMWMyQkwzQ2Y2Tml5cUVWV3dUc2lLNXo1NXg2dytRa0lhT1FtOWtGdTg5TWR3NDJGUGQvS1I4eHBtTS9Cb1BQQW1qZ3VpSHJPdTZkOVdpNGFNaE9ZZ1BWWXFkdFVDOHhibEtzWE9OSWRpSVNRTzA4eWU2S3FUcnNKMUZlU1YySkZKZFoxU1VIQzBQVWNTQ29uRTQ4V2pRTDVMTk1pOHAwUDdLeDlacHRPNjdLYUF6aEU=",
    "line1" : "Ralphs",
    "line2" : "700 S Coast Hwy",
    "distance" : 5212.8633,
    "categories" : [ {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    } ]
  }, {
    "line3" : "Lake Forest, CA 92630",
    "search_filter" : "Uk9sdk9jSWl5bTFzeUVNcEdFWEtpNWdwdXJNZW50NTljS1BBc2lDM3hFRGM4eFR1VWZFTEl0dCtWTkJMR2x3SUhVd0JIQ0xzUGxrKytYTmZWaEZ6YXZJK2RiM3JadGpLYkY2WktaWXVRMnBiZklYWW10Rkh3eDE0SUJoVVNzdmtISGoxdVA2aEFPWktDdTZhbCs0djRlcW81ZG1ORjdnMmRuY0s5cEFKZ3N6NXpCR1BwWkJoLzhsWE1SWTZqU2FwV0pMcW9SR3BkRlRJMi95bllUaEgxb096WWRXUkE5Q01UNWgzcjRVQW1vWT0=",
    "line1" : "Ralph's Grocery Pharmacy",
    "line2" : "23716 El Toro Rd",
    "distance" : 6921.5664,
    "categories" : [ {
      "name" : "Pharmacies",
      "code" : "ANC",
      "parent_category" : {
        "code" : "AN",
        "name" : "Health Care"
      }
    } ]
  }, {
    "line3" : "Lake Forest, CA 92630",
    "search_filter" : "N2hBdVpZb3RDMUJoZm5oUkVCRGNMSk8vUDlSbGxDczBPaXpFeG5FMUxvWEtVRFF3cHAvM3FrdjNPd09UOTVxeFdmdnZBcHdVcG43VlE3WEM5VnV4Ry9xR0t0ak8zMm1PWlFmQ3BJSnNZUEF1WVNEZkJ4VTloRTVwOFk0VG0yaUpoeG96ejNHWHpBRlBaa2RwRHBRWUxVekRYWTA2OUdrWTI4Ull3Z2N3U0VHaFJJb2YxNXZCcjRpdC9xZkFOc253RFZmTCtNSzNoZkxEc05mZnlESzRPVndqZ0doVEJaZ1E3dGZiMWo5Sk9jLzVDY0ZpWUcxd1ZIaFh5MWJvc0Q2Nnp2alVEaE1TQXVVPQ==",
    "line1" : "Nina's Indian Groceries",
    "line2" : "23542 El Toro Rd",
    "distance" : 7402.6924,
    "categories" : [ {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Indian Restaurants",
      "code" : "AEG",
      "parent_category" : {
        "code" : "AE",
        "name" : "Restaurants"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    } ]
  }, {
    "line3" : "Newport Beach, CA 92660",
    "search_filter" : "SnI5OWZTQ1NjNFBhdDIzT29KbVFVd0ZrMys0ek0ydFdGblBTQ0FXVHcvVFJDL0JpakVWUlhsY2FIY0RmamRrRS9wd1dFTTJjZUExcXFXNTdmODdzVDBSWmtDRE9Lc0ZaZ3RrK2JTT3VUYkx4cFFyTGRzSHloRU9wR2J3bEVvbFBvREFYMUduZ1lJZXJyQm9uckQvVXAwMldmQnFubU9mdkkxMU9jNklhOXEwRjNrdXVhZmRuYlBGRVllalN5Y2RCSWR5YkNSZzZacisrLzhOM0t5dCtBcU9OR1VKRFJLeWJWN3U5OGkxQUc0UWRvdWlJTmUzNnVIUDVmem5Yejd4bU9ZME5YSzdvUnZDOStXSjd1VDBoNDAxVWs3Y1Z5TmkvRW9mSnRJUTNGeDA9",
    "line1" : "Ralphs",
    "line2" : "1150 Irvine Ave",
    "distance" : 18307.008,
    "categories" : [ {
      "name" : "Malls & Shopping Centers",
      "code" : "AKH",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Florists",
      "code" : "AKL",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Shopping/Retail",
      "code" : "AK",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "ATMs",
      "code" : "AAA",
      "parent_category" : {
        "code" : "AA",
        "name" : "Banks & ATMs"
      }
    } ]
  }, {
    "line3" : "San Clemente, CA 92672",
    "search_filter" : "bHdFL013QzgrV0RuejFFajFveHRVYk9YVUpNbW1xK0FTRU5Sc0QvdmdZWWVqeUJ3R0c2V3o5L2ZIYkdQVUdINGVENTNPMGdxQjBGYkZFOWorZEIvL0trelZHNC9wTTdJRVJkY1Q0bVlhSWoweTBmeUMyY2lCV2x3R0NZMXk3azY0alVvZ3B1YUNvcWZTNm84VFgrVGdjZjJBZXNZc3FaNUJXVDFkazlVQnVJN1EvOC9yT3dIb29GdnU1aDdZaFRlM1ovbW9hM2w2S29vak1sWnAyOWNFSFdGYTFkbkpCWVFoZTZiaWhJQkNJZUwrYVVUK1BPZDMvaHJubEU2d2F3NC9Wc2hjaG92SFNjTzJ1TW9Ea3N2d1E9PQ==",
    "line1" : "Ralphs Grocery Co Store 221",
    "line2" : "903 S El Camino Real",
    "distance" : 18830.482,
    "categories" : [ {
      "name" : "Grocery Stores",
      "code" : "AKD",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "Food Markets",
      "code" : "AKJ",
      "parent_category" : {
        "code" : "AK",
        "name" : "Shopping/Retail"
      }
    }, {
      "name" : "ATMs",
      "code" : "AAA",
      "parent_category" : {
        "code" : "AA",
        "name" : "Banks & ATMs"
      }
    } ]
  } ]
}

Test