Location Management: Create List

Create a list of locations that 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 Create List API allows you to create a list of locations, including their co-ordinates and their IDs. It can also store additional information such as a description of each location, opening times, and address, to provide more context.

This API also supports the use of a “metaInfo” object which can be used to store any other relevant information such as contact details, accessibility information etc.

When uploading a list, co-ordinates for each location are mandatory. If you do not have the co-ordinates of a location but have the address instead, we can geocode those for you. If the geocoding option is selected we will geocode every address in your request, any existing geocodes you send us will be overwritten.

When Geocoding a list, if a geocode cannot be found for one of your locations then the request will fail. You will not be charged, and we will outline which address(es) had caused the issue.

Please note that each address geocoded is chargeable based on your standard geocoding cost.

Geocoding supports most international locations. For a full list of coverage please see https://support.loqate.com/coverage-full/.

Base URL

https://api.addressy.com/LocationServices/LocationManagement/CreateList/v1.00

Note: we don't support API connections using HTTP - all calls should use HTTPS.

JSON

https://api.addressy.com/LocationServices/LocationManagement/CreateList/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.

* = required field

Name Type Example values Description
Key* String AA11-AA11-AA11-AA11 The Loqate Management key used to authenticate with the service.
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 strings "locations": [
        {
            "Name": "Point A",
            "Description": "A point",
            "Address": "An unstructured address",
            "latitude": "51.5119437",
            "longitude": "-0.1279533",
            "metaInfo": { "MyValue": "SomeValue" }
            "OpeningHours": {
                "Monday": {
                    "Open": "9",
                    "Close": "5",
                    "Information": "9am - 5pm"
                },
                "Tuesday": {
                    "Open": "9",
                    "Close": "5",
                    "Information": "9am - 5pm"
                },
                "Wednesday": {
                    "Open": "9",
                    "Close": "1",
                    "Information": "half day closing"
                },
                "Thursday": {
                    "Open": "9",
                    "Close": "5",
                    "Information": "9AM-5PM"
                },
                "Friday": {
                    "Open": "8",
                    "Close": "6",
                    "Information": "8am - 6pm"
                },
                "Saturday": {
                    "Open": "8",
                    "Close": "7",
                    "Information": "8am - 7pm"
                },
                "Sunday": {
                    "Open": "",
                    "Close": "",
                    "Information": "Closed"
                }
        },
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.
Geocoding Boolean TRUE/FALSE A Boolean that determines whether the addresses passed in the locations object will be geocoded. Set to FALSE by default.

 

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
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”
openingHours Object "OpeningHours": {
                "Monday": {
                    "Open": "9",
                    "Close": "5",
                    "Information": "9am - 5pm"
                },
                "Tuesday": {
                    "Open": "9",
                    "Close": "5",
                    "Information": "9am - 5pm"
                },
                "Wednesday": {
                    "Open": "9",
                    "Close": "1",
                    "Information": "half day closing"
                },
                "Thursday": {
                    "Open": "9",
                    "Close": "5",
                    "Information": "9AM-5PM"
                },
                "Friday": {
                    "Open": "8",
                    "Close": "6",
                    "Information": "8am - 6pm"
                },
                "Saturday": {
                    "Open": "8",
                    "Close": "7",
                    "Information": "8am - 7pm"
                },
                "Sunday": {
                    "Open": "",
                    "Close": "",
                    "Information": "Closed"
                }
An object containing opening hours information for the specified location. Each day can have optional Open, Close and Information fields of type String.

Back to top

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 The date and time of when the list was initially created.
LastModifiedOn DateTime 2023-08-24T13:41:19.251Z The date and time of when the list was last modified.

Back to top

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
1002 MissingListName Listname not supplied. Please supply Listname.
1003 MissingAddress Address not supplied. Please supply Address.
1004 InvalidLatLong Invalid lat or long supplied. Check input data.
1005 InvalidPointName Point supplied with no name. Check point data.
1009 ProviderFailure Internal server error. Internal server error. Please try again later.
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.

Back to top

Examples

Below are a selection of requests to the API along with the corresponding response.

Example Create List request

POST https://api.addressy.com/LocationServices/LocationManagement/CreateList/v1.00/json4.ws?
Content-Type: application/json

{
    "key":"aa11-aa11-aa11-aa11",
    "listname": "uk offices",
    "listdescription": "a list containing our uk offices",
    "geocoding": "false",
    "locations": [
        {
            "name": "worcester office",
            "description": "our office in worcester",
            "address": "waterside, basin rd, worcester wr5 3da",
            "latitude": "52.18284",
            "longitude": "-2.22194",
            "metainfo": { "contact number": "01244657333" },
            "openinghours": {
                "monday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "tuesday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "wednesday": {
                    "open": "9",
                    "close": "1",
                    "information": "half day closing"
                },
                "thursday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am-5pm"
                },
                "friday": {
                    "open": "8",
                    "close": "6",
                    "information": "8am - 6pm"
                },
                "saturday": {
                    "open": "8",
                    "close": "7",
                    "information": "8am - 7pm"
                },
                "sunday": {
                    "open": "",
                    "close": "",
                    "information": "closed"
                }
            }
        },
        {
            "name": "chester office",
            "description": "our office in chester",
            "address": "the foundation business park, heronsway, chester ch4 9gb",
            "latitude": "53.16147",
            "longitude": "-2.90621",
            "metainfo": { "contact number": "01244657333" },
            "openinghours": {
                "monday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "tuesday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "wednesday": {
                    "open": "9",
                    "close": "1",
                    "information": "half day closing"
                },
                "thursday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am-5pm"
                },
                "friday": {
                    "open": "8",
                    "close": "6",
                    "information": "8am - 6pm"
                },
                "saturday": {
                    "open": "8",
                    "close": "7",
                    "information": "8am - 7pm"
                },
                "sunday": {
                    "open": "",
                    "close": "",
                    "information": "closed"
                }
             }
        },
        {
            "name": "london office",
            "description": "our london office",
            "address": "128 queen victoria st, london ec4v 4bj",
            "latitude": "51.51209",
            "longitude": "-0.09770",
            "metainfo": { "contact number": "02074281250" },
            "openinghours": {
                "monday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "tuesday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "wednesday": {
                    "open": "9",
                    "close": "1",
                    "information": "half day closing"
                },
                "thursday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am-5pm"
                },
                "friday": {
                    "open": "8",
                    "close": "6",
                    "information": "8am - 6pm"
                },
                "saturday": {
                    "open": "8",
                    "close": "7",
                    "information": "8am - 7pm"
                },
                "sunday": {
                    "open": "",
                    "close": "",
                    "information": "closed"
                }
            }
        }
    ]
}

