Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Geography (viv.geo)

The Bixby viv.geo library capsule provides a set of concepts and actions that allow your capsule to handle a variety of location-based expressions for training and processing. This includes handling points, geometry regions and shapes, and named localities such as cities, countries, and landmarks.

Models

The viv.geo capsule includes around 100 concepts covering geographical and locality information, as well as a general SearchTerm concept for training purposes. For more information on SearchTerm, read Using SearchTerm.

This is not an exhaustive list, but covers the more common models you might use.

Administrative Divisions

An administrative division is any politically distinct region recognized by international mapping authorities and used in geocoding.

Administrative divisions have country-specific meanings. (See Wikipedia's List of administrative divisions by country.)

CountryDivision
PropertyTypeKindNotes
nameCountryDivisionNamenameRequired
typeAdministrativeDivisionTypeNamename
countryCode2ISOCountryCode2name
countryCode3ISOCountryCode3name

ISOCountryCode2 is the two-character ISO identifier for the country; ISOCountryCode3 is the three-character ISO identifier for the country.

LevelOneDivision

This represents a first-level administrative division, such as a state in the United States, a province in Canada or Korea, and so on.

PropertyTypeKindNotes
nameLevelOneDivisionNamenameRequired
typeAdministrativeDivisionTypeNamename
countryCode2ISOCountryCode2name
countryCode3ISOCountryCode3name
subdivisionCodeISOSubdivisionCodename
countryCountryDivisionstructure
LevelTwoDivision

This represents a second-level administrative division, such as a county or province.

PropertyTypeKindNotes
nameLevelTwoDivisionNamenameRequired
centroidGeoPointstructure
countryCountryDivisionstructure
levelOneLevelOneDivisionstructure
LevelThreeDivision

This represents a third-level administrative division.

PropertyTypeKindNotes
nameLevelThreeDivisionNamenameRequired
countryCountryDivisionstructure
levelOneLevelOneDivisionstructure
levelTwoLevelTwoDivisionstructure
LevelFourDivision

This represents a fourth-level administrative division.

PropertyTypeKindNotes
nameLevelFourDivisionNamenameRequired
countryCountryDivisionstructure
levelOneLevelOneDivisionstructure
levelTwoLevelTwoDivisionstructure
levelThreeLevelThreeDivisionstructure

Points

Points represent specific geographic areas.

GeoPoint

A GeoPoint is a specific point on Earth specified by a latitude and longitude.

PropertyTypeKindNotes
latitudeLatitudedecimalRequired
longitudeLongitudedecimalRequired
currentDistanceCurrentDistancestructure(1)
reverseGeoGeocodedAddresssee Address
timeZonetime.TimeZoneIdtextlazy-sourced
populationDensityPopulationDensitystructurelazy-sourced
userFriendlyNamePlaceNamename

CurrentDistance is the Distance from the user's current location to the GeoPoint. As with other fields in GeoPoint, it is lazily sourced when accessed.

CurrentLocation

This structure extends GeoPoint to be a special case for storing the user's current location. CurrentLocation is marked as transient. The viv.geo capsule includes an instantiation strategy that will set the value of CurrentLocation based on $user.currentLocation.

NamedPoint

A GeoPoint with a name and an address. If you have trained your capsule to take SearchTerm inputs, you will need to provide actions that take NamedPoint concepts as inputs. See Using SearchTerm for more details.

PropertyTypeKindNotes
namePlaceNametext
pointGeoPointstructureRequired
addressAddressstructure
Address
PropertyTypeKindNotes
namePlaceNametext
pointGeoPointstructurerequired
addressAddressstructureoptional

The Address structure concept includes the following properties. Cardinality is min (Optional) max (One) unless noted.

PropertyTypeKindNotes
centroidGeoPointstructurelazy-source
localityLocalitystructure
countryCountryDivisiontext
levelOneLevelOneDivisiontext
levelTwoLevelTwoDivisionNametext
levelThreeLevelThreeDivisionNametext
levelFourLevelFourDivisionNametext
subLocalityOneSubLocalityOneNamestructure
subLocalityTwoSubLocalityTwoNamestructure
subLocalityThreeSubLocalityThreeNamestructure
subLocalityFourSubLocalityFourNamestructure
postalCodePostalCodetext
streetAddressStreetAddresstext
streetAddress2StreetAddress2text 
Note

centroid in Address is lazily sourced when there is sufficient information in other properties to determine a specific GeoPoint.

Locality

A city or town within a geographic region.

PropertyTypeKindNotes
nameLocalityNamenameRequired
centroidGeoPointstructure
typeAdministrativeDivisionTypeNamename
countryCountryDivisionstructure
levelOneLevelOneDivisionstructure
levelTwoLevelTwoDivisionstructure
levelThreeLevelThreeDivisionstructure
levelFourLevelFourDivisionstructure
localityClassLocalityClassenum

LocalityClass has the following possible symbols:

  • CountryCapital
  • LevelOneCapital
  • LevelTwoCapital
  • LevelThreeCapital
  • LevelFourCapital
Neighborhood

A neighborhood in a city, such as "Mission District" (in San Francisco) or "West End" (in London).

PropertyTypeKindNotes
nameNeighborhoodNamenamerequired
centroidGeoPointstructure
Place

A landmark or a business. The phrases "SJC" (an airport code), "Santana Row" (a shopping mall), "Golden Gate Bridge" (a landmark), and "french laundry" (a restaurant) could all be tagged as PlaceName.

PropertyTypeKindNotes
namePlaceNamenamerequired
centroidGeoPointstructure

Other

Distance
PropertyTypeKindNotes
magnitudeDistanceMagnitudedecimalRequired
unitDistanceUnitenumRequired

Possible symbols for DistanceUnit are:

  • Millimeters
  • Centimeters
  • Inches
  • Feet
  • Yards
  • Meters
  • Kilometers
  • Miles
Note

Do not train on the Distance structure concept, but instead train on the two primitives separately. An utterance such as "find restaurants in a 2 mile radius" would tag 2 as DistanceMagnitude and mile as DistanceUnit. (However, if the utterance can be applied more generally, consider using SearchTerm instead.)

PopulationDensity

This will be lazily sourced (computed for your capsule) when accessed.

PropertyTypeKindNotes
densityDensitydecimalRequired
typeDensityTypeenumRequired

Possible symbols for DensityType are:

  • ultra-dense
  • metropolitan-dense
  • metropolitan
  • suburban-dense
  • suburban
  • rural
  • remote
  • unknown
SearchRegion

If you have trained on named points or divisions, you will need to provide actions that take SearchRegion concepts as inputs. See Using SearchRegion for more details.

PropertyTypeKindNotes
searchTypeSearchTypeenumRequired
streetAddressStreetAddresstext
postalLocationPostalLocationtext
countryCountryDivisiontext
levelOneLevelOneDivisiontext
levelTwoLevelTwoDivisiontext
levelThreeLevelThreeDivisiontext
levelFourLevelFourDivisiontext
localityLocalitystructure
subLocalityOneSubLocalityOnestructure(1)
subLocalityTwoSubLocalityTwostructure
subLocalityThreeSubLocalityThreestructure
subLocalityFourSubLocalityFourstructure
localityClassLocalityClassenum
pointRadiusPointRadiusstructure
shapeGeometryWKTtext(2)
  1. A subLocality* is a civil administrative division below the Locality level; these are country/region-specific. A subLocality* contains the same properties as a Locality, with the exception of localityClass.

  2. This is a "well-known text" string representing a vector geometry.

The possible symbols for SearchType are:

  • Country
  • LevelOne
  • LevelTwo
  • LevelThree
  • LevelFour
  • Locality
  • SubLocalityOne
  • SubLocalityTwo
  • SubLocalityThree
  • SublocalityFour
  • PostalLocation
  • PointRadius

Training

The viv.geo capsule includes actions that will use the concepts above such as SearchTerm or Locality as inputs and output more concrete concepts that the actions in your capsule can act on. These actions will guide Bixby in resolving ambiguities such as distinguishing between similarly-named cities, or searching in a specific area to provide your capsule a list of businesses. This lets Bixby do a lot of the work for you: you can train on SearchTerm and provide actions that take NamedPoint concepts as inputs.

Using SearchTerm

The SearchTerm concept allows your capsule to easily search on a variety of geographic types. Utterances such as "SFO", "60 South Market Street", "Mountain View" and "Golden Gate Bridge" can all be trained with SearchTerm.

Your capsule does not have to handle the search action, but instead just needs one or more action that takes a NamedPoint as an input. Data from Here Maps will be used by viv.geo to resolve the SearchTerm into a specific NamedPoint.

As an example, a ridesharing capsule might have a DestinationPoint model that has a role-of NamedPoint. Its FindRideShare action could then include DestinationPoint as one of its inputs:

action (FindRideShare) {
type (Search)
description (A real-time search for available ride shares)

collect {
input (destination) {
type (DestinationPoint)
min (Required) max (One)
default-select {
with-learning
with-rule {
select-first
}
}
}
// ... other inputs to collect ...
}
output (RideShare) {
// The RideShare concept includes a property of type (DestinationPoint)
}
}

This action enables selection learning, along with a fallback selection rule of select-first to default to the first returned option. The ridesharing capsule might have a remote endpoint that includes RideShare as one of its inputs:

endpoints {
action-endpoints {
action-endpoint (BookRideShare) {
accepted-inputs (rideShare, seatCount, estimate, payment)
remote-endpoint ("https://example.com/rideshare/book") {
method (POST)
}
}
}
// ... other endpoints ...
}

Using SearchRegion

If your capsule needs to train on concepts for named points and divisions, you should train on the *Name primitive concepts, not on the structure concepts. For reference, the matching primitives to the structure concepts above are:

  • CountryDivisionName
  • LevelOneDivisionName
  • LevelTwoDivisionName
  • LevelThreeDivisionName
  • LevelFourDivisionName
  • LocalityName
  • NeighborhoodName
  • PlaceName

If you have trained on named points or divisions, you should provide actions that take SearchRegion concepts as inputs. A hypothetical FindBusiness action might include:

action (FindBusiness) {
type (Search)
description (An action that finds businesses matching some search criteria)
collect {
input (searchRegion) {
type (geo.SearchRegion)
min (Required) max (One)
default-select {
with-learning
with-rule {
select-first
}
}
}
// ... other inputs to collect ...
}
output (Business) {
}
}

This action enables selection learning, along with a fallback selection rule of select-first to default to the first returned option. The JavaScript action implementation should accept SearchRegion as one of its inputs.

Note

When possible, you should train on SearchTerm for the most flexibility in handling user utterances. Only train on other viv.geo concepts if you need to specifically restrict utterances to those concepts.

As many of the properties of SearchRegion will be populated by Bixby as possible based on the available data. For instance, if you trained your capsule on Locality, and the utterance value was "San Jose, CA", the returned SearchRegion would have a SearchType set to Locality; the pointRadius would approximate the size of San Jose; divisions would be filled in with appropriate values.