Using Spatial Nodes
|
The spatial node is supported in Verizon Connect® Flows™ version 2.2 or later. |
With the spatial node you can access a range of geospatial types, functions, remote services, and data. Currently supported methods are defined below.
To edit the spatial node, double-click on the node in the Flow Editor. The Edit spatial node dialog box opens.
You can edit the following fields:
| • | Name - Enter a unique name for this spatial flows node. |
| • | Config - Click the edit icon  to configure your authentication details. |
| • | Method - Select one of the spatial methods described below. |
| • | Parameters - Enter the parameters that are relevant for the selected method. |
Configuring Authentication Details
To use the spatial node you must authenticate with the server. Generally this is done, using your TDE authentication credentials.
If you have GeoStream credentials you can enter these manually.
To configure your authentication details:
| 1. | Open the Edit spatial node dialog box. |
| 2. | Click on the edit icon in the same line as the Config field. |
| 3. | Under Settings, select "Obtain from TDE" or "Enter manually". |
| 4. | To obtain authentication details from TDE, make sure that you have set up you TDE authentication credentials and enter these into the relevant fields. To enter your authentication details manually, enter the details directly into the relevant fields. |
This method allows you to pass in an address and latitude/longitute coordinates for a location, and it adjusts the location so that it is on the correct side of the street and the appropriate distance away from the street. The method returns the corrected coordinates for the location and the level of confidence that the input and output locations match.
Input Parameters
The getCorrectedLocation method requires both of the following two input parameters:
| • | Location - The location to correct, as latitude/longitude coordinates. Into the Location field within the Edit spatial node dialog box either enter the coordinates directly, or enter the name of the message object you want to process (for example msg.location). The message object you pass to it can either contain a string (for example "-43.52327,172.62985") or a JSON object with lat and lon properties (for example { lat: '-43.52327', lon: '172.62985' } ). |
| • | Address - The address of the location to correct. Into the Address field within the Edit spatial node dialog box either enter the address directly, or enter the name of the message object you want to process (for example msg.address). The message object you pass to it can either contain a string (for example "104 Victoria St, ...") or a JSON object with streetNumber and streetName properties (for example { streetNumber: '104', streetName: 'Victoria Street' } ). |
|
If you are passing a string as input, ensure that you include the properties in the correct order.
|
Output Parameters
The method outputs the following parameters as part of a JSON object:
| • | location: The corrected location, on the appropriate side of the road and with the appropriate distance away from the road. Provided as a JSON object with independent properties for latitude, longitude and z-level (which is the relative height of the coordinates). |
| • | intersection: The point on the street that is closest to the corrected location, as a JSON object with independent properties for latitude, longitude and z-level. |
| • | confidenceLevel: The confidence level that the input and output locations match, as a string with one of the following values: |
|
| • | failureReason: If no matching location is found, location and intersection are both null, confidenceLevel is "None", and the reason for the failure is given within this parameter as a string. |
A possible output JSON object might look like this:
{
"location": {
"lat": -43.52327,
"lon": 172.629851,
"z": 0
},
"intersection": {
"lat": -43.52329,
"lon": 172.629796,
"z": 0
},
"confidenceLevel": "High",
"failureReason": ""
}
This method allows you to geocode an address for a given query string. The method returns locations matching the query, including latitude, longitude, and other relevant properties.
Input Parameters
The geocode method requires the following input parameters:
| • | Searches - An array of JSON objects that contain a required query string and optionally any of the other input parameters listed here (form, matchTypes, countries, locationHint, timeout, or limit). If an input parameter is supplied as part of the searches object and also as a separate input parameter, the value inside the searches object is used for the particular search. If Form is "full", the query is treated as complete. If Form is "prefix" you can provide the first 3 or more letters of the query string. Into the Searches field within the Edit spatial node dialog box enter the name of the message object you want to process (for example msg.payload.searches). The message object you pass to it must contain an array of JSON objects with a query property and optionally one or more of the other input parameters. For example: { "searches": [ { "query": "20 Enterprise", "countries": ["USA"], "locationHint": "-43.52327,172.62985" "matchTypes": "Street" }, { "query": "Toronto" } ] } |
| • | Form - The type of query provided. The value can be either "prefix" or "full". "Prefix" queries should be used for cases where users get results as they type. "Full" queries provide superior results to "prefix" queries when geocoding queries that are complete. The default value is "prefix" (if not provided). Into the Form field within the Edit spatial node dialog box either enter the type of query directly, or enter the name of the message object you want to process (for example msg.payload.form). The message object you pass to it must contain the appropriate string (for example "full"). |
| • | Match Types - The types of match to return, as a comma separated list. The values can be: |
|
In the Edit spatial node dialog box > Search Types field either enter the search types directly, or enter the name of the message object you want to process (for example msg.payload.searchTypes). The message object you pass to it can either contain a string, with a comma separating multiple search types (for example "Street,Region"), or an array of search type strings (for example [ 'Street', 'Region' ]).
| • | Countries - The countries to search in, as a comma separated list. Use country names from the TDE Country Enumeration. When Form is "full", exactly one country is required. When Form is "prefix", multiple countries can be provided, or the field can be omitted. In the latter case all countries that are available for the configured credentials are searched. Note, however, that search performance is inversely proportional to the number of countries searched. Into the Countries field within the Edit spatial node dialog box either enter the countries directly, or enter the name of the message object you want to process (for example msg.payload.countries). The message object you pass to it can either contain a string, with a comma separating multiple countries (for example "USA,Canada"), or an array of country strings (for example [ 'USA', 'Canada' ]). |
| • | Location Hint - A string containing latitude and longitude coordinates. Matches are biased towards locations that are near the provided coordinates. This parameter is optional. Into the Location Hint field within the Edit spatial node dialog box either enter the coordinates directly, or enter the name of the message object you want to process (for example msg.payload.locationHint). The message object you pass to it can either contain a string (for example "-43.52327,172.62985") or a JSON object with lat and lon properties (for example { lat: '-43.52327', lon: '172.62985' } ). |
| • | Timeout - The maximum time (in milliseconds) to search matches for, before terminating prematurely. The default value is "no timeout". This parameter is optional. Into the Timeout field within the Edit spatial node dialog box either enter the timeout value directly, or enter the name of the message object you want to process (for example msg.payload.timeout). The message object you pass to it must contain the appropriate number as a string (for example "30000"). |
| • | Limit - The maximum number of suggested location matches. The default value is 5 (if not provided) and the maximum value is 100. Into the Limit field within the Edit spatial node dialog box either enter the limit value directly, or enter the name of the message object you want to process (for example msg.payload.limit). The message object you pass to it must contain the appropriate number as a string (for example "10"). |
A possible input JSON object might look like this:
{
"searches": [
{
"query": "Floor 4 104 Victoria St, Christchurch",
"form": "prefix",
"matchTypes": [
"Street",
"Region",
"LatLon"
],
"countries": [
"NewZealand"
],
"locationHint": "-43.523265,172.629855",
"timeout": "200",
"limit": "1"
},{
"query": "Toronto"
}
],
"form": "prefix",
"matchTypes": [
"Street",
"Region",
"LatLon"
],
"countries": [
"USA",
"Canada"
],
"timeout": "200",
"limit": "2"
}
Output Parameters
The method outputs some or all of the following parameters as part of a JSON object:
| • | matches: An array of matches objects, which are described below. |
| • | status: One of the following status codes: |
|
A match JSON object can contain the following keys:
location |
This is the location where the queried address was found. For street matches, the location is slightly offset from the street. A LatLon object, consisting of a lat, lon, and z value. |
intersection |
For street matches, this is the point where the matched location intersects with the street network. For other matches, this is equal to the location. A LatLon object, consisting of a lat, lon, and z value. |
boundingBox |
This is the area where the queried address has been found in, for region and postcode matches. A BoundingBox object, consisting of LatLon objects for the most south-western point (bottomLeft) and the most north-eastern point (topRight) of an area. |
matchType |
The type of match. This can be Street, Region, PostCode, or LatLon. |
units |
A list of unit level information for the matched address. This is an array of JSON objects, containing a type and a name (number or identifier). For example: [ { "type": "Apartment", "name": "1a" }, { "type": "Building", "name": "2" } ] |
streetNumber |
For street matches, this is the street number. For example "5" or "20a". |
streetName |
For street matches, this is the name of the street. |
regions |
A list of regions in increasing order of size. A Regions object, consisting of a name (for example "Aliso Viejo") and a level (for example "0" for a city or "1" for a county). City always has a level of 0. Other region levels are dependent on the country, but are used consistently within the same country. |
postcode |
The post (or ZIP) code for the matched address. This is returned for postcode matches and for some street matches. |
country |
The name of the country where the matched address is located. For example "USA". |
matchQuality |
A value between 0 and 1 that indicates how closely the query matches the address found. It does not indicate the probability that the address found is the correct location. |
formattedAddress |
A one-line address string formatted using the local address format. The formatted address does not include the country name. |
|
If an error occurs, the results object contains only an error property with an error message. For example: { "error": "Expected search to contain query" } |
A possible output JSON object might look like this:
{
"results": [
{
"status": "SearchCompleted",
"matches": [
{
"units": [
{
"type": "Floor",
"name": "4"
}
],
"streetNumber": "104",
"streetName": "Victoria St",
"regions": [
{
"name": "Christchurch Central",
"level": -1
},
{
"name": "Christchurch",
"level": 0
},
{
"name": "Christchurch City",
"level": 1
},
{
"name": "Canterbury",
"level": 2
}
],
"postcode": "8013",
"country": "New Zealand",
"matchQuality": 0.9549549549549551,
"matchType": "Street",
"formattedAddress": "Floor 4, 104 Victoria St, Christchurch Central,
Christchurch, Canterbury, 8013, New Zealand",
"location": {
"lat": -43.523265,
"lon": 172.629855,
"z": 0
},
"intersection": {
"lat": -43.523292,
"lon": 172.6298,
"z": 0
}
}
]
},
{
"status": "TooManyMatches",
"matches": [
{
"regions": [
{
"name": "Toronto",
"level": 0
},
{
"name": "Toronto",
"level": 1
},
{
"name": "Ontario",
"level": 2
}
],
"country": "Canada",
"matchQuality": 0.971042471042471,
"matchType": "Region",
"formattedAddress": "Toronto, Ontario, Canada",
"location": {
"lat": 43.64869,
"lon": -79.38544,
"z": 0
},
"intersection": {
"lat": 43.64869,
"lon": -79.38544,
"z": 0
},
"boundingBox": {
"bottomLeft": {
"lat": 43.58647,
"lon": -79.63926,
"z": 0
},
"topRight": {
"lat": 43.85544,
"lon": -79.11889,
"z": 0
}
}
},
{
"regions": [
{
"name": "Toronto",
"level": 0
},
{
"name": "Jefferson",
"level": 1
},
{
"name": "Ohio",
"level": 2
}
],
"country": "USA",
"matchQuality": 0.9219992050874404,
"matchType": "Region",
"formattedAddress": "Toronto, Jefferson, Ohio, USA",
"location": {
"lat": 40.46095,
"lon": -80.606439,
"z": 0
},
"intersection": {
"lat": 40.46095,
"lon": -80.606439,
"z": 0
},
"boundingBox": {
"bottomLeft": {
"lat": 40.40993,
"lon": -80.74133,
"z": 0
},
"topRight": {
"lat": 40.57038,
"lon": -80.59774,
"z": 0
}
}
}
]
}
]
}
Previous
Next
Print