v2 > Lookups > LocationCitiesLookup

Search available location cities that can be used for location feature properties like APPLICABLE_CITY. The search result is organized in pages.

  • URL

    /connect/v2/locations/cities/search

  • Method:

    POST

  • URL Params

    none

  • Request :

Field Type Required Description Domain of value
locale string Yes An Origin supported locale 'de', 'es_MX', 'en', 'fr' or 'zh_CN'
pageNumber number Yes The page number the search result will start from Positive integer greater than 0
pageSize number Yes The maximum number of result by page Integer between 1 and 100
searchCriteria[] array of object Yes The list of search criteria SearchCriteria object array
searchCriteria[].name string Yes A criterion code supported by the search See the reference
searchCriteria[].value string Yes The value to search See the reference

Sample Request (KEYWORD)

This sample request could be translated as : "Search cities matching the keyword 'St. Johns' starting from page 1 with 100 results by page."

{
  "locale": "en",
  "pageNumber": "1",
  "pageSize": "100",
  "searchCriteria": [
    {
      "name": "KEYWORD",
      "value": "St. Johns"
    }
  ]
}

Sample Request (ORIGINID)

This sample request could be translated as : "Search the city with ORIGINID value of b8315bb8-6ced-4708-902b-962055b21e51 starting from page 1 with 100 results by page."

{
  "locale": "en",
  "pageNumber": "1",
  "pageSize": "100",
  "searchCriteria": [
    {
      "name": "ORIGINID",
      "value": "b8315bb8-6ced-4708-902b-962055b21e51"
    }
  ]
}
  • Response :
Field Type Presence Description Domain of value
status object Always The execution status A status object
status.state string Always The state of execution 'SUCCESS' or 'ERROR'
status.code string On error The general error code and message See Errors reference
status.messages[] array of string On error List of error causes A validation message or other causes
result object On success The execution result A result object
result.entityType string On success The type of entity this result is about 'LOCATION_CITY'
result.searchInfo object On success Informations about the search result pages A searchInfo object
result.searchInfo.numberOfElements object On success The total number of elements found A positive integer
result.searchInfo.numberOfPages object On success The total number of pages NumberOfElements / pageSize
result.data[] array of object On success The actual search result : a list of location cities Array of location city object
result.data[].city string On success The city name in the requested locale Any string
result.data[].region string On success The region name in the requested locale Any string
result.data[].country string On success The country name in the requested locale Any string
result.data[].cityDetails object On success Detailed information about the city A cityDetails object
result.data[].cityDetails.originId string On success The city unique origin ID A UUID
result.data[].cityDetails.name string On success The city canonical name Any string
result.data[].regionDetails object On success Detailed information about the region A regionDetails object
result.data[].regionDetails.name string On success The region canonical name Any string
result.data[].countryDetails object On success Detailed information about the country A countryDetails object
result.data[].countryDetails.name string On success The country canonical name Any string
connectRequest object Always The exact request sent that produced this response A LocationCitiesLookup request

Sample Response (Success - KEYWORD)

  • HTTP Code : 200
{
  "status": {
    "state": "SUCCESS"
  },
  "result": {
    "entityType": "LOCATION_CITY",
    "searchInfo": {
      "numberOfElements": "3",
      "numberOfPages": "1"
    },
    "data": [
      {
        "city": "St. John's",
        "region": "Newfoundland and Labrador",
        "country": "Canada",
        "cityDetails": {
          "originId": "e13619ed-338f-46a7-9929-d9667fbb4131",
          "name": "St. John's"
        },
        "regionDetails": {
          "name": "Newfoundland and Labrador"
        },
        "countryDetails": {
          "name": "Canada"
        }
      },
      {
        "city": "Fort St. John",
        "region": "British Columbia",
        "country": "Canada",
        "cityDetails": {
          "originId": "976c54ca-7ade-4924-9a5f-817bd171dedd",
          "name": "Fort St. John"
        },
        "regionDetails": {
          "name": "British Columbia"
        },
        "countryDetails": {
          "name": "Canada"
        }
      },
      {
        "city": "St Johnsbury",
        "region": "Vermont",
        "country": "United States",
        "cityDetails": {
          "originId": "0ef6fb5c-024d-478f-a637-a925e35c67de",
          "name": "St Johnsbury"
        },
        "regionDetails": {
          "name": "Vermont"
        },
        "countryDetails": {
          "name": "United States"
        }
      }
    ]
  },
  "connectRequest": {
    "locale": "en",
    "pageNumber": "1",
    "pageSize": "100",
    "searchCriteria": [
      {
        "name": "KEYWORD",
        "value": "St. Johns"
      }
    ]
  }
}

Sample Response (Success - ORIGINID)

  • HTTP Code : 200
{
  "status": {
    "state": "SUCCESS"
  },
  "result": {
    "entityType": "LOCATION_CITY",
    "searchInfo": {
      "numberOfElements": "1",
      "numberOfPages": "1"
    },
    "data": [
      {
        "city": "Athens",
        "region": "Attica",
        "country": "Greece",
        "cityDetails": {
          "originId": "b8315bb8-6ced-4708-902b-962055b21e51",
          "name": "Athens"
        },
        "regionDetails": {
          "name": "Attica"
        },
        "countryDetails": {
          "name": "Greece"
        }
      }
    ]
  },
  "connectRequest": {
    "locale": "en",
    "pageNumber": "1",
    "pageSize": "100",
    "searchCriteria": [
      {
        "name": "ORIGINID",
        "value": "b8315bb8-6ced-4708-902b-962055b21e51"
      }
    ]
  }
}

Sample Response (Error)

  • HTTP Code : 400, 500
{
  "status": {
    "state": "ERROR",
    "code": "CE00001 - Connect request failed validation. Refer to provided messages for details.",
    "messages": [
      "Request has invalid value '0' for field pageNumber. Allowed value(s) : [positive integer not equal zero]",
      "searchCriteria[0] has invalid value 'CITY' for field name. Allowed value(s) : [KEYWORD,ORIGINID]"
    ]
  },
  "connectRequest": {
    "locale": "en",
    "pageNumber": "0",
    "pageSize": "1",
    "searchCriteria": [
      {
        "name": "CITY",
        "value": "Athens"
      }
    ]
  }
}

results matching ""

    No results matching ""