Location Management: Update List or Point
Update a list of locations or a particular location within that list. Lists modified using this API can be used with our Distance Finder endpoint.
This endpoint requires the use of a Loqate Management key. Management keys are used to provide access to server-side functions in place of your standard API key, ensuring that were any of your keys to be scraped from a customer facing website, they could not be used to edit or delete your Location Lists. For information on how to create a Management key please see the Setting Up Store Finder Keys guide.
The Update List or Point API allows you to update an existing list created using our Create List endpoint.
When updating a list or point, any fields left null will retain their original information.
To add new points to a list, only supply the new values - the existing points will be unaffected. You can add a maximum of 100 points to an existing list per request.
Base URL
https://api.addressy.com/LocationServices/LocationManagement/UpdateListOrPoint/v1.00
Note: we don't support API connections using HTTP - all calls should use HTTPS.
JSON
https://api.addressy.com/LocationServices/LocationManagement/UpdateListOrPoint/v1.00/json4.ws?
Note: A REST endpoint with a JSON payload is the only call style supported.
Request parameters
Each request to the web service requires a number of parameters, all of which are listed below. All requests require a key which can be generated in your account.
Note: where potentially sensitive data is used in these parameters, remember to make the request as secure as possible (see the API Security page for more information).
When updating a list or point, any fields left blank will retain their original information.
* = required field
Name | Type | Example values | Description |
---|---|---|---|
Key* | String | AA11-AA11-AA11-AA11 | The Loqate Management key used to authenticate with the service. |
listID* | String | c28231fe-736b-4b50-b57b-9686afe221c2 | Unique GuID for a given list. |
listName | String | UK Stores | The name of the list being created. |
listDescription | String | A list containing all of our UK stores. | A description of the list being created. |
locations | Array of location objects |
"locations": [
{
“ID”: “443d67b0-0c81-4ba9-9e1b-21435db6ee1e",
"Name": "Point A",
"Description": "A point",
"Address": "An unstructured address",
"latitude": "51.5119437",
"longitude": "-0.1279533",
"metaInfo": { "MyValue": "SomeValue" }
},
]
|
An array of strings that is populated with information about a location. If latitude and longitude are blank then Geocoding must be set to true. |
Locations fields
Further information on the fields contained within the “locations” Array.
Note: Most of these fields are not required and exist to provide contextual information about the location if results are being displayed.
Name | Type | Example values | Description |
---|---|---|---|
Id* | String | b5733d12-1403-4a15-a292-3dcaa717d0f7 | GuID unique to a given location. If updating fields within one location this parameter is required. |
latitude* | String | 51.508930 | The WGS 84 latitude in decimal degrees format. This is mandatory unless Geocoding is set to TRUE. |
longitude* | String | -0.131387 | The WGS 84 longitude in decimal degrees format. This is mandatory unless Geocoding is set to TRUE. |
name | String | Loqate Office | Name of the location. |
description | String | Loqate’s Worcester Office | Description of the location for display purposes. |
address | String | Waterside, Basin Rd, Worcester WR5 3DA | Address of the location for display purposes. If Geocoding is set to TRUE then this parameter is mandatory. |
isoCountry | String | GB | ISO2 or ISO3 country code. If Geocoding is set to TRUE then this parameter is mandatory. |
metaInfo | Dictionary <string,string> |
"metaInfo": {"key1":"value1", "key2" : "value2", "key3" : "value3"} |
A key value pair that can be used to store any other relevant information. For example, this could be used to store contact information as “ContactNumber”:”123456789” |
Response Fields
The response from the web service is a table with the specification below. Where no items are found, the response will be empty (although all endpoints specify the columns). If an error occurs, the response will not follow this format. Instead the response will be an error table.
Name | Type | Example values | Description |
---|---|---|---|
ListID | String | b035b09f-e08f-4789-8224-0042a2dd4d36 | Automatically generated GuID used to uniquely identify a list. |
ListName | String | UK Stores | The name of the list passed in the request. |
ListDescription | String | A list containing all of our UK stores. | The description of the list passed in the request. |
Locations | Array of strings |
"locations": [
{
"Id": "65e7e2bc-3586-4c45-a18c-2979474c06b2",
"Name": "Point A",
"Description": "A point",
"Address": "An unstructured address",
"latitude": "51.5119437",
"longitude": "-0.1279533",
"metaInfo": { "MyValue": "SomeValue" }
},
]
|
An array of strings that is populated with information about a location. Also contains a uniquely generated GuID per point. |
CreatedOn | DateTime |
2023-08-24T13:41:19.251Z
|
DateTime of when the list was initially created. |
LastModifiedOn | DateTime |
2023-08-24T13:41:19.251Z
|
DateTime of when the list was last modified. |
Errors
Below are the errors which are specific to this web service. If an error occurs, an error table like the one below will be returned. To check for an error response, test for a 4-column table with columns "Error", "Description", "Cause" and "Resolution" containing a single row.
For a list of errors applicable to all APIs, have a look at the list of common errors.
Number | Description | Cause | Resolution |
---|---|---|---|
1004 | InvalidLatLong | Invalid lat or long supplied. | Check input data. |
1005 | InvalidPointName | Point supplied with no name. | Check point data. |
1006 | NoListFound | No list of that ID can be found associated with your account. | Correct ListID and try again. |
1010 | NonManagementKey | Location Management operations required a Management key. | Ensure you are using a Management key created by adding a Store Finder service to your Loqate account. |
Examples
The example below shows a request to the API along with the corresponding response.
Example Update List or Point Request
POST https://api.addressy.com/LocationServices/LocationManagement/UpdateListOrPoint/v1.00/json4.ws?
Content-Type: application/json
{
"key": "AA11-AA11-AA11-AA11",
"listId": "7bbcbea3-c995-4ed7-9be2-bfb25b3b2cef",
"listDescription": "New description",
"locations": [
{
"Id": "971558ff-c725-4b66-bfee-42e7cbb2be7f",
"Name": "Worcester Office Updated",
"Description": "An updated location of our Worcester office",
"Address": "Waterside, Basin Rd, Worcester WR5 3DA",
"latitude": "51.5119437",
"longitude": "-0.1279533",
"metaInfo": {
"ContactNumber": "01244657333"
}
}
]
}
Example Response
{
"ListId": "7bbcbea3-c995-4ed7-9be2-bfb25b3b2cef",
"ListName": "UK Offices Geocoded",
"ListDescription": "New description",
"Locations": [
{
"Id": "971558ff-c725-4b66-bfee-42e7cbb2be7f",
"Name": "Worcester Office Updated",
"Description": "An updated location of our Worcester office",
"Address": "Waterside, Basin Rd, Worcester WR5 3DA",
"Latitude": "51.5119437",
"Longitude": "-0.1279533",
"MetaInfo": {
"Contact Number": "01244657333"
}
},
{
"Id": "4ba9b14d-4fa9-4ce3-8cbf-e7b19d268720",
"Name": "Chester Office",
"Description": "Our office in Chester",
"Address": "The Foundation Business Park, Heronsway, Chester CH4 9GB",
"Latitude": "53.161261",
"Longitude": "-2.90642",
"MetaInfo": {
"Contact Number": "01244657333"
}
},
{
"Id": "a8caeada-0ed7-476e-8706-d4656ff7ee0d",
"Name": "London Office",
"Description": "Our London Office",
"Address": "128 Queen Victoria St, London EC4V 4BJ",
"Latitude": "51.51205",
"Longitude": "-0.097604",
"MetaInfo": {
"Contact Number": "02074281250"
}
}
],
"CreatedOn": "2023-09-04T11:19:27.395Z",
"LastModifiedOn": "2023-09-04T12:10:22.229Z"
}