Creates a new location within a specified Layer. Optionally sets the classification, and adds custom field values.
URL: /data/locations/v2/create
Method: POST
Method Parameters
|
Name |
Type |
Required |
Description |
|
apiKey |
string |
Yes |
The API key for your organisation. |
|
model |
object |
Yes |
The object detailing the specified values. See Model Object Properties. |
Model Object Properties
|
Name |
Type |
Required |
Description |
| layerKey |
string |
Yes |
The API key matching the Layer in which the record is to be stored. |
|
uniqueKey |
string |
Yes |
The unique key for the record. If this matches an existing record in the Layer specified by the layerKey parameter value, the request will be automatically dealt with by the edit method with the following parameters being passed through:
|
|
name |
string |
Yes |
The value for the Location’s Name. |
|
postcode |
string |
Yes * |
Optional. The postcode in which the new Location is to be positioned. Must be provided if coordinates are null. |
|
coordinates |
object |
Yes * |
Optional. See Coordinate Object Properties. The coordinates in which the new Location is to be positioned. Must be provided if the postcode is null. |
|
classificationKey |
string |
No |
Optional. The Key of the Classification to be assigned to the new Location on creation. |
|
relationships |
object array | No |
Optional. [Deprecated] |
|
dataFilterKeys |
string array |
No |
Optional. [Deprecated] |
|
dataFields |
object array |
No |
Optional. See DataField Object Properties. A collection of objects providing values that are stored within DataFields. |
* Whilst postcode and coordinates are both optional properties, at least one must be provided in order to determine a position. If both are provided, the position will be determined using the coordinates.
Coordinate Object Properties
|
Name |
Type |
Required |
Description |
|
latitudeY |
decimal |
Yes |
The value for the Latitude. Ranges from -90.0 to +90.0. |
|
longitudeX |
decimal |
Yes |
The value for the Longitude. Ranges from -180.0 to +180.0. |
Relationship Object Properties
This is deprecated. Do not use.
|
Name |
Type |
Required |
Description |
|
uniqueKey |
string |
Yes |
The unique key of another record to create a relationship with. |
|
layerKey |
string |
Yes |
The API key matching the Layer in which the record specified by this objects uniqueKey property value is stored. |
DataField Object Properties
|
Name |
Type |
Required |
Description |
|
key |
string |
Yes |
The API key matching the DataField in which to store the value. |
|
value |
string |
Yes |
The value to store in the DataField. Maximum value length of 100 characters. If the DataField is of Text type, values longer than 100 characters will be truncated. If the DataField is of Number type, the minimum value is -9,999,999,999,999.999999 and the maximum value is 9,999,999,999,999.999999. Values less or greater than this will result in an error. If the DataField is of YesNo type, acceptable values are:
Other values will result in a "No" value being stored. If the DataField is of Date type, values should be passed using the YYYY-MM-DD format. |
Response
The following responses may be returned in addition to the standard ones specified under Common Information.
|
Code |
Error Message |
Notes |
|
200 |
The request for the following DataField Key(s) could not be met: { key }, { key }, { key } |
Indicates partial success. The request was carried out successfully for all Keys provided with the exception of the Keys returned in the error message. For any keys returned, either:
|
| The request for the following DataField Key and Value combinations could not be met: [{"key":"","value":""}] |
Indicates partial success. The request was carried out successfully for all Keys provided with the exception of the Keys returned in the error message. For any keys returned, either:
|
|
| Note: You may receive more than one of the above response messages indicating partial success. | ||
|
400 |
System record limit reached. |
The maximum number of records allowed by your subscription has been reached. |
|
The Key value provided was greater than 100 characters. |
The uniqueKey provided for the new location was over 100 characters in length. |
|
|
A postcode or longitude and latitude coordinates was not provided. |
Both postcode and coordinate parameter values were null. No position can be determined for the location. |
|
|
Longitudes must range from -180.0 to 180.0. |
The longitudeX parameter value of the coordinate parameter object was out of range. |
|
|
Latitudes must range from -90.0 to 90.0. |
The latitudeY parameter value of the coordinate parameter object was out of range. |
|
|
A record with the Key provided already exists. Creating another Location with the same Key would cause a conflict. |
The uniqueKey provided is already in use for an existing Location and the layerKey parameter value specified a different Layer to the one the existing record is on. |
|
|
The Layer Key provided was not suitable for Locations. |
The layerKey parameter value specifies a Layer of Area type. Locations can only be created on Layers of Location type. |
|
|
The Classification provided was not on the same MapLayer as the Location. |
The classificationKey parameter value specifies a Classification that is not attached to the Layer specified by the layerKey parameter value. |
|
|
A location for the specified postcode could not be determined. Please provide latitude and longitude coordinates instead. |
A position for the postcode could not be determined, try specifying coordinates instead. |
|
|
The MapLayer was not attached to a Geocoding Layer. |
There is a configuration error in your system. If you wish to use the postcode parameter to position a location, you must have specified a Geocoding layer on the Layer specified by the layerKey parameter value. |
|
|
DataField keys are not unique. |
There were duplicate DataField keys passed in the dataFields parameter array. |
|
|
The number value entered was out of range. Number values must be between -9,999,999,999,999.999999 and 9,999,999,999,999.999999. |
The key parameter of a DataField object specifies a DataField of Number type. The value parameter value specified a number outside of the range this DataField type allows. |
|
Example call
URL: https://api.vision-mapping.com/data/locations/v2/create?apiKey=INSERT_YOUR_KEY_HERE
Body:
{"layerKey":"abc","uniqueKey":"abc","name":"abc","postcode":null,"coordinates":{"latitudeY":0.1,"longitudeX":0.1},"classificationKey":"abc","relationships":[{"uniqueKey":"abc","layerKey":"abc"}],"dataFilterKeys":["abc","abc1","abc2"],"dataFields":[{"key":"abc","value":"abc"}]}
Example response
Response: 200 OK
Message:
"The request for the following Filter Key(s) could not be met: abc1, abc2".
Comments
0 comments
Article is closed for comments.