Create Landmark

Last updated
Save as PDF

createLandmark

This web service creates a landmark with the specified primary details. Note that:

The landmark will inherit default values for all type-specific attributes. editAttributes() may be used subsequently to set the type-specific attributes if/as desired.
Creating a landmark causes the system to automatically determine inventory counts for the landmark. Arrival notifications will not be sent for any assets that are determined to be at the landmark.
The list of valid characters are: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789<(+&!$*);-./,%>?:#@='
The landmark's initial geographic location and boundary may be specified in one of several ways as indicated by the defineBoundaryUsing parameter described below.
Regardless of which method that is used, the result will always be that the system understands the landmark in terms of its polygonal boundary (even if it is auto-created). See table below.

void createLandmark(string companyId, string defineBoundaryUsing, Landmark landmark) throws WSException

companyId: (optional) A string, maximum length 10, specifying the unique company identifier where the landmark is to be created.
NOTE: If no companyId is specified, the company of the authorized user making the call will be used.

defineBoundaryUsing: A single character specifying how the system should establish the landmark's geographical location and boundary. Valid values are:

Value	Set Location by:	Additional Info
A	Address and Radius	If set to 'A', the system will require the address and radius to be supplied. (The circle centroid lat/lon and polygon vertices are ignored even if they are supplied.) This method is useful to integrators that have neither lat/lons nor polygonal boundaries for their landmarks. In this case, the address is geocoded into lat/long coordinates which are used to set the circle centroid. And then a default polygonal boundary (a hexagon) is auto-created to fit precisely within the area of the specified radius. Note that a valid range for the radius is .01 thru 5000. Specifying a 0 radius will cause the landmark to inherit the default radius for that landmark type.
C	Circle Centroid Lat/Long and Radius	If set to 'C', the system will require the circle centroid lat/lon and radius to be supplied. And the address is still required as well although not used to set the location. (The polygonal vertices are ignored even if they are supplied.) This method is useful to integrators that simply have a lat/lon location for their landmarks but not their polygonal boundaries. In this case, a default polygonal boundary (a hexagon) is auto-created to fit precisely within the area of the specified radius. Note that a valid range for the radius is .01 thru 5000. Specifying a 0 radius will cause the landmark to inherit the default radius for that landmark type.
V	Polygon Vertices	If set to 'V', the system will require the polygon vertices to be supplied. And the address is still required as well although not used to set the location. (The circle centroid lat/lon and radius are ignored even if they are supplied.) This method is useful to integrators that have polygonal boundaries for their landmarks. In this case, the specified vertices are used to establish the landmark's boundary. Then, its circle centroid lat/lon and associated radius are auto-created by creating the smallest circle possible that completely surrounds the polygon.

Value

Set Location by:

Additional Info

Address and Radius

If set to 'A', the system will require the address and radius to be supplied. (The circle centroid lat/lon and polygon vertices are ignored even if they are supplied.)

This method is useful to integrators that have neither lat/lons nor polygonal boundaries for their landmarks. In this case, the address is geocoded into lat/long coordinates which are used to set the circle centroid. And then a default polygonal boundary (a hexagon) is auto-created to fit precisely within the area of the specified radius.

Note that a valid range for the radius is .01 thru 5000. Specifying a 0 radius will cause the landmark to inherit the default radius for that landmark type.

Circle Centroid Lat/Long and Radius

If set to 'C', the system will require the circle centroid lat/lon and radius to be supplied. And the address is still required as well although not used to set the location. (The polygonal vertices are ignored even if they are supplied.)

This method is useful to integrators that simply have a lat/lon location for their landmarks but not their polygonal boundaries. In this case, a default polygonal boundary (a hexagon) is auto-created to fit precisely within the area of the specified radius.

Note that a valid range for the radius is .01 thru 5000. Specifying a 0 radius will cause the landmark to inherit the default radius for that landmark type.

Polygon Vertices

If set to 'V', the system will require the polygon vertices to be supplied. And the address is still required as well although not used to set the location. (The circle centroid lat/lon and radius are ignored even if they are supplied.)

This method is useful to integrators that have polygonal boundaries for their landmarks. In this case, the specified vertices are used to establish the landmark's boundary. Then, its circle centroid lat/lon and associated radius are auto-created by creating the smallest circle possible that completely surrounds the polygon.

landmark: A Landmark object with the details for creating the landmark.
- To have a landmark inherit the company setting for pre-arrival radius pass a value of 0.
- The following fields in the Landmark object will be ignored as they are auto-filled by the system during creation:
  createTime
  createUser
  lastModTime
  lastModUser
  polygon - centroidLat
  polygon - centroidLong
- The following fields in the Landmark object cannot be set during creation and must be modified using their respective web services:
  aliases[] - can be set after creation using the Add Landmark Alias/Remove Landmark Alias web services
  attributes[] - can be set after creation using the Edit Landmark Attributes web service
  assocLandmarkNames[] - at the present time, settable only via the Services Portal UI
  assocPrimaryLandmarkName - at the present time, settable only via the Services Portal UI

Authorization Requirements

The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.

Required Application Licenses
- Remote Integration

Required User Permissions
- Can use GeoServices
- Can maintain landmarks

Customer integrators are authorized to their own company's data only.

Sample XML Request

Only the SOAP body is shown. To see a sample SOAP Envelope and Header, click here.

<soap:Body>

<createLandmark>

<companyId/>

<defineBoundaryUsing>C</defineBoundaryUsing>

<landmark>

<address>

<city>Morgantown</city>

<country>US</country>

<postalCode>19543</postalCode>

<state>PA</state>

<street>123 Main Street</street>

</address>

<aliases/>

<assocLandmarkNames/>

<assocPrimaryLandmarkName/>

<attributes/>

<circCentroidLat>40.153545</circCentroidLat>

<circCentroidLong>-75.862441</circCentroidLong>

<circRadius>0.09</circRadius>

<createTime></createTime>

<createUser></createUser>

<divisionID>RFR</divisionID>

<lastModTime></lastModTime>

<lastModUser></lastModUser>

<name>Superior Distribution Inc</name>

<preArrRadius/>25.00</preArrRadius>

<typeID>customer</typeID>

<useInProxRef>1</useInProxRef>

<polygon>

<centroidLat>0.0</centroidLat>

<centroidLong>0.0</centroidLong>

<vertices/>

</polygon>

</landmark>

</createLandmark>

</soap:Body>

Sample XML Response

<soapenv:Body>

<createLandmarkResponse/>

</soapenv:Body>

Exceptions

001 Unknown Error.
003 Company not authorized for integration.
004 User is not authorized.
005 User cannot create landmark for specified company.
006 Address city is invalid.
007 Address state/country is invalid.
008 Address postal code is invalid.
009 Address street is invalid.
010 Cannot geocode address to a valid latitude/longitude.
011 Circle centroid latitude/longitude are invalid.
012 Circle radius is invalid.
013 Division ID is invalid.
014 Name is invalid.
015 Pre-arrival radius is invalid.
016 Type ID is invalid.
017 Polygon vertices are invalid.
018 DefineBoundaryUsing is invalid.