Example Response

{
    "listid": "bc0898aa-8303-4d1c-bf48-ff20d6a5c2ae",
    "listname": "uk offices",
    "listdescription": "a list containing our uk offices",
    "locations": [
        {
            "id": "a5b45721-f9ee-4d7f-bab3-712b2d12bb4d",
            "name": "worcester office",
            "description": "our office in worcester",
            "address": "waterside, basin rd, worcester wr5 3da",
            "latitude": "52.18284",
            "longitude": "-2.22194",
            "metainfo": {
                "contact number": "01244657333"
            },
            "openinghours": {
                "monday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "tuesday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "wednesday": {
                    "open": "9",
                    "close": "1",
                    "information": "half day closing"
                },
                "thursday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am-5pm"
                },
                "friday": {
                    "open": "8",
                    "close": "6",
                    "information": "8am - 6pm"
                },
                "saturday": {
                    "open": "8",
                    "close": "7",
                    "information": "8am - 7pm"
                },
                "sunday": {
                    "open": "",
                    "close": "",
                    "information": "closed"
                }
            }
        },
        {
            "id": "776d2ca7-70bc-4af0-8a55-ff213be1f5bd",
            "name": "chester office",
            "description": "our office in chester",
            "address": "the foundation business park, heronsway, chester ch4 9gb",
            "latitude": "53.16147",
            "longitude": "-2.90621",
            "metainfo": {
                "contact number": "01244657333"
            },
            "openinghours": {
                "monday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "tuesday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "wednesday": {
                    "open": "9",
                    "close": "1",
                    "information": "half day closing"
                },
                "thursday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am-5pm"
                },
                "friday": {
                    "open": "8",
                    "close": "6",
                    "information": "8am - 6pm"
                },
                "saturday": {
                    "open": "8",
                    "close": "7",
                    "information": "8am - 7pm"
                },
                "sunday": {
                    "open": "",
                    "close": "",
                    "information": "closed"
                }
            }
        },
        {
            "id": "e2c40ce6-b394-44fa-acf1-add027c46689",
            "name": "london office",
            "description": "our london office",
            "address": "128 queen victoria st, london ec4v 4bj",
            "latitude": "51.51209",
            "longitude": "-0.0977",
            "metainfo": {
                "contact number": "02074281250"
            },
            "openinghours": {
                "monday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "tuesday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am - 5pm"
                },
                "wednesday": {
                    "open": "9",
                    "close": "1",
                    "information": "half day closing"
                },
                "thursday": {
                    "open": "9",
                    "close": "5",
                    "information": "9am-5pm"
                },
                "friday": {
                    "open": "8",
                    "close": "6",
                    "information": "8am - 6pm"
                },
                "saturday": {
                    "open": "8",
                    "close": "7",
                    "information": "8am - 7pm"
                },
                "sunday": {
                    "open": "",
                    "close": "",
                    "information": "closed"
                }
            }
        }
    ],
    "createdon": "2023-12-14t14:30:28.343z",
    "lastmodifiedon": "2023-12-14t14:30:28.343z"
}

Back to top

Example Create List request with Geocoding

POST https://api.addressy.com/LocationServices/LocationManagement/CreateList/v1.00/json4.ws?
Content-Type: application/json


{
    "key":"AA11-AA11-AA11-AA11",
    "listName": "UK Offices Geocoded",
    "listDescription": "A List containing our UK Offices",
    "geocoding": "True",
    "locations": [
        {
            "Name": "Worcester Office",
            "Description": "Our office in Worcester",
            "Address": "Waterside, Basin Rd, Worcester WR5 3DA",
            "isoCountry": "GB",
            "metaInfo": { "Contact Number": "01244657333" }
        },
        {
            "Name": "Chester Office",
            "Description": "Our office in Chester",
            "Address": "The Foundation Business Park, Heronsway, Chester CH4 9GB",
            "isoCountry": "GB",
            "metaInfo": { "Contact Number": "01244657333" }
        },
        {
            "Name": "London Office",
            "Description": "Our London Office",
            "Address": "128 Queen Victoria St, London EC4V 4BJ",
            "isoCountry": "GB",
            "metaInfo": { "Contact Number": "02074281250" }
        }
    ]
}

 

Example Response

{
	"ListId": "7bbcbea3-c995-4ed7-9be2-bfb25b3b2cef",
	"ListName": "UK Offices Geocoded",
	"ListDescription": "A List containing our UK Offices",
	"Locations": [
		{
			"Id": "971558ff-c725-4b66-bfee-42e7cbb2be7f",
			"Name": "Worcester Office",
            "Description": "Our office in Worcester",
            "Address": "Waterside, Basin Rd, Worcester WR5 3DA",
            "Latitude": "52.182747",
            "Longitude": "-2.222145",
            "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-04T11:19:27.395Z"
}

Back to top

Get started for free today

  • No credit card required
  • Cancel any time
  • 24/7 support
Get started