Data/Locations/v1/Create

This endpoint is deprecated. Please see the latest version.

Creates a new location within a specified MapLayer. Optionally sets the classification, adds the new location to one or more DataFilters, creates a Relationship with other existing locations, and adds custom field values.

URL: /data/locations/v1/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
mapLayerKey	string	Yes	The ClientKey of the MapLayer in which the specified record is in.
dataFieldKey	string	Yes	The ClientKey matching the DataField in which the recordKey value will be stored. The specified DataField should be of SystemLink type.
recordKey	string	Yes	The Key for the record. If this matches an existing record in the MapLayer specified by the mapLayerKey parameter value, the request will be automatically dealt with by the edit method with the following parameters being passed through: recordKey dataFieldKey name postcode coordinates
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. See Relationship Object Properties. A collection of objects describing relationship information that is required to link the new location being created to one or more already existing locations in different MapLayers.
dataFilterKeys	string array	No	Optional. The collection of DataFilter Keys to be added to the new Location on creation.
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

Name

Type

Required

Description

recordKey

string

Yes

The key of another record to create a relationship with.

dataFieldKey

string

Yes

The ClientKey matching the DataField in which the recordKey parameter value is stored.

The specified DataField should be of SystemLink type.

DataField Object Properties

Name

Type

Required

Description

key

string

Yes

The ClientKey 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 SystemLink type, then a value greater than 100 characters will result in an error. Otherwise longer values 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:

for Yes; "Yes", "True", "1" and "Y",
for No: "No", "False", "0", and "N".

Other values will result in a "No" value being stored.

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 Filter 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 DataFilter was not found, the DataFilter was not of static type, the DataFilter was not attached to the MapLayer in which the specified record is in.
	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 DataField was not found, the DataField was not attached to the same MapLayer as the record being created, the DataField was a SystemLink and the provided value was over the 100 character limit.
	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 messaghe. For any keys returned, either: The record was not found, There was no relationship between the two MapLayers both records are within.
	Relationships could not be created. No Relationship hierarchies for the MapLayer were found.	The MapLayer of the record being created had no links to any other MapLayers. If you receive this error, see Creating a new Layer Relationship for further help.
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 recordKey provided for the new location was over 100 characters in length.
	A postcode or longitude and latitude coordinates was not provided.	Both of 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 recordKey provided is already in use for an existing Location and the mapLayerKey parameter value specified a different MapLayer to the one the existing record is on.
	The MapLayer Key provided was not suitable for Locations.	The mapLayerKey parameter value specifies a MapLayer of Area type. Locations can only be created on MapLayers of Location type.
	The DataField for the MapLayer was not set to be a SystemLink.	The dataFieldKey parameter value specifies a DataField that is not of SystemLink type.
	No link between the DataField and MapLayer was found.	The dataFieldKey parameter value specifies a DataField that is not linked to the MapLayer specified by the mapLayerKey parameter value.
	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 MapLayer specified by the mapLayerKey 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 MapLayer specified by the targetMapLayerKey parameter value.
	DataField keys are not unique.	There were duplicate DataField keys passed in the dataFields parameter array.
	Cannot pass the same DataField key used to create the record in the dataFields parameter array.	The same DataField key passed in the dataFieldKey parameter was provided 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/v1/create?apiKey=INSERT_YOUR_KEY_HERE

Body:

{
   mapLayerKey: "abc",
   dataFieldKey: "abc",
   recordKey: "abc",
   name: "abc",
   postcode: null,
   coordinates: {
      latitudeY: 0.1,
      longitudeX: 0.1
   },
   classificationKey: "abc",
   relationships: [
      {
         recordKey: "abc",
         dataFieldKey: "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".