Location Management: Get List

Get a list of locations to see the details of that list and the locations within it.

The Get List API allows you to view an existing list created using our Create List endpoint. 

Base URL

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

JSON

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

* = required field

Name Type Example values Description
Key* String AA11-AA11-AA11-AA11 The Loqate key used to authenticate with the service.
listID* String c28231fe-736b-4b50-b57b-9686afe221c2 Unique GuID for a given list.

When sending a request, if a listID is provided then the response will contain all of the points within that list. If no ListID is provided, the response will contain a list of the location lists associated with your account.

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 location objects
"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 objects 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.

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
1006 NoListFound No list of that ID can be found associated with your account. Correct ListID and try again.
1007 NoListsExist You have no lists associated with your account. Upload a new list to your account and try again.

Back to top

Examples

The example below shows a request to the API and the corresponding response.

Example Get List Request

GET https://api.addressy.com/LocationServices/LocationManagement/GetLists/v1.00/json4.ws?&key=AA11-AA11-AA11-AA11&listId=f0a0d848-1ffb-43e2-bf98-3025ca274832
Content-Type: application/json

Example Response

{
    "ListId": "f0a0d848-1ffb-43e2-bf98-3025ca274832",
    "ListName": "UK Offices Geocoded",
    "ListDescription": "A List containing our UK Offices",
    "Locations": [
        {
            "Id": "7715a581-2760-4325-8998-ba8aca8ce098",
            "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": "36a01354-553b-48f8-a797-1706b147426c",
            "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": "e7f85a3e-ca11-41f8-a94e-d63070cec0a0",
            "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-04T13:57:53.985Z",
    "LastModifiedOn": "2023-09-04T13:57:53.985Z"
}

Back to top

Get started for free today

